From 0e56fe29a9afeee00e02e722496678df89d37d50 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 17 Nov 2009 13:59:39 +0200 Subject: Complete the implementation of the option documentation Add the man page generator. Port CLI usage, HTML documentation and the man page to the auto-generated version. Update examples and documentation. --- doc/cli.xhtml | 199 ++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 131 insertions(+), 68 deletions(-) (limited to 'doc/cli.xhtml') 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 @@

DESCRIPTION

-

cli generates a C++ implementation for a command - line interface defined in the CLI language. For an input file in the - form name.cli the following C++ files are generated: +

cli 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 + name.cli the following is generated. By + default or if the --generate-cxx option is + specified, the following C++ files are generated: name.hxx (header file), name.ixx (inline file, generated unless the --suppress-inline - option is specified), and name.cxx (source file).

+ option is specified), and name.cxx (source file). + If the --generate-html option is specified, then + the name.html HTML documentation file is generated. + If the --generate-man option is specified, then + the name.1 man page file is generated. When + --generate-html or --generate-man + is specified, the --stdout option can be used to + redirect the output to STDOUT instead of a file.

OPTIONS

-
-
--help
-
Print usage information and exit.
- -
--version
-
Print version and exit.
- -
--output-dir | -o dir
-
Write generated files to dir instead of - the current directory.
- -
--suppress-inline
-
Generate all functions non-inline. By default simple functions - are made inline. This option suppresses creation of the inline - file.
- -
--hxx-suffix suffix
-
Use the provided suffix instead of the default - .hxx to construct the name of the generated header - file.
- -
--ixx-suffix suffix
-
Use the provided suffix instead of the default - .ixx to construct the name of the generated inline - file.
- -
--cxx-suffix suffix
-
Use the provided suffix instead of the default - .cxx to construct the name of the generated source - file.
- -
--option-prefix prefix
-
Use the provided prefix instead of the default - - 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.
- -
--option-separator separator
-
Use the provided separator instead of the default - -- 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.
- -
--include-with-brackets
-
Use angle brackets (<>) instead of quotes ("") in generated - #include directives.
- -
--include-prefix prefix
-
Add prefix to generated #include - directive paths.
- -
--guard-prefix prefix
-
Add 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.
- -
--reserved-name name[=rep]
-
Add name to the list of names that should not - be used as identifiers. The name can optionally be followed by - = and the replacement name that should be - used instead. All C++ keywords are already in this list.
+ -
+
+
--help
+
Print usage information and exit.
+
--version
+
Print version and exit.
+ +
--output-dir|-o dir
+
Write the generated files to dir instead of the current directory.
+ +
--suppress-inline
+
Generate all functions non-inline. By default simple functions are made + inline. This option suppresses creation of the inline file.
+ +
--suppress-usage
+
Suppress the generation of the usage printing code.
+ +
--long-usage
+
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.
+ +
--option-length len
+
Indent option descriptions len 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.
+ +
--generate-cxx
+
Generate C++ code. If neither --generate-man nor + --generate-html is specified, this mode is assumed by + default.
+ +
--generate-man
+
Generate documentation in the man page format.
+ +
--generate-html
+
Generate documentation in the HTML format.
+ +
--man-prologue file
+
Insert the content of file at the beginning of the man page file.
+ +
--man-epilogue file
+
Insert the content of file at the end of the man page file.
+ +
--html-prologue file
+
Insert the content of file at the beginning of the HTML file.
+ +
--html-epilogue file
+
Insert the content of file at the end of the HTML file.
+ +
--class fq-name
+
Generate the man page or HTML documentation only for the fq-name + options class. The fq-name name should be a fully-qualified options + class name, for example, app::options. This + functionality is useful if you need to insert custom documentation between + options belonging to different classes.
+ +
--stdout
+
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.
+ +
--hxx-suffix suffix
+
Use suffix instead of the default .hxx to + construct the name of the generated header file.
+ +
--ixx-suffix suffix
+
Use suffix instead of the default .ixx to + construct the name of the generated inline file.
+ +
--cxx-suffix suffix
+
Use suffix instead of the default .cxx to + construct the name of the generated source file.
+ +
--man-suffix suffix
+
Use suffix instead of the default .1 to construct + the name of the generated man page file.
+ +
--html-suffix suffix
+
Use suffix instead of the default .html to + construct the name of the generated HTML file.
+ +
--option-prefix prefix
+
Use prefix instead of the default - 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.
+ +
--option-separator sep
+
Use sep instead of the default -- 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.
+ +
--include-with-brackets
+
Use angle brackets (<>) instead of quotes ("") in the generated + #include directives.
+ +
--include-prefix prefix
+
Add prefix to the generated #include directive + paths.
+ +
--guard-prefix prefix
+
Add prefix 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.
+ +
--reserved-name name=rep
+
Add name with an optional rep 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

If the input file is not a valid CLI definition, cli -- cgit