From c3f214e5f820d298129e558d64c10e8826bf84ef Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sat, 3 Sep 2016 16:38:40 +0200 Subject: Add --omit-link-check option --- doc/cli.xhtml | 394 +++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 239 insertions(+), 155 deletions(-) (limited to 'doc/cli.xhtml') diff --git a/doc/cli.xhtml b/doc/cli.xhtml index 99c2f78..dff4fba 100644 --- a/doc/cli.xhtml +++ b/doc/cli.xhtml @@ -77,15 +77,15 @@
--version
Print version and exit.
-
--include-path|-I dir
-
Search dir for bracket-included (<>) - options files.
+
--include-path|-I dir
+
Search dir for bracket-included + (<>) options files.
-
--output-dir|-o dir
-
Write the generated files to dir instead of the current - directory.
+
--output-dir|-o dir
+
Write the generated files to dir instead of the + current directory.
-
--std version
+
--std version
Specify the C++ standard that should be used during compilation. Valid values are c++98 (default), c++11, and c++14.
@@ -113,24 +113,36 @@ argv array as well as files specified with command line options. +
--generate-vector-scanner
+
Generate the vector_scanner implementation. This scanner + is capable of reading command line arguments from + vector<string>.
+
--suppress-inline
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 +
--suppress-cli
+
Do not generate the CLI support types (scanners, parser, etc). + Normally, the support types are generated unless another + .cli was included, in which case the support types are + expected to be provided by its generated code.
+ +
--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
+
--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 +
Generate C++ code. If neither --generate-man, + --generate-html, nor + --generate-txt is specified, this mode is assumed by default.
--generate-man
@@ -139,6 +151,10 @@
--generate-html
Generate documentation in the HTML format.
+
--generate-txt
+
Generate documentation in the plain text format, similar to + usage.
+
--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 @@ -163,16 +179,17 @@ implementation the long documentation string is always used, even if the short version is provided.
-
--page-usage name
+
--page-usage name
Generate the combined usage printing code for the entire page. Specifically, this will include all the namespace-level documentation as well as usage for all the options classes printed in the order they are defined in the main translation unit (documentation/classes from included units are ignored except for base classes). -

The name argument is used as a prefix to form the name of the - usage printing function. It can include the namespace qualification as - well as documentation variable expansion, for example:

+

The name argument is used as a prefix to form the + name of the usage printing function. It can include the namespace + qualification as well as documentation variable expansion, for + example:

--page-usage print_         # print_usage() in global namespace
 --page-usage app::print_    # print_usage() in app namespace
@@ -182,18 +199,18 @@
     --short-usage options are specified, then the long
     usage function has the *long_usage() suffix.
-
--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.
+
--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.
--ansi-color
Use ANSI color escape sequences when printing usage. By "color" we really only mean the bold and underline modifiers. Note that Windows console does not recognize ANSI escape sequences and will display them as garbage. However, if you pipe such output through - less(1), it will display them correctly.
+ less(1), it will display them correctly.
--exclude-base
Exclude base class information from usage and documentation.
@@ -202,179 +219,246 @@
Include base class information after derived for usage and documentation. By default, base classes are included first.
-
--class-doc name=kind
-
Specify the documentation kind that should be used for the - options class name. The name value should be a - fully-qualified class name, for example, app::options. - The kind value can be short, - long, or exclude. If the value is - exclude, then the class documentation is excluded from - usage and man/HTML output. For usage, the short and +
--class-doc name=kind
+
Specify the documentation kind that should be used + for the options class name. The + name value should be a fully-qualified class name, for + example, app::options. The kind + value can be short, long, or + exclude. If the value is exclude, + then the class documentation is excluded from usage and man/HTML/text + output. For usage, the short and long values determine which usage function will be called when the class is used as base or as part of the page usage (see - --page-usage). For man/HTML, these values determine - which documentation strings are used in the output.
- -
--class name
-
Generate the man page or HTML documentation only for the options class - name. The name value 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.
- -
--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$ + --page-usage). For man/HTML/text, these values + determine which documentation strings are used in the output.
+ +
--class name
+
Generate the man page, HTML, or text documentation only for the + options class name. The name value + 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.
+ +
--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.
+ "\name=val" + syntax. + +
--link-regex regex
+
Add regex to the list of regular expressions used + to transform link targets in the generated documentation. The argument to + this option is a Perl-like regular expression in the form + /pattern/replacement/. Any + character can be used as a delimiter instead of '/' + and the delimiter can be escaped inside pattern and + replacement with a backslash (\). + You can specify multiple regular expressions by repeating this option. All + the regular expressions are tried in the order specified and the first + expression that matches is used. Use the + --link-regex-trace option to debug link + transformation.
+ +
--link-regex-trace
+
Trace the process of applying regular expressions specified with the + --link-regex option. Use this option to find out why + your regular expressions don't do what you expected them to do.
+ +
--html-heading-map c=h
+
Map CLI heading c (valid values: + 'H', '0', '1', + 'h', and '2') to HTML heading + h (for example, 'h1', + 'h2', etc).
+ +
--omit-link-check
+
Don't check that local fragment link references (\l{#ref ...}) resolve + to ids.
+ +
--hxx-prologue text
+
Insert text at the beginning of the generated C++ + header file.
-
--hxx-prologue text
-
Insert text at the beginning of the generated C++ header +
--ixx-prologue text
+
Insert text at the beginning of the generated C++ + inline file.
+ +
--cxx-prologue text
+
Insert text at the beginning of the generated C++ + source file.
+ +
--man-prologue text
+
Insert text at the beginning of the generated man + page file.
+ +
--html-prologue text
+
Insert text at the beginning of the generated HTML file.
-
--ixx-prologue text
-
Insert text at the beginning of the generated C++ inline +
--txt-prologue text
+
Insert text at the beginning of the generated text file.
-
--cxx-prologue text
-
Insert text at the beginning of the generated C++ source +
--hxx-epilogue text
+
Insert text at the end of the generated C++ header file.
-
--man-prologue text
-
Insert text at the beginning of the generated man page +
--ixx-epilogue text
+
Insert text at the end of the generated C++ inline file.
-
--html-prologue text
-
Insert text at the beginning of the generated HTML file.
+
--cxx-epilogue text
+
Insert text at the end of the generated C++ source + file.
-
--hxx-epilogue text
-
Insert text at the end of the generated C++ header file.
+
--man-epilogue text
+
Insert text at the end of the generated man page + file.
-
--ixx-epilogue text
-
Insert text at the end of the generated C++ inline file.
+
--html-epilogue text
+
Insert text at the end of the generated HTML + file.
-
--cxx-epilogue text
-
Insert text at the end of the generated C++ source file.
+
--txt-epilogue text
+
Insert text at the end of the generated text + file.
-
--man-epilogue text
-
Insert text at the end of the generated man page text.
+
--hxx-prologue-file file
+
Insert the content of file at the beginning of the + generated C++ header file.
-
--html-epilogue text
-
Insert text at the end of the generated HTML text.
+
--ixx-prologue-file file
+
Insert the content of file at the beginning of the + generated C++ inline file.
-
--hxx-prologue-file file
-
Insert the content of file at the beginning of the generated - C++ header file.
+
--cxx-prologue-file file
+
Insert the content of file at the beginning of the + generated C++ source file.
-
--ixx-prologue-file file
-
Insert the content of file at the beginning of the generated - C++ inline file.
+
--man-prologue-file file
+
Insert the content of file at the beginning of the + generated man page file.
-
--cxx-prologue-file file
-
Insert the content of file at the beginning of the generated - C++ source file.
+
--html-prologue-file file
+
Insert the content of file at the beginning of the + generated HTML file.
-
--man-prologue-file file
-
Insert the content of file at the beginning of the generated - man page file.
+
--txt-prologue-file file
+
Insert the content of file at the beginning of the + generated text file.
-
--html-prologue-file file
-
Insert the content of file at the beginning of the generated - HTML file.
+
--hxx-epilogue-file file
+
Insert the content of file at the end of the + generated C++ header file.
-
--hxx-epilogue-file file
-
Insert the content of file at the end of the generated C++ - header file.
+
--ixx-epilogue-file file
+
Insert the content of file at the end of the + generated C++ inline file.
-
--ixx-epilogue-file file
-
Insert the content of file at the end of the generated C++ - inline file.
+
--cxx-epilogue-file file
+
Insert the content of file at the end of the + generated C++ source file.
-
--cxx-epilogue-file file
-
Insert the content of file at the end of the generated C++ - source file.
+
--man-epilogue-file file
+
Insert the content of file at the end of the + generated man page file.
-
--man-epilogue-file file
-
Insert the content of file at the end of the generated man page - file.
+
--html-epilogue-file file
+
Insert the content of file at the end of the + generated HTML file.
-
--html-epilogue-file file
-
Insert the content of file at the end of the generated HTML - file.
+
--txt-epilogue-file file
+
Insert the content of file at the end of the + generated text file.
-
--output-prefix prefix
-
Add prefix at the beginning of the generated output file - name(s).
+
--output-prefix prefix
+
Add prefix at the beginning of the generated + output file name(s).
-
--output-suffix suffix
-
Add suffix at the end of the generated output file name(s). - Note that it is added before any file type-specific suffixes; see +
--output-suffix suffix
+
Add suffix at the end of the generated output file + name(s). Note that it is added before any file type-specific suffixes; see --*-suffix below.
-
--hxx-suffix suffix
-
Use suffix instead of the default .hxx to - construct the name of the generated header 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.
-
--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.
-
--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.
-
--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.
-
--html-suffix suffix
-
Use suffix instead of the default .html to - construct the name of the generated HTML file.
+
--txt-suffix suffix
+
Use suffix instead of the default + .txt to construct the name of the generated text + 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-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.
+
--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.
- -
--options-file file
-
Read additional options from file with each option appearing on - a separate line optionally followed by space and an option value. Empty - lines and lines starting with # are ignored. Option - values can be enclosed in double (") or single - (') quotes to preserve leading and trailing +
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.
+ +
--options-file file
+
Read additional options from file with each option + appearing on a separate line optionally followed by space and an option + value. Empty lines and lines starting with # are + ignored. Option values can be enclosed in double (") + or single (') quotes to preserve leading and trailing whitespaces as well as to specify empty values. If the value itself contains trailing or leading quotes, enclose it with an extra pair of quotes, for example '"x"'. Non-leading and -- cgit