diff options
Diffstat (limited to 'doc/cli.xhtml')
| -rw-r--r-- | doc/cli.xhtml | 199 |
1 files changed, 131 insertions, 68 deletions
diff --git a/doc/cli.xhtml b/doc/cli.xhtml index b026b6e..85dd4b9 100644 --- a/doc/cli.xhtml +++ b/doc/cli.xhtml @@ -59,81 +59,144 @@ <h1>DESCRIPTION</h1> - <p><code><b>cli</b></code> generates a C++ implementation for a command - line interface defined in the CLI language. For an input file in the - form <code><b>name.cli</b></code> the following C++ files are generated: + <p><code><b>cli</b></code> generates C++ implementation and + documentation in various formats for a command line interface + defined in the CLI language. For an input file in the form + <code><b>name.cli</b></code> the following is generated. By + default or if the <code><b>--generate-cxx</b></code> option is + specified, the following C++ files are generated: <code><b>name.hxx</b></code> (header file), <code><b>name.ixx</b></code> (inline file, generated unless the <code><b>--suppress-inline</b></code> - option is specified), and <code><b>name.cxx</b></code> (source file).</p> + option is specified), and <code><b>name.cxx</b></code> (source file). + If the <code><b>--generate-html</b></code> option is specified, then + the <code><b>name.html</b></code> HTML documentation file is generated. + If the <code><b>--generate-man</b></code> option is specified, then + the <code><b>name.1</b></code> man page file is generated. When + <code><b>--generate-html</b></code> or <code><b>--generate-man</b></code> + is specified, the <code><b>--stdout</b></code> option can be used to + redirect the output to STDOUT instead of a file.</p> <h1>OPTIONS</h1> - <dl class="options"> - <dt><code><b>--help</b></code></dt> - <dd>Print usage information and exit.</dd> - - <dt><code><b>--version</b></code></dt> - <dd>Print version and exit.</dd> - - <dt><code><b>--output-dir</b> | <b>-o</b> <i>dir</i></code></dt> - <dd>Write generated files to <code><i>dir</i></code> instead of - the current directory.</dd> - - <dt><code><b>--suppress-inline</b></code></dt> - <dd>Generate all functions non-inline. By default simple functions - are made inline. This option suppresses creation of the inline - file.</dd> - - <dt><code><b>--hxx-suffix</b> <i>suffix</i></code></dt> - <dd>Use the provided <code><i>suffix</i></code> instead of the default - <code><b>.hxx</b></code> to construct the name of the generated header - file.</dd> - - <dt><code><b>--ixx-suffix</b> <i>suffix</i></code></dt> - <dd>Use the provided <code><i>suffix</i></code> instead of the default - <code><b>.ixx</b></code> to construct the name of the generated inline - file.</dd> - - <dt><code><b>--cxx-suffix</b> <i>suffix</i></code></dt> - <dd>Use the provided <code><i>suffix</i></code> instead of the default - <code><b>.cxx</b></code> to construct the name of the generated source - file.</dd> - - <dt><code><b>--option-prefix</b> <i>prefix</i></code></dt> - <dd>Use the provided <code><i>prefix</i></code> instead of the default - <code><b>-</b></code> as an option prefix. Unknown command line - arguments that start with this prefix are treated as unknown options. - If you set the option prefix to the empty value, then all the unknown - command line arguments will be treated as program arguments.</dd> - - <dt><code><b>--option-separator</b> <i>separator</i></code></dt> - <dd>Use the provided <code><i>separator</i></code> instead of the default - <code><b>--</b></code> as an optional separator between options and - arguments. All the command line arguments that are parsed after this - separator are treated as program arguments. Set the option separator - to the empty value if you don't want this functionality.</dd> - - <dt><code><b>--include-with-brackets</b></code></dt> - <dd>Use angle brackets (<>) instead of quotes ("") in generated - <code><b>#include</b></code> directives.</dd> - - <dt><code><b>--include-prefix</b> <i>prefix</i></code></dt> - <dd>Add <code><i>prefix</i></code> to generated <code><b>#include</b></code> - directive paths.</dd> - - <dt><code><b>--guard-prefix</b> <i>prefix</i></code></dt> - <dd>Add <code><i>prefix</i></code> to generated header inclusion guards. - The prefix is transformed to upper case and characters that are - illegal in a preprocessor macro name are replaced with underscores.</dd> - - <dt><code><b>--reserved-name</b> <i>name</i>[<b>=</b><i>rep</i>]</code></dt> - <dd>Add <code><i>name</i></code> to the list of names that should not - be used as identifiers. The name can optionally be followed by - <code><b>=</b></code> and the replacement name that should be - used instead. All C++ keywords are already in this list.</dd> +<!-- + The following documentation was generated by CLI, a command + line interface compiler for C++. +--> - </dl> +<dl class="options"> + <dt><code><b>--help</b></code></dt> + <dd>Print usage information and exit.</dd> + <dt><code><b>--version</b></code></dt> + <dd>Print version and exit.</dd> + + <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <i>dir</i></dt> + <dd>Write the generated files to <i>dir</i> instead of the current directory.</dd> + + <dt><code><b>--suppress-inline</b></code></dt> + <dd>Generate all functions non-inline. By default simple functions are made + inline. This option suppresses creation of the inline file.</dd> + + <dt><code><b>--suppress-usage</b></code></dt> + <dd>Suppress the generation of the usage printing code.</dd> + + <dt><code><b>--long-usage</b></code></dt> + <dd>If no short documentation string is provided, use the complete long + documentation string in usage. By default, in this situation only the first + sentence from the long string is used.</dd> + + <dt><code><b>--option-length</b></code> <i>len</i></dt> + <dd>Indent option descriptions <i>len</i> characters when printing usage. This + is useful when you have multiple options classes, potentially in separate + files, and would like their usage to have the same indentation level.</dd> + + <dt><code><b>--generate-cxx</b></code></dt> + <dd>Generate C++ code. If neither <code><b>--generate-man</b></code> nor + <code><b>--generate-html</b></code> is specified, this mode is assumed by + default.</dd> + + <dt><code><b>--generate-man</b></code></dt> + <dd>Generate documentation in the man page format.</dd> + + <dt><code><b>--generate-html</b></code></dt> + <dd>Generate documentation in the HTML format.</dd> + + <dt><code><b>--man-prologue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the man page file.</dd> + + <dt><code><b>--man-epilogue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the man page file.</dd> + + <dt><code><b>--html-prologue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the HTML file.</dd> + + <dt><code><b>--html-epilogue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the HTML file.</dd> + + <dt><code><b>--class</b></code> <i>fq-name</i></dt> + <dd>Generate the man page or HTML documentation only for the <i>fq-name</i> + options class. The <i>fq-name</i> name should be a fully-qualified options + class name, for example, <code><b>app::options</b></code>. This + functionality is useful if you need to insert custom documentation between + options belonging to different classes.</dd> + + <dt><code><b>--stdout</b></code></dt> + <dd>Write output to STDOUT instead of a file. This option is not valid when + generating C++ code and is normally used to combine generated documentation + for several option classes in a single file.</dd> + + <dt><code><b>--hxx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.hxx</b></code> to + construct the name of the generated header file.</dd> + + <dt><code><b>--ixx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.ixx</b></code> to + construct the name of the generated inline file.</dd> + + <dt><code><b>--cxx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.cxx</b></code> to + construct the name of the generated source file.</dd> + + <dt><code><b>--man-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.1</b></code> to construct + the name of the generated man page file.</dd> + + <dt><code><b>--html-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.html</b></code> to + construct the name of the generated HTML file.</dd> + + <dt><code><b>--option-prefix</b></code> <i>prefix</i></dt> + <dd>Use <i>prefix</i> instead of the default <code><b>-</b></code> as an option + prefix. Unknown command line arguments that start with this prefix are + treated as unknown options. If you set the option prefix to the empty value, + then all the unknown command line arguments will be treated as program + arguments.</dd> + + <dt><code><b>--option-separator</b></code> <i>sep</i></dt> + <dd>Use <i>sep</i> instead of the default <code><b>--</b></code> as an optional + separator between options and arguments. All the command line arguments that + are parsed after this separator are treated as program arguments. Set the + option separator to the empty value if you don't want this functionality.</dd> + + <dt><code><b>--include-with-brackets</b></code></dt> + <dd>Use angle brackets (<>) instead of quotes ("") in the generated + <code><b>#include</b></code> directives.</dd> + + <dt><code><b>--include-prefix</b></code> <i>prefix</i></dt> + <dd>Add <i>prefix</i> to the generated <code><b>#include</b></code> directive + paths.</dd> + + <dt><code><b>--guard-prefix</b></code> <i>prefix</i></dt> + <dd>Add <i>prefix</i> to the generated header inclusion guards. The prefix is + transformed to upper case and characters that are illegal in a preprocessor + macro name are replaced with underscores.</dd> + + <dt><code><b>--reserved-name</b></code> <i>name</i>=<i>rep</i></dt> + <dd>Add <i>name</i> with an optional <i>rep</i> replacement to the list of names + that should not be used as identifiers. If provided, the replacement name is + used instead. All C++ keywords are already in this list.</dd> + +</dl> <h1>DIAGNOSTICS</h1> <p>If the input file is not a valid CLI definition, <code><b>cli</b></code> |