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