From 5a2da5767e796bcfdaf5ebf3b80b93c57d31d0aa Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 16 Nov 2015 11:43:19 +0200 Subject: Support specifying documentation variables on command line --- doc/cli.1 | 59 ++++++++++++++++++++++++---------------------- doc/cli.xhtml | 75 +++++++++++++++++++++++++++++++---------------------------- 2 files changed, 70 insertions(+), 64 deletions(-) (limited to 'doc') diff --git a/doc/cli.1 b/doc/cli.1 index 8cc15a7..bd12cad 100644 --- a/doc/cli.1 +++ b/doc/cli.1 @@ -57,10 +57,6 @@ option can be used to redirect the output to STDOUT instead of a file. .\"-------------------------------------------------------------------- .SH OPTIONS .\"-------------------------------------------------------------------- -.\" -.\" 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" @@ -87,9 +83,25 @@ with command line options\. .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--cli-namespace\fP \fIns\fP" +Generate the CLI support types in the \fIns\fP namespace (\fBcli\fP by +default)\. The namespace can be nested, for example \fBdetails::cli\fP\. If +the namespace is empty, then the support types are generated in the global +namespace\. .IP "\fB--ostream-type\fP \fItype\fP" Output stream type instead of the default \fBstd::ostream\fP that should be used to print usage and exception information\. +.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--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--suppress-undocumented\fP" Suppress the generation of documentation entries for undocumented options\. .IP "\fB--suppress-usage\fP" @@ -110,18 +122,21 @@ useful when you have multiple options classes, potentially in separate files, and would like their usage to have the same indentation level\. .IP "\fB--exclude-base\fP" Exclude base class information from usage and documentation\. -.IP "\fB--cli-namespace\fP \fIns\fP" -Generate the CLI support types in the \fIns\fP namespace (\fBcli\fP by -default)\. The namespace can be nested, for example \fBdetails::cli\fP\. If -the namespace is empty, then the support types are generated in the global -namespace\. -.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--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\. To generate documentation for multiple +classes, repeat this option and the documentation will be produced in the +order specified\. This functionality is useful if you need to assemble +documentation from multiple classes in a specific order or to insert custom +documentation between options belonging to different classes\. +.IP "\fB--docvar\fP|\fB-v\fP \fIname\fP=\fIval\fP" +Set documentation variable \fIname\fP to the value \fIval\fP\. Documentation +variables can be substituted in prologues and epilogues (see +\fB--*-prologue*\fP and \fB--*-epilogue*\fP options) using the +\fB$\fP\fIname\fP\fB$\fP expansion syntax (use \fB$$\fP to escape expansion)\. +They can also be defined in \fB\.cli\fP files using the +"\e\fIname\fP=\fIval\fP" syntax\. .IP "\fB--hxx-prologue\fP \fItext\fP" Insert \fItext\fP at the beginning of the generated C++ header file\. .IP "\fB--ixx-prologue\fP \fItext\fP" @@ -166,18 +181,6 @@ Insert the content of \fIfile\fP at the end of the generated C++ source file\. Insert the content of \fIfile\fP at the end of the generated man page file\. .IP "\fB--html-epilogue-file\fP \fIfile\fP" Insert the content of \fIfile\fP at the end of the generated 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\. To generate documentation for multiple -classes, repeat this option and the documentation will be produced in the -order specified\. This functionality is useful if you need to assemble -documentation from multiple classes in a specific order or 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\. diff --git a/doc/cli.xhtml b/doc/cli.xhtml index 896f237..e2baa6b 100644 --- a/doc/cli.xhtml +++ b/doc/cli.xhtml @@ -70,12 +70,6 @@ redirect the output to STDOUT instead of a file.

OPTIONS

- - -
--help
Print usage information and exit.
@@ -118,11 +112,33 @@
Generate all functions non-inline. By default simple functions are made inline. This option suppresses creation of the inline file.
+
--cli-namespace ns
+
Generate the CLI support types in the ns namespace + (cli by default). The namespace can be nested, for + example details::cli. If the namespace is empty, then + the support types are generated in the global namespace.
+
--ostream-type type
Output stream type instead of the default std::ostream that should be used to print usage and exception information.
+
--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.
+ +
--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.
+
--suppress-undocumented
Suppress the generation of documentation entries for undocumented options.
@@ -152,22 +168,24 @@
--exclude-base
Exclude base class information from usage and documentation.
-
--cli-namespace ns
-
Generate the CLI support types in the ns namespace - (cli by default). The namespace can be nested, for - example details::cli. If the namespace is empty, then - the support types are generated in the global namespace.
- -
--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.
+
--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. To generate documentation for multiple + classes, repeat this option and the documentation will be produced in the + order specified. This functionality is useful if you need to assemble + documentation from multiple classes in a specific order or to insert + custom documentation between options belonging to different classes.
-
--generate-html
-
Generate documentation in the HTML format.
+
--docvar|-v name=val
+
Set documentation variable name to the value val. + Documentation variables can be substituted in prologues and epilogues (see + --*-prologue* and --*-epilogue* + options) using the $name$ + expansion syntax (use $$ to escape expansion). They + can also be defined in .cli files using the + "\name=val" syntax.
--hxx-prologue text
Insert text at the beginning of the generated C++ header @@ -243,21 +261,6 @@
Insert the content of file at the end of the generated 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. To generate documentation for multiple - classes, repeat this option and the documentation will be produced in the - order specified. This functionality is useful if you need to assemble - documentation from multiple classes in a specific order or 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.
-- cgit v1.1