diff options
| -rw-r--r-- | cli/context.cxx | 7 | ||||
| -rw-r--r-- | cli/context.hxx | 4 | ||||
| -rw-r--r-- | cli/html.cxx | 203 | ||||
| -rw-r--r-- | cli/man.cxx | 4 | ||||
| -rw-r--r-- | cli/semantics/elements.hxx | 6 | ||||
| -rw-r--r-- | cli/source.cxx | 6 | ||||
| -rw-r--r-- | doc/cli-prologue.xhtml | 15 | ||||
| -rw-r--r-- | doc/cli.xhtml | 480 |
8 files changed, 380 insertions, 345 deletions
diff --git a/cli/context.cxx b/cli/context.cxx index 1324b0c..332c22e 100644 --- a/cli/context.cxx +++ b/cli/context.cxx @@ -315,12 +315,13 @@ translate (string const& s, std::set<string> const& set) } string context:: -format (string const& s, output_type ot) +format (output_type ot, string const& s, bool para) { string r; - r.reserve (s.size ()); - bool para (false); + if (para && ot == ot_html) + r += "<p>"; + bool escape (false); std::stack<unsigned char> blocks; // Bit 0: code; 1: italic; 2: bold. diff --git a/cli/context.hxx b/cli/context.hxx index b6ce420..6eeaa3b 100644 --- a/cli/context.hxx +++ b/cli/context.hxx @@ -93,8 +93,10 @@ public: static string translate (string const&, std::set<string> const&); + // If para is true, start a new paragraph. + // static string - format (string const&, output_type); + format (output_type, string const&, bool para); public: static string const& diff --git a/cli/html.cxx b/cli/html.cxx index 1679fd3..dd49a91 100644 --- a/cli/html.cxx +++ b/cli/html.cxx @@ -12,6 +12,98 @@ using namespace std; namespace { + static string + escape_html (string const& s) + { + string r; + r.reserve (s.size ()); + + for (size_t i (0), n (s.size ()); i < n; ++i) + { + switch (s[i]) + { + case '<': + { + r += "<"; + break; + } + case '&': + { + r += "&"; + break; + } + default: + { + r += s[i]; + break; + } + } + } + + return r; + } + + static void + wrap_lines (ostream& os, const string& d, size_t indent) + { + assert (!d.empty ()); + + size_t lim (78 - indent); + string ind (indent, ' '); + + size_t b (0), e (0), i (0); + + for (size_t n (d.size ()); i < n; ++i) + { + if (d[i] == ' ' || d[i] == '\n') + e = i; + + if (d[i] == '\n' || (i - b >= lim && e != b)) + { + os << (b != 0 ? "\n" : "") << ind << string (d, b, e - b); + + if (d[i] == '\n') + os << endl; + + b = e = e + 1; + } + } + + // Write the last line. + // + if (b != i) + os << (b != 0 ? "\n" : "") << ind << string (d, b, i - b); + } + + struct doc: traversal::doc, context + { + doc (context& c) : context (c) {} + + virtual void + traverse (type& ds) + { + // n = 1 - common doc string + // n = 2 - arg string, common doc string + // n > 2 - arg string, usage string, man string + // + size_t n (ds.size ()); + const string& d (n == 1 ? ds[0] : n == 2 ? ds[1] : ds[2]); + + if (d.empty ()) + return; + + std::set<string> arg_set; + if (n > 1) + translate_arg (ds[0], arg_set); + + string s (format (ot_html, escape_html (translate (d, arg_set)), true)); + + wrap_lines (os, s, 2); + os << endl + << endl; + } + }; + struct option: traversal::option, context { option (context& c) : context (c) {} @@ -28,7 +120,7 @@ namespace names& n (o.named ()); - os << " <dt><code><b>"; + os << " <dt><code><b>"; for (names::name_iterator i (n.name_begin ()); i != n.name_end (); ++i) { @@ -50,7 +142,7 @@ namespace translate_arg ( doc.size () > 0 ? doc[0] : string ("<arg>"), arg_set)); - os << ' ' << format (escape_html (s), ot_html); + os << ' ' << format (ot_html, escape_html (s), false); } os << "</dt>" << endl; @@ -77,85 +169,14 @@ namespace // Format the documentation string. // - d = format (escape_html (translate (d, arg_set)), ot_html); - - os << " <dd>"; - - if (!d.empty ()) - { - size_t b (0), e (0), i (0); - - for (size_t n (d.size ()); i < n; ++i) - { - if (d[i] == ' ' || d[i] == '\n') - e = i; - - if (d[i] == '\n' || (i - b >= 76 && e != b)) - { - if (b != 0) - { - os << endl - << " "; - } - - os << string (d, b, e - b); - - if (d[i] == '\n') - os << endl; - - b = e = e + 1; - } - } - - // Flush the last line. - // - if (b != i) - { - if (b != 0) - { - os << endl - << " "; - } - - os << string (d, b, i - b); - } - } + d = format (ot_html, escape_html (translate (d, arg_set)), false); - os << "</dd>" << endl + wrap_lines (os, "<dd>" + d + "</dd>", 4); + os << endl << endl; } private: - string - escape_html (string const& s) - { - string r; - r.reserve (s.size ()); - - for (size_t i (0), n (s.size ()); i < n; ++i) - { - switch (s[i]) - { - case '<': - { - r += "<"; - break; - } - case '&': - { - r += "&"; - break; - } - default: - { - r += s[i]; - break; - } - } - } - - return r; - } }; // @@ -165,9 +186,7 @@ namespace class_ (context& c) : context (c), option_ (c) { - *this >> inherits_base_ >> base_ >> inherits_base_; - base_ >> names_option_; - + *this >> inherits_base_ >> *this; names_option_ >> option_; } @@ -177,15 +196,20 @@ namespace if (!options.exclude_base ()) inherits (c, inherits_base_); - names (c, names_option_); + if (!c.names_empty ()) + { + os << " <dl class=\"options\">" << endl; + names (c, names_option_); + os << " </dl>" << endl + << endl; + } } private: + traversal::inherits inherits_base_; + option option_; traversal::names names_option_; - - traversal::class_ base_; - traversal::inherits inherits_base_; }; } @@ -195,18 +219,21 @@ generate_html (context& ctx) traversal::cli_unit unit; traversal::names unit_names; traversal::namespace_ ns; + doc dc (ctx); class_ cl (ctx); - unit >> unit_names >> ns; + unit >> unit_names; + unit_names >> dc; + unit_names >> ns; unit_names >> cl; traversal::names ns_names; - ns >> ns_names >> ns; + ns >> ns_names; + ns_names >> dc; + ns_names >> ns; ns_names >> cl; - ctx.os << "<dl class=\"options\">" << endl; - if (ctx.options.class_ ().empty ()) unit.dispatch (ctx.unit); else @@ -230,6 +257,4 @@ generate_html (context& ctx) } } } - - ctx.os << "</dl>" << endl; } diff --git a/cli/man.cxx b/cli/man.cxx index b6fd7e8..d4ef7c5 100644 --- a/cli/man.cxx +++ b/cli/man.cxx @@ -50,7 +50,7 @@ namespace translate_arg ( doc.size () > 0 ? doc[0] : string ("<arg>"), arg_set)); - os << ' ' << format (s, ot_man); + os << ' ' << format (ot_man, s, false); } os << "\"" << endl; @@ -77,7 +77,7 @@ namespace // Format the documentation string. // - d = format (translate (d, arg_set), ot_man); + d = format (ot_man, translate (d, arg_set), false); if (!d.empty ()) { diff --git a/cli/semantics/elements.hxx b/cli/semantics/elements.hxx index a0adce0..65a9382 100644 --- a/cli/semantics/elements.hxx +++ b/cli/semantics/elements.hxx @@ -347,6 +347,12 @@ namespace semantics return names_.end (); } + bool + names_empty () const + { + return names_.empty (); + } + virtual names_iterator_pair find (string const& name) const; diff --git a/cli/source.cxx b/cli/source.cxx index d5c3fd3..19cdb82 100644 --- a/cli/source.cxx +++ b/cli/source.cxx @@ -208,7 +208,7 @@ namespace l++; // ' ' seperator if (doc.size () > 0) - l += format (doc[0], ot_plain).size (); + l += format (ot_plain, doc[0], false).size (); else l += 5; // <arg> } @@ -268,7 +268,7 @@ namespace if (doc.size () > 0) { - string s (format (doc[0], ot_plain)); + string s (format (ot_plain, doc[0], false)); os << escape_str (s); l += s.size (); } @@ -306,7 +306,7 @@ namespace // Format the documentation string. // - d = format (d, ot_plain); + d = format (ot_plain, d, false); if (!d.empty ()) { 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; } </style> 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; } </style> @@ -83,244 +76,259 @@ line interface compiler for C++. --> -<dl class="options"> - <dt><code><b>--help</b></code></dt> - <dd>Print usage information and exit.</dd> - - <dt><code><b>--version</b></code></dt> - <dd>Print version and exit.</dd> - - <dt><code><b>--include-path</b></code>|<code><b>-I</b></code> <i>dir</i></dt> - <dd>Search <i>dir</i> for bracket-included (<code><b><></b></code>) options - files.</dd> - - <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <i>dir</i></dt> - <dd>Write the generated files to <i>dir</i> instead of the current directory.</dd> - - <dt><code><b>--generate-modifier</b></code></dt> - <dd>Generate option value modifiers in addition to accessors.</dd> - - <dt><code><b>--generate-specifier</b></code></dt> - <dd>Generate functions for determining whether the option was specified on the - command line.</dd> - - <dt><code><b>--generate-parse</b></code></dt> - <dd>Generate <code><b>parse()</b></code> 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.</dd> - - <dt><code><b>--generate-description</b></code></dt> - <dd>Generate the option description list that can be examined at runtime.</dd> + <dl class="options"> + <dt><code><b>--help</b></code></dt> + <dd>Print usage information and exit.</dd> + + <dt><code><b>--version</b></code></dt> + <dd>Print version and exit.</dd> + + <dt><code><b>--include-path</b></code>|<code><b>-I</b></code> <i>dir</i></dt> + <dd>Search <i>dir</i> for bracket-included (<code><b><></b></code>) + options files.</dd> + + <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <i>dir</i></dt> + <dd>Write the generated files to <i>dir</i> instead of the current + directory.</dd> + + <dt><code><b>--generate-modifier</b></code></dt> + <dd>Generate option value modifiers in addition to accessors.</dd> - <dt><code><b>--generate-file-scanner</b></code></dt> - <dd>Generate the <code>argv_file_scanner</code> implementation. This scanner is - capable of reading command line arguments from the <code>argv</code> array - as well as files specified with command line options.</dd> + <dt><code><b>--generate-specifier</b></code></dt> + <dd>Generate functions for determining whether the option was specified on + the command line.</dd> - <dt><code><b>--suppress-inline</b></code></dt> - <dd>Generate all functions non-inline. By default simple functions are made - inline. This option suppresses creation of the inline file.</dd> + <dt><code><b>--generate-parse</b></code></dt> + <dd>Generate <code><b>parse()</b></code> 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.</dd> - <dt><code><b>--ostream-type</b></code> <i>type</i></dt> - <dd>Output stream type instead of the default <code><b>std::ostream</b></code> - that should be used to print usage and exception information.</dd> + <dt><code><b>--generate-description</b></code></dt> + <dd>Generate the option description list that can be examined at + runtime.</dd> - <dt><code><b>--suppress-undocumented</b></code></dt> - <dd>Suppress the generation of documentation entries for undocumented options.</dd> + <dt><code><b>--generate-file-scanner</b></code></dt> + <dd>Generate the <code>argv_file_scanner</code> implementation. This + scanner is capable of reading command line arguments from the + <code>argv</code> array as well as files specified with command line + options.</dd> - <dt><code><b>--suppress-usage</b></code></dt> - <dd>Suppress the generation of the usage printing code.</dd> + <dt><code><b>--suppress-inline</b></code></dt> + <dd>Generate all functions non-inline. By default simple functions are + made inline. This option suppresses creation of the inline file.</dd> - <dt><code><b>--long-usage</b></code></dt> - <dd>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.</dd> + <dt><code><b>--ostream-type</b></code> <i>type</i></dt> + <dd>Output stream type instead of the default + <code><b>std::ostream</b></code> that should be used to print usage and + exception information.</dd> - <dt><code><b>--short-usage</b></code></dt> - <dd>If specified together with <code><b>--long-usage</b></code>, generate both - short and long usage versions. In this mode, the usage printing functions - are called <code><b>print_short_usage()</b></code> and - <code><b>print_long_usage()</b></code> and for the long usage the long - documentation string is always used, even if the short version is provided.</dd> + <dt><code><b>--suppress-undocumented</b></code></dt> + <dd>Suppress the generation of documentation entries for undocumented + options.</dd> - <dt><code><b>--option-length</b></code> <i>len</i></dt> - <dd>Indent option descriptions <i>len</i> 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.</dd> + <dt><code><b>--suppress-usage</b></code></dt> + <dd>Suppress the generation of the usage printing code.</dd> - <dt><code><b>--exclude-base</b></code></dt> - <dd>Exclude base class information from usage and documentation.</dd> + <dt><code><b>--long-usage</b></code></dt> + <dd>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.</dd> - <dt><code><b>--cli-namespace</b></code> <i>ns</i></dt> - <dd>Generate the CLI support types in the <i>ns</i> namespace - (<code><b>cli</b></code> by default). The namespace can be nested, for - example <code><b>details::cli</b></code>. If the namespace is empty, then - the support types are generated in the global namespace.</dd> + <dt><code><b>--short-usage</b></code></dt> + <dd>If specified together with <code><b>--long-usage</b></code>, generate + both short and long usage versions. In this mode, the usage printing + functions are called <code><b>print_short_usage()</b></code> and + <code><b>print_long_usage()</b></code> and for the long usage the long + documentation string is always used, even if the short version is + provided.</dd> - <dt><code><b>--generate-cxx</b></code></dt> - <dd>Generate C++ code. If neither <code><b>--generate-man</b></code> nor - <code><b>--generate-html</b></code> is specified, this mode is assumed by - default.</dd> + <dt><code><b>--option-length</b></code> <i>len</i></dt> + <dd>Indent option descriptions <i>len</i> 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.</dd> + + <dt><code><b>--exclude-base</b></code></dt> + <dd>Exclude base class information from usage and documentation.</dd> + + <dt><code><b>--cli-namespace</b></code> <i>ns</i></dt> + <dd>Generate the CLI support types in the <i>ns</i> namespace + (<code><b>cli</b></code> by default). The namespace can be nested, for + example <code><b>details::cli</b></code>. If the namespace is empty, then + the support types are generated in the global namespace.</dd> + + <dt><code><b>--generate-cxx</b></code></dt> + <dd>Generate C++ code. If neither <code><b>--generate-man</b></code> nor + <code><b>--generate-html</b></code> is specified, this mode is assumed by + default.</dd> + + <dt><code><b>--generate-man</b></code></dt> + <dd>Generate documentation in the man page format.</dd> + + <dt><code><b>--generate-html</b></code></dt> + <dd>Generate documentation in the HTML format.</dd> + + <dt><code><b>--hxx-prologue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the beginning of the generated C++ header + file.</dd> + + <dt><code><b>--ixx-prologue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the beginning of the generated C++ inline + file.</dd> + + <dt><code><b>--cxx-prologue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the beginning of the generated C++ source + file.</dd> + + <dt><code><b>--man-prologue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the beginning of the generated man page + file.</dd> + + <dt><code><b>--html-prologue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the beginning of the generated HTML file.</dd> + + <dt><code><b>--hxx-epilogue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the end of the generated C++ header file.</dd> + + <dt><code><b>--ixx-epilogue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the end of the generated C++ inline file.</dd> + + <dt><code><b>--cxx-epilogue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the end of the generated C++ source file.</dd> + + <dt><code><b>--man-epilogue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the end of the generated man page text.</dd> + + <dt><code><b>--html-epilogue</b></code> <i>text</i></dt> + <dd>Insert <i>text</i> at the end of the generated HTML text.</dd> + + <dt><code><b>--hxx-prologue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the generated + C++ header file.</dd> + + <dt><code><b>--ixx-prologue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the generated + C++ inline file.</dd> + + <dt><code><b>--cxx-prologue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the generated + C++ source file.</dd> + + <dt><code><b>--man-prologue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the generated + man page file.</dd> + + <dt><code><b>--html-prologue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the generated + HTML file.</dd> + + <dt><code><b>--hxx-epilogue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the generated C++ + header file.</dd> + + <dt><code><b>--ixx-epilogue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the generated C++ + inline file.</dd> + + <dt><code><b>--cxx-epilogue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the generated C++ + source file.</dd> + + <dt><code><b>--man-epilogue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the generated man page + file.</dd> + + <dt><code><b>--html-epilogue-file</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the generated HTML + file.</dd> + + <dt><code><b>--class</b></code> <i>fq-name</i></dt> + <dd>Generate the man page or HTML documentation only for the + <i>fq-name</i> options class. The <i>fq-name</i> name should be a + fully-qualified options class name, for example, + <code><b>app::options</b></code>. 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.</dd> + + <dt><code><b>--stdout</b></code></dt> + <dd>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.</dd> + + <dt><code><b>--hxx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.hxx</b></code> to + construct the name of the generated header file.</dd> + + <dt><code><b>--ixx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.ixx</b></code> to + construct the name of the generated inline file.</dd> + + <dt><code><b>--cxx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.cxx</b></code> to + construct the name of the generated source file.</dd> + + <dt><code><b>--man-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.1</b></code> to + construct the name of the generated man page file.</dd> + + <dt><code><b>--html-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.html</b></code> to + construct the name of the generated HTML file.</dd> + + <dt><code><b>--option-prefix</b></code> <i>prefix</i></dt> + <dd>Use <i>prefix</i> instead of the default <code><b>-</b></code> 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.</dd> + + <dt><code><b>--option-separator</b></code> <i>sep</i></dt> + <dd>Use <i>sep</i> instead of the default <code><b>--</b></code> 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.</dd> + + <dt><code><b>--include-with-brackets</b></code></dt> + <dd>Use angle brackets (<>) instead of quotes ("") in the generated + <code><b>#include</b></code> directives.</dd> + + <dt><code><b>--include-prefix</b></code> <i>prefix</i></dt> + <dd>Add <i>prefix</i> to the generated <code><b>#include</b></code> + directive paths.</dd> + + <dt><code><b>--guard-prefix</b></code> <i>prefix</i></dt> + <dd>Add <i>prefix</i> 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.</dd> + + <dt><code><b>--reserved-name</b></code> <i>name</i>=<i>rep</i></dt> + <dd>Add <i>name</i> with an optional <i>rep</i> 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.</dd> + + <dt><code><b>--options-file</b></code> <i>file</i></dt> + <dd>Read additional options from <i>file</i> with each option appearing on + a separate line optionally followed by space and an option value. Empty + lines and lines starting with <code><b>#</b></code> are ignored. Option + values can be enclosed in double (<code><b>"</b></code>) or single + (<code><b>'</b></code>) 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 <code><b>'"x"'</b></code>. Non-leading and + non-trailing quotes are interpreted as being part of the option value. + + <p>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 <code><b>--options-file</b></code> option is specified except + that the shell escaping and quoting is not required. Repeat this option to + specify more than one options file.</p></dd> - <dt><code><b>--generate-man</b></code></dt> - <dd>Generate documentation in the man page format.</dd> - - <dt><code><b>--generate-html</b></code></dt> - <dd>Generate documentation in the HTML format.</dd> - - <dt><code><b>--hxx-prologue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the beginning of the generated C++ header file.</dd> - - <dt><code><b>--ixx-prologue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the beginning of the generated C++ inline file.</dd> - - <dt><code><b>--cxx-prologue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the beginning of the generated C++ source file.</dd> - - <dt><code><b>--man-prologue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the beginning of the generated man page file.</dd> - - <dt><code><b>--html-prologue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the beginning of the generated HTML file.</dd> - - <dt><code><b>--hxx-epilogue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the end of the generated C++ header file.</dd> - - <dt><code><b>--ixx-epilogue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the end of the generated C++ inline file.</dd> - - <dt><code><b>--cxx-epilogue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the end of the generated C++ source file.</dd> + </dl> - <dt><code><b>--man-epilogue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the end of the generated man page text.</dd> - - <dt><code><b>--html-epilogue</b></code> <i>text</i></dt> - <dd>Insert <i>text</i> at the end of the generated HTML text.</dd> - - <dt><code><b>--hxx-prologue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the beginning of the generated C++ - header file.</dd> - - <dt><code><b>--ixx-prologue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the beginning of the generated C++ - inline file.</dd> - - <dt><code><b>--cxx-prologue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the beginning of the generated C++ - source file.</dd> - - <dt><code><b>--man-prologue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the beginning of the generated man page - file.</dd> - - <dt><code><b>--html-prologue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the beginning of the generated HTML - file.</dd> - - <dt><code><b>--hxx-epilogue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the end of the generated C++ header - file.</dd> - - <dt><code><b>--ixx-epilogue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the end of the generated C++ inline - file.</dd> - - <dt><code><b>--cxx-epilogue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the end of the generated C++ source - file.</dd> - - <dt><code><b>--man-epilogue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the end of the generated man page file.</dd> - - <dt><code><b>--html-epilogue-file</b></code> <i>file</i></dt> - <dd>Insert the content of <i>file</i> at the end of the generated HTML file.</dd> - - <dt><code><b>--class</b></code> <i>fq-name</i></dt> - <dd>Generate the man page or HTML documentation only for the <i>fq-name</i> - options class. The <i>fq-name</i> name should be a fully-qualified options - class name, for example, <code><b>app::options</b></code>. 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.</dd> - - <dt><code><b>--stdout</b></code></dt> - <dd>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.</dd> - - <dt><code><b>--hxx-suffix</b></code> <i>suffix</i></dt> - <dd>Use <i>suffix</i> instead of the default <code><b>.hxx</b></code> to - construct the name of the generated header file.</dd> - - <dt><code><b>--ixx-suffix</b></code> <i>suffix</i></dt> - <dd>Use <i>suffix</i> instead of the default <code><b>.ixx</b></code> to - construct the name of the generated inline file.</dd> - - <dt><code><b>--cxx-suffix</b></code> <i>suffix</i></dt> - <dd>Use <i>suffix</i> instead of the default <code><b>.cxx</b></code> to - construct the name of the generated source file.</dd> - - <dt><code><b>--man-suffix</b></code> <i>suffix</i></dt> - <dd>Use <i>suffix</i> instead of the default <code><b>.1</b></code> to construct - the name of the generated man page file.</dd> - - <dt><code><b>--html-suffix</b></code> <i>suffix</i></dt> - <dd>Use <i>suffix</i> instead of the default <code><b>.html</b></code> to - construct the name of the generated HTML file.</dd> - - <dt><code><b>--option-prefix</b></code> <i>prefix</i></dt> - <dd>Use <i>prefix</i> instead of the default <code><b>-</b></code> 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.</dd> - - <dt><code><b>--option-separator</b></code> <i>sep</i></dt> - <dd>Use <i>sep</i> instead of the default <code><b>--</b></code> 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.</dd> - - <dt><code><b>--include-with-brackets</b></code></dt> - <dd>Use angle brackets (<>) instead of quotes ("") in the generated - <code><b>#include</b></code> directives.</dd> - - <dt><code><b>--include-prefix</b></code> <i>prefix</i></dt> - <dd>Add <i>prefix</i> to the generated <code><b>#include</b></code> directive - paths.</dd> - - <dt><code><b>--guard-prefix</b></code> <i>prefix</i></dt> - <dd>Add <i>prefix</i> 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.</dd> - - <dt><code><b>--reserved-name</b></code> <i>name</i>=<i>rep</i></dt> - <dd>Add <i>name</i> with an optional <i>rep</i> 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.</dd> - - <dt><code><b>--options-file</b></code> <i>file</i></dt> - <dd>Read additional options from <i>file</i> with each option appearing on a - separate line optionally followed by space and an option value. Empty lines - and lines starting with <code><b>#</b></code> are ignored. Option values can - be enclosed in double (<code><b>"</b></code>) or single - (<code><b>'</b></code>) 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 - <code><b>'"x"'</b></code>. Non-leading and non-trailing quotes are - interpreted as being part of the option value. - - <p>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 <code><b>--options-file</b></code> option is specified except that - the shell escaping and quoting is not required. Repeat this option to - specify more than one options file.</p></dd> - -</dl> <h1>DIAGNOSTICS</h1> <p>If the input file is not a valid CLI definition, <code><b>cli</b></code> |