diff options
Diffstat (limited to 'doc/cli.1')
| -rw-r--r-- | doc/cli.1 | 223 |
1 files changed, 134 insertions, 89 deletions
@@ -22,10 +22,13 @@ cli \- command line interface compiler for C++ .SH DESCRIPTION .\"-------------------------------------------------------------------- .B cli -generates a C++ implementation for a command line interface defined in the CLI -language. For an input file in the form +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 .B name.cli -the following C++ files are generated: +the following is generated. By default or if the +.B --generate-cxx +option is specified, the following C++ files are generated: .B name.hxx (header file), .B name.ixx @@ -33,95 +36,139 @@ the following C++ files are generated: .B --suppress-inline option is specified), and .B name.cxx (source file). +If the +.B --generate-html +option is specified, then the +.B name.html +HTML documentation file is generated. If the +.B --generate-man +option is specified, then the +.B name.1 +man page file is generated. When +.B --generate-html +or +.B --generate-man +is specified, the +.B --stdout +option can be used to redirect the output to STDOUT instead of a file. .\" .\" .\" .\"-------------------------------------------------------------------- .SH OPTIONS .\"-------------------------------------------------------------------- -.IP "\fB\--help\fR" -Print usage information and exit. - -.IP "\fB\--version\fR" -Print version and exit. - -.IP "\fB\--output-dir\fR | \fB\-o \fIdir\fR" -Write generated files to -.I dir -instead of the current directory. - -.IP "\fB\--suppress-inline\fR" -Generate all functions non-inline. By default simple functions are made -inline. This option suppresses creation of the inline file. - -.IP "\fB\--hxx-suffix \fIsuffix\fR" -Use the provided -.I suffix -instead of the default -.B .hxx -to construct the name of the generated header file. - -.IP "\fB\--ixx-suffix \fIsuffix\fR" -Use the provided -.I suffix -instead of the default -.B .ixx -to construct the name of the generated inline file. - -.IP "\fB\--cxx-suffix \fIsuffix\fR" -Use the provided -.I suffix -instead of the default -.B .cxx -to construct the name of the generated source file. - -.IP "\fB\--option-prefix \fIprefix\fR" -Use the provided -.I prefix -instead of the default -.B - -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. - -.IP "\fB\--option-separator \fIseparator\fR" -Use the provided -.I separator -instead of the default -.B -- -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. - -.IP "\fB\--include-with-brackets\fR" -Use angle brackets (<>) instead of quotes ("") in generated -.B #include -directives. - -.IP "\fB\--include-prefix \fIprefix\fR" -Add -.I prefix -to generated -.B #include -directive paths. - -.IP "\fB\--guard-prefix \fIprefix\fR" -Add -.I prefix -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. - -.IP "\fB\--reserved-name \fIname\fR[\fB=\fIrep\fR]" -Add -.I name -to the list of names that should not be used as identifiers. The name -can optionally be followed by -.B = -and the replacement name that should be used instead. All C++ keywords -are already in this list. +.\" +.\" The following documentation was generated by CLI, a command +.\" line interface compiler for C++. +.\" +.IP "\fB--help\fP" +Print usage information and exit\. + +.IP "\fB--version\fP" +Print version and exit\. + +.IP "\fB--output-dir\fP|\fB-o\fP \fIdir\fP" +Write the generated files to \fIdir\fP instead of the current directory\. + +.IP "\fB--suppress-inline\fP" +Generate all functions non-inline\. By default simple functions are made +inline\. This option suppresses creation of the inline file\. + +.IP "\fB--suppress-usage\fP" +Suppress the generation of the usage printing code\. + +.IP "\fB--long-usage\fP" +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\. + +.IP "\fB--option-length\fP \fIlen\fP" +Indent option descriptions \fIlen\fP 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\. + +.IP "\fB--generate-cxx\fP" +Generate C++ code\. If neither \fB--generate-man\fP nor +\fB--generate-html\fP is specified, this mode is assumed by default\. + +.IP "\fB--generate-man\fP" +Generate documentation in the man page format\. + +.IP "\fB--generate-html\fP" +Generate documentation in the HTML format\. + +.IP "\fB--man-prologue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the beginning of the man page file\. + +.IP "\fB--man-epilogue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the end of the man page file\. + +.IP "\fB--html-prologue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the beginning of the HTML file\. + +.IP "\fB--html-epilogue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the end of the HTML file\. + +.IP "\fB--class\fP \fIfq-name\fP" +Generate the man page or HTML documentation only for the \fIfq-name\fP +options class\. The \fIfq-name\fP name should be a fully-qualified options +class name, for example, \fBapp::options\fP\. This functionality is useful +if you need to insert custom documentation between options belonging to +different classes\. + +.IP "\fB--stdout\fP" +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\. + +.IP "\fB--hxx-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.hxx\fP to construct the name of +the generated header file\. + +.IP "\fB--ixx-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.ixx\fP to construct the name of +the generated inline file\. + +.IP "\fB--cxx-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.cxx\fP to construct the name of +the generated source file\. + +.IP "\fB--man-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.1\fP to construct the name of +the generated man page file\. + +.IP "\fB--html-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.html\fP to construct the name +of the generated HTML file\. + +.IP "\fB--option-prefix\fP \fIprefix\fP" +Use \fIprefix\fP instead of the default \fB-\fP 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\. + +.IP "\fB--option-separator\fP \fIsep\fP" +Use \fIsep\fP instead of the default \fB--\fP 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\. + +.IP "\fB--include-with-brackets\fP" +Use angle brackets (<>) instead of quotes ("") in the generated +\fB#include\fP directives\. + +.IP "\fB--include-prefix\fP \fIprefix\fP" +Add \fIprefix\fP to the generated \fB#include\fP directive paths\. + +.IP "\fB--guard-prefix\fP \fIprefix\fP" +Add \fIprefix\fP 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\. + +.IP "\fB--reserved-name\fP \fIname\fP=\fIrep\fP" +Add \fIname\fP with an optional \fIrep\fP 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\. .\" .\" DIAGNOSTICS @@ -129,9 +176,7 @@ are already in this list. .SH DIAGNOSTICS If the input file is not a valid CLI definition, .B cli -will issue diagnostic messages to -.B STDERR -and exit with non-zero exit code. +will issue diagnostic messages to STDERR and exit with non-zero exit code. .\" .\" BUGS .\" |