From 5f7743da2fa5791e624b41ea1a749ccfa58a8f53 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 30 Oct 2015 10:47:45 +0200 Subject: Implement scope documentation generation in HTML --- doc/cli-prologue.xhtml | 15 +- doc/cli.xhtml | 480 +++++++++++++++++++++++++------------------------ 2 files changed, 248 insertions(+), 247 deletions(-) (limited to 'doc') diff --git a/doc/cli-prologue.xhtml b/doc/cli-prologue.xhtml index b9e2f30..88d1e6b 100644 --- a/doc/cli-prologue.xhtml +++ b/doc/cli-prologue.xhtml @@ -21,23 +21,16 @@ padding-bottom : 0.0em; } - #commands dt { - padding-top : 0.4em; - } - - #commands dd { - padding-bottom : 0.4em; - padding-left : 2em; + .options { + margin: 1em 0 1em 0; } .options dt { - padding-top : 0.4em; + margin: 1em 0 0 0; } .options dd { - padding-top : 0.1em; - padding-bottom : 0.4em; - padding-left : 1.4em; + margin: .1em 0 0 4.5em; } diff --git a/doc/cli.xhtml b/doc/cli.xhtml index 1e905bc..896f237 100644 --- a/doc/cli.xhtml +++ b/doc/cli.xhtml @@ -21,23 +21,16 @@ padding-bottom : 0.0em; } - #commands dt { - padding-top : 0.4em; - } - - #commands dd { - padding-bottom : 0.4em; - padding-left : 2em; + .options { + margin: 1em 0 1em 0; } .options dt { - padding-top : 0.4em; + margin: 1em 0 0 0; } .options dd { - padding-top : 0.1em; - padding-bottom : 0.4em; - padding-left : 1.4em; + margin: .1em 0 0 4.5em; } @@ -83,244 +76,259 @@ line interface compiler for C++. --> -
-
--help
-
Print usage information and exit.
- -
--version
-
Print version and exit.
- -
--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.
- -
--generate-modifier
-
Generate option value modifiers in addition to accessors.
- -
--generate-specifier
-
Generate functions for determining whether the option was specified on the - command line.
- -
--generate-parse
-
Generate parse() functions instead of parsing - constructors. This is primarily useful for being able to parse into an - already initialized options class instance, for example, to implement - merging/overriding.
- -
--generate-description
-
Generate the option description list that can be examined at runtime.
+
+
--help
+
Print usage information and exit.
+ +
--version
+
Print version and exit.
+ +
--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.
+ +
--generate-modifier
+
Generate option value modifiers in addition to accessors.
-
--generate-file-scanner
-
Generate the argv_file_scanner implementation. This scanner is - capable of reading command line arguments from the argv array - as well as files specified with command line options.
+
--generate-specifier
+
Generate functions for determining whether the option was specified on + the command line.
-
--suppress-inline
-
Generate all functions non-inline. By default simple functions are made - inline. This option suppresses creation of the inline file.
+
--generate-parse
+
Generate parse() functions instead of parsing + constructors. This is primarily useful for being able to parse into an + already initialized options class instance, for example, to implement + merging/overriding.
-
--ostream-type type
-
Output stream type instead of the default std::ostream - that should be used to print usage and exception information.
+
--generate-description
+
Generate the option description list that can be examined at + runtime.
-
--suppress-undocumented
-
Suppress the generation of documentation entries for undocumented options.
+
--generate-file-scanner
+
Generate the argv_file_scanner implementation. This + scanner is capable of reading command line arguments from the + argv array as well as files specified with command line + options.
-
--suppress-usage
-
Suppress the generation of the usage printing code.
+
--suppress-inline
+
Generate all functions non-inline. By default simple functions are + made inline. This option suppresses creation of the inline file.
-
--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.
+
--ostream-type type
+
Output stream type instead of the default + std::ostream that should be used to print usage and + exception information.
-
--short-usage
-
If specified together with --long-usage, generate both - short and long usage versions. In this mode, the usage printing functions - are called print_short_usage() and - print_long_usage() and for the long usage the long - documentation string is always used, even if the short version is provided.
+
--suppress-undocumented
+
Suppress the generation of documentation entries for undocumented + options.
-
--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.
+
--suppress-usage
+
Suppress the generation of the usage printing code.
-
--exclude-base
-
Exclude base class information from usage and documentation.
+
--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.
-
--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.
+
--short-usage
+
If specified together with --long-usage, generate + both short and long usage versions. In this mode, the usage printing + functions are called print_short_usage() and + print_long_usage() and for the long usage the long + documentation string is always used, even if the short version is + provided.
-
--generate-cxx
-
Generate C++ code. If neither --generate-man nor - --generate-html is specified, this mode is assumed by - default.
+
--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.
+ +
--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.
+ +
--generate-html
+
Generate documentation in the HTML format.
+ +
--hxx-prologue text
+
Insert text at the beginning of the generated C++ header + file.
+ +
--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.
+ +
--hxx-epilogue text
+
Insert text at the end of the generated C++ header file.
+ +
--ixx-epilogue text
+
Insert text at the end of the generated C++ inline file.
+ +
--cxx-epilogue text
+
Insert text at the end of the generated C++ source file.
+ +
--man-epilogue text
+
Insert text at the end of the generated man page text.
+ +
--html-epilogue text
+
Insert text at the end of the generated HTML text.
+ +
--hxx-prologue-file file
+
Insert the content of file at the beginning of the generated + C++ header file.
+ +
--ixx-prologue-file file
+
Insert the content of file at the beginning of the generated + C++ inline file.
+ +
--cxx-prologue-file file
+
Insert the content of file at the beginning of the generated + C++ source file.
+ +
--man-prologue-file file
+
Insert the content of file at the beginning of the generated + man page 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.
+ +
--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.
+ +
--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.
+ +
--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.
+ +
--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.
+ +
--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 + non-trailing quotes are interpreted as being part of the option value. + +

The semantics of providing options in a file is equivalent to providing + the same set of options in the same order on the command line at the point + where the --options-file option is specified except + that the shell escaping and quoting is not required. Repeat this option to + specify more than one options file.

-
--generate-man
-
Generate documentation in the man page format.
- -
--generate-html
-
Generate documentation in the HTML format.
- -
--hxx-prologue text
-
Insert text at the beginning of the generated C++ header file.
- -
--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.
- -
--hxx-epilogue text
-
Insert text at the end of the generated C++ header file.
- -
--ixx-epilogue text
-
Insert text at the end of the generated C++ inline file.
- -
--cxx-epilogue text
-
Insert text at the end of the generated C++ source file.
+
-
--man-epilogue text
-
Insert text at the end of the generated man page text.
- -
--html-epilogue text
-
Insert text at the end of the generated HTML text.
- -
--hxx-prologue-file file
-
Insert the content of file at the beginning of the generated C++ - header file.
- -
--ixx-prologue-file file
-
Insert the content of file at the beginning of the generated C++ - inline file.
- -
--cxx-prologue-file file
-
Insert the content of file at the beginning of the generated C++ - source file.
- -
--man-prologue-file file
-
Insert the content of file at the beginning of the generated man page - 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.
- -
--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.
- -
--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.
- -
--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.
- -
--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.
- -
--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 non-trailing quotes are - interpreted as being part of the option value. - -

The semantics of providing options in a file is equivalent to providing - the same set of options in the same order on the command line at the point - where the --options-file option is specified except that - the shell escaping and quoting is not required. Repeat this option to - specify more than one options file.

- -

DIAGNOSTICS

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