summaryrefslogtreecommitdiff
path: root/doc/cli.1
diff options
context:
space:
mode:
Diffstat (limited to 'doc/cli.1')
-rw-r--r--doc/cli.1223
1 files changed, 134 insertions, 89 deletions
diff --git a/doc/cli.1 b/doc/cli.1
index 80e3bc6..2e9f180 100644
--- a/doc/cli.1
+++ b/doc/cli.1
@@ -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
.\"