diff options
author | Boris Kolpackov <boris@codesynthesis.com> | 2015-11-16 11:43:19 +0200 |
---|---|---|
committer | Boris Kolpackov <boris@codesynthesis.com> | 2015-11-16 11:43:19 +0200 |
commit | 5a2da5767e796bcfdaf5ebf3b80b93c57d31d0aa (patch) | |
tree | e3f101a7cae07ce18a485abc261b15467339861b | |
parent | 03ee21e34a4829644cc07b4fc6378b2f5e1de937 (diff) |
Support specifying documentation variables on command linedoc
-rw-r--r-- | cli/cli.cxx | 20 | ||||
-rw-r--r-- | cli/options.cli | 87 | ||||
-rw-r--r-- | cli/options.cxx | 189 | ||||
-rw-r--r-- | cli/options.hxx | 48 | ||||
-rw-r--r-- | cli/options.ixx | 66 | ||||
-rw-r--r-- | cli/semantics/unit.hxx | 1 | ||||
-rw-r--r-- | doc/cli.1 | 59 | ||||
-rw-r--r-- | doc/cli.xhtml | 75 |
8 files changed, 297 insertions, 248 deletions
diff --git a/cli/cli.cxx b/cli/cli.cxx index 41f90aa..ecf3b3b 100644 --- a/cli/cli.cxx +++ b/cli/cli.cxx @@ -11,6 +11,8 @@ #include <cutl/compiler/code-stream.hxx> +#include <semantics/doc.hxx> + #include "options.hxx" #include "parser.hxx" #include "generator.hxx" @@ -97,6 +99,24 @@ main (int argc, char* argv[]) parser p (include_paths); auto_ptr<semantics::cli_unit> unit (p.parse (ifs, path)); + // Merge documentation variables from the command line. + // + for (map<string, string>::const_iterator i (ops.docvar ().begin ()); + i != ops.docvar ().end (); + ++i) + { + using semantics::doc; + + // Values specified in the .cli file override command line. + // + if (unit->lookup<doc> ("", "var: " + i->first) != 0) + continue; + + doc& d (unit->new_node<doc> (semantics::path ("<command line>"), 0, 0)); + unit->new_edge<semantics::names> (*unit, d, "var: " + i->first); + d.push_back (i->second); + } + generator g; g.generate (ops, *unit, path); } diff --git a/cli/options.cli b/cli/options.cli index 7f8e2dc..841081d 100644 --- a/cli/options.cli +++ b/cli/options.cli @@ -65,6 +65,15 @@ class options made inline. This option suppresses creation of the inline file." }; + std::string --cli-namespace = "::cli" + { + "<ns>", + "Generate the CLI support types in the <ns> namespace (\cb{cli} by + default). The namespace can be nested, for example \cb{details::cli}. + If the namespace is empty, then the support types are generated in + the global namespace." + }; + std::string --ostream-type = "::std::ostream" { "<type>", @@ -72,6 +81,29 @@ class options should be used to print usage and exception information." }; + bool --generate-cxx + { + "Generate C++ code. If neither \cb{--generate-man} nor \cb{--generate-html} + is specified, this mode is assumed by default." + }; + + bool --generate-man + { + "Generate documentation in the man page format." + }; + + bool --generate-html + { + "Generate documentation in the HTML format." + }; + + bool --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." + }; + bool --suppress-undocumented { "Suppress the generation of documentation entries for undocumented @@ -112,29 +144,27 @@ class options "Exclude base class information from usage and documentation." }; - std::string --cli-namespace = "::cli" - { - "<ns>", - "Generate the CLI support types in the <ns> namespace (\cb{cli} by - default). The namespace can be nested, for example \cb{details::cli}. - If the namespace is empty, then the support types are generated in - the global namespace." - }; - - bool --generate-cxx - { - "Generate C++ code. If neither \cb{--generate-man} nor \cb{--generate-html} - is specified, this mode is assumed by default." - }; - - bool --generate-man + std::vector<std::string> --class { - "Generate documentation in the man page format." + "<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, \cb{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." }; - bool --generate-html + std::map<std::string, std::string> --docvar|-v { - "Generate documentation in the HTML format." + "<name>=<val>", + "Set documentation variable <name> to the value <val>. Documentation + variables can be substituted in prologues and epilogues (see + \cb{--*-prologue*} and \cb{--*-epilogue*} options) using the + \cb{$}<name>\cb{$} expansion syntax (use \cb{$$} to escape expansion). + They can also be defined in \cb{.cli} files using the + \c{\"\\<name>=<val>\"} syntax." }; // Prologues. @@ -273,25 +303,6 @@ class options "Insert the content of <file> at the end of the generated HTML file." }; - std::vector<std::string> --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, \cb{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." - }; - - bool --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." - }; - std::string --hxx-suffix = ".hxx" { "<suffix>", diff --git a/cli/options.cxx b/cli/options.cxx index dd9d075..c225d49 100644 --- a/cli/options.cxx +++ b/cli/options.cxx @@ -488,52 +488,40 @@ namespace cli static void parse (std::map<K, V>& m, scanner& s) { - std::string o (s.next ()); + const char* o (s.next ()); if (s.more ()) { std::string ov (s.next ()); std::string::size_type p = ov.find ('='); - if (p == std::string::npos) - { - K k = K (); - - if (!ov.empty ()) - { - std::istringstream ks (ov); + K k = K (); + V v = V (); + std::string kstr (ov, 0, p); + std::string vstr (ov, (p != std::string::npos ? p + 1 : ov.size ())); - if (!(ks >> k && ks.eof ())) - throw invalid_value (o, ov); - } - - m[k] = V (); - } - else + int ac (2); + char* av[] = { - K k = K (); - V v = V (); - std::string kstr (ov, 0, p); - std::string vstr (ov, p + 1); + const_cast<char*> (o), 0 + }; - if (!kstr.empty ()) - { - std::istringstream ks (kstr); - - if (!(ks >> k && ks.eof ())) - throw invalid_value (o, ov); - } - - if (!vstr.empty ()) - { - std::istringstream vs (vstr); - if (!(vs >> v && vs.eof ())) - throw invalid_value (o, ov); - } + if (!kstr.empty ()) + { + av[1] = const_cast<char*> (kstr.c_str ()); + argv_scanner s (0, ac, av); + parser<K>::parse (k, s); + } - m[k] = v; + if (!vstr.empty ()) + { + av[1] = const_cast<char*> (vstr.c_str ()); + argv_scanner s (0, ac, av); + parser<V>::parse (v, s); } + + m[k] = v; } else throw missing_value (o); @@ -566,17 +554,20 @@ options () generate_description_ (), generate_file_scanner_ (), suppress_inline_ (), + cli_namespace_ ("::cli"), ostream_type_ ("::std::ostream"), + generate_cxx_ (), + generate_man_ (), + generate_html_ (), + stdout__ (), suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), short_usage_ (), option_length_ (0), exclude_base_ (), - cli_namespace_ ("::cli"), - generate_cxx_ (), - generate_man_ (), - generate_html_ (), + class__ (), + docvar_ (), hxx_prologue_ (), ixx_prologue_ (), cxx_prologue_ (), @@ -597,8 +588,6 @@ options () cxx_epilogue_file_ (), man_epilogue_file_ (), html_epilogue_file_ (), - class__ (), - stdout__ (), hxx_suffix_ (".hxx"), ixx_suffix_ (".ixx"), cxx_suffix_ (".cxx"), @@ -630,17 +619,20 @@ options (int& argc, generate_description_ (), generate_file_scanner_ (), suppress_inline_ (), + cli_namespace_ ("::cli"), ostream_type_ ("::std::ostream"), + generate_cxx_ (), + generate_man_ (), + generate_html_ (), + stdout__ (), suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), short_usage_ (), option_length_ (0), exclude_base_ (), - cli_namespace_ ("::cli"), - generate_cxx_ (), - generate_man_ (), - generate_html_ (), + class__ (), + docvar_ (), hxx_prologue_ (), ixx_prologue_ (), cxx_prologue_ (), @@ -661,8 +653,6 @@ options (int& argc, cxx_epilogue_file_ (), man_epilogue_file_ (), html_epilogue_file_ (), - class__ (), - stdout__ (), hxx_suffix_ (".hxx"), ixx_suffix_ (".ixx"), cxx_suffix_ (".cxx"), @@ -697,17 +687,20 @@ options (int start, generate_description_ (), generate_file_scanner_ (), suppress_inline_ (), + cli_namespace_ ("::cli"), ostream_type_ ("::std::ostream"), + generate_cxx_ (), + generate_man_ (), + generate_html_ (), + stdout__ (), suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), short_usage_ (), option_length_ (0), exclude_base_ (), - cli_namespace_ ("::cli"), - generate_cxx_ (), - generate_man_ (), - generate_html_ (), + class__ (), + docvar_ (), hxx_prologue_ (), ixx_prologue_ (), cxx_prologue_ (), @@ -728,8 +721,6 @@ options (int start, cxx_epilogue_file_ (), man_epilogue_file_ (), html_epilogue_file_ (), - class__ (), - stdout__ (), hxx_suffix_ (".hxx"), ixx_suffix_ (".ixx"), cxx_suffix_ (".cxx"), @@ -764,17 +755,20 @@ options (int& argc, generate_description_ (), generate_file_scanner_ (), suppress_inline_ (), + cli_namespace_ ("::cli"), ostream_type_ ("::std::ostream"), + generate_cxx_ (), + generate_man_ (), + generate_html_ (), + stdout__ (), suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), short_usage_ (), option_length_ (0), exclude_base_ (), - cli_namespace_ ("::cli"), - generate_cxx_ (), - generate_man_ (), - generate_html_ (), + class__ (), + docvar_ (), hxx_prologue_ (), ixx_prologue_ (), cxx_prologue_ (), @@ -795,8 +789,6 @@ options (int& argc, cxx_epilogue_file_ (), man_epilogue_file_ (), html_epilogue_file_ (), - class__ (), - stdout__ (), hxx_suffix_ (".hxx"), ixx_suffix_ (".ixx"), cxx_suffix_ (".cxx"), @@ -833,17 +825,20 @@ options (int start, generate_description_ (), generate_file_scanner_ (), suppress_inline_ (), + cli_namespace_ ("::cli"), ostream_type_ ("::std::ostream"), + generate_cxx_ (), + generate_man_ (), + generate_html_ (), + stdout__ (), suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), short_usage_ (), option_length_ (0), exclude_base_ (), - cli_namespace_ ("::cli"), - generate_cxx_ (), - generate_man_ (), - generate_html_ (), + class__ (), + docvar_ (), hxx_prologue_ (), ixx_prologue_ (), cxx_prologue_ (), @@ -864,8 +859,6 @@ options (int start, cxx_epilogue_file_ (), man_epilogue_file_ (), html_epilogue_file_ (), - class__ (), - stdout__ (), hxx_suffix_ (".hxx"), ixx_suffix_ (".ixx"), cxx_suffix_ (".cxx"), @@ -898,17 +891,20 @@ options (::cli::scanner& s, generate_description_ (), generate_file_scanner_ (), suppress_inline_ (), + cli_namespace_ ("::cli"), ostream_type_ ("::std::ostream"), + generate_cxx_ (), + generate_man_ (), + generate_html_ (), + stdout__ (), suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), short_usage_ (), option_length_ (0), exclude_base_ (), - cli_namespace_ ("::cli"), - generate_cxx_ (), - generate_man_ (), - generate_html_ (), + class__ (), + docvar_ (), hxx_prologue_ (), ixx_prologue_ (), cxx_prologue_ (), @@ -929,8 +925,6 @@ options (::cli::scanner& s, cxx_epilogue_file_ (), man_epilogue_file_ (), html_epilogue_file_ (), - class__ (), - stdout__ (), hxx_suffix_ (".hxx"), ixx_suffix_ (".ixx"), cxx_suffix_ (".cxx"), @@ -976,10 +970,21 @@ print_usage (::std::ostream& os) os << "--suppress-inline Generate all functions non-inline." << ::std::endl; + os << "--cli-namespace <ns> Generate the CLI support types in the <ns>" << ::std::endl + << " namespace ('cli' by default)." << ::std::endl; + os << "--ostream-type <type> Output stream type instead of the default" << ::std::endl << " 'std::ostream' that should be used to print usage" << ::std::endl << " and exception information." << ::std::endl; + os << "--generate-cxx Generate C++ code." << ::std::endl; + + os << "--generate-man Generate documentation in the man page format." << ::std::endl; + + os << "--generate-html Generate documentation in the HTML format." << ::std::endl; + + os << "--stdout Write output to STDOUT instead of a file." << ::std::endl; + os << "--suppress-undocumented Suppress the generation of documentation entries" << ::std::endl << " for undocumented options." << ::std::endl; @@ -998,14 +1003,11 @@ print_usage (::std::ostream& os) os << "--exclude-base Exclude base class information from usage and" << ::std::endl << " documentation." << ::std::endl; - os << "--cli-namespace <ns> Generate the CLI support types in the <ns>" << ::std::endl - << " namespace ('cli' by default)." << ::std::endl; - - os << "--generate-cxx Generate C++ code." << ::std::endl; + os << "--class <fq-name> Generate the man page or HTML documentation only" << ::std::endl + << " for the <fq-name> options class." << ::std::endl; - os << "--generate-man Generate documentation in the man page format." << ::std::endl; - - os << "--generate-html Generate documentation in the HTML format." << ::std::endl; + os << "--docvar|-v <name>=<val> Set documentation variable <name> to the value" << ::std::endl + << " <val>." << ::std::endl; os << "--hxx-prologue <text> Insert <text> at the beginning of the generated" << ::std::endl << " C++ header file." << ::std::endl; @@ -1067,11 +1069,6 @@ print_usage (::std::ostream& os) os << "--html-epilogue-file <file> Insert the content of <file> at the end of the" << ::std::endl << " generated HTML file." << ::std::endl; - os << "--class <fq-name> Generate the man page or HTML documentation only" << ::std::endl - << " for the <fq-name> options class." << ::std::endl; - - os << "--stdout Write output to STDOUT instead of a file." << ::std::endl; - os << "--hxx-suffix <suffix> Use <suffix> instead of the default '.hxx' to" << ::std::endl << " construct the name of the generated header file." << ::std::endl; @@ -1145,8 +1142,18 @@ struct _cli_options_map_init &::cli::thunk< options, bool, &options::generate_file_scanner_ >; _cli_options_map_["--suppress-inline"] = &::cli::thunk< options, bool, &options::suppress_inline_ >; + _cli_options_map_["--cli-namespace"] = + &::cli::thunk< options, std::string, &options::cli_namespace_ >; _cli_options_map_["--ostream-type"] = &::cli::thunk< options, std::string, &options::ostream_type_ >; + _cli_options_map_["--generate-cxx"] = + &::cli::thunk< options, bool, &options::generate_cxx_ >; + _cli_options_map_["--generate-man"] = + &::cli::thunk< options, bool, &options::generate_man_ >; + _cli_options_map_["--generate-html"] = + &::cli::thunk< options, bool, &options::generate_html_ >; + _cli_options_map_["--stdout"] = + &::cli::thunk< options, bool, &options::stdout__ >; _cli_options_map_["--suppress-undocumented"] = &::cli::thunk< options, bool, &options::suppress_undocumented_ >; _cli_options_map_["--suppress-usage"] = @@ -1159,14 +1166,12 @@ struct _cli_options_map_init &::cli::thunk< options, std::size_t, &options::option_length_ >; _cli_options_map_["--exclude-base"] = &::cli::thunk< options, bool, &options::exclude_base_ >; - _cli_options_map_["--cli-namespace"] = - &::cli::thunk< options, std::string, &options::cli_namespace_ >; - _cli_options_map_["--generate-cxx"] = - &::cli::thunk< options, bool, &options::generate_cxx_ >; - _cli_options_map_["--generate-man"] = - &::cli::thunk< options, bool, &options::generate_man_ >; - _cli_options_map_["--generate-html"] = - &::cli::thunk< options, bool, &options::generate_html_ >; + _cli_options_map_["--class"] = + &::cli::thunk< options, std::vector<std::string>, &options::class__ >; + _cli_options_map_["--docvar"] = + &::cli::thunk< options, std::map<std::string, std::string>, &options::docvar_ >; + _cli_options_map_["-v"] = + &::cli::thunk< options, std::map<std::string, std::string>, &options::docvar_ >; _cli_options_map_["--hxx-prologue"] = &::cli::thunk< options, std::vector<std::string>, &options::hxx_prologue_ >; _cli_options_map_["--ixx-prologue"] = @@ -1207,10 +1212,6 @@ struct _cli_options_map_init &::cli::thunk< options, std::string, &options::man_epilogue_file_ >; _cli_options_map_["--html-epilogue-file"] = &::cli::thunk< options, std::string, &options::html_epilogue_file_ >; - _cli_options_map_["--class"] = - &::cli::thunk< options, std::vector<std::string>, &options::class__ >; - _cli_options_map_["--stdout"] = - &::cli::thunk< options, bool, &options::stdout__ >; _cli_options_map_["--hxx-suffix"] = &::cli::thunk< options, std::string, &options::hxx_suffix_ >; _cli_options_map_["--ixx-suffix"] = diff --git a/cli/options.hxx b/cli/options.hxx index 0328661..ecafb22 100644 --- a/cli/options.hxx +++ b/cli/options.hxx @@ -393,9 +393,24 @@ class options suppress_inline () const; const std::string& + cli_namespace () const; + + const std::string& ostream_type () const; const bool& + generate_cxx () const; + + const bool& + generate_man () const; + + const bool& + generate_html () const; + + const bool& + stdout_ () const; + + const bool& suppress_undocumented () const; const bool& @@ -413,17 +428,11 @@ class options const bool& exclude_base () const; - const std::string& - cli_namespace () const; - - const bool& - generate_cxx () const; - - const bool& - generate_man () const; + const std::vector<std::string>& + class_ () const; - const bool& - generate_html () const; + const std::map<std::string, std::string>& + docvar () const; const std::vector<std::string>& hxx_prologue () const; @@ -485,12 +494,6 @@ class options const std::string& html_epilogue_file () const; - const std::vector<std::string>& - class_ () const; - - const bool& - stdout_ () const; - const std::string& hxx_suffix () const; @@ -555,17 +558,20 @@ class options bool generate_description_; bool generate_file_scanner_; bool suppress_inline_; + std::string cli_namespace_; std::string ostream_type_; + bool generate_cxx_; + bool generate_man_; + bool generate_html_; + bool stdout__; bool suppress_undocumented_; bool suppress_usage_; bool long_usage_; bool short_usage_; std::size_t option_length_; bool exclude_base_; - std::string cli_namespace_; - bool generate_cxx_; - bool generate_man_; - bool generate_html_; + std::vector<std::string> class__; + std::map<std::string, std::string> docvar_; std::vector<std::string> hxx_prologue_; std::vector<std::string> ixx_prologue_; std::vector<std::string> cxx_prologue_; @@ -586,8 +592,6 @@ class options std::string cxx_epilogue_file_; std::string man_epilogue_file_; std::string html_epilogue_file_; - std::vector<std::string> class__; - bool stdout__; std::string hxx_suffix_; std::string ixx_suffix_; std::string cxx_suffix_; diff --git a/cli/options.ixx b/cli/options.ixx index c2b9a80..b146a60 100644 --- a/cli/options.ixx +++ b/cli/options.ixx @@ -264,12 +264,42 @@ suppress_inline () const } inline const std::string& options:: +cli_namespace () const +{ + return this->cli_namespace_; +} + +inline const std::string& options:: ostream_type () const { return this->ostream_type_; } inline const bool& options:: +generate_cxx () const +{ + return this->generate_cxx_; +} + +inline const bool& options:: +generate_man () const +{ + return this->generate_man_; +} + +inline const bool& options:: +generate_html () const +{ + return this->generate_html_; +} + +inline const bool& options:: +stdout_ () const +{ + return this->stdout__; +} + +inline const bool& options:: suppress_undocumented () const { return this->suppress_undocumented_; @@ -305,28 +335,16 @@ exclude_base () const return this->exclude_base_; } -inline const std::string& options:: -cli_namespace () const -{ - return this->cli_namespace_; -} - -inline const bool& options:: -generate_cxx () const -{ - return this->generate_cxx_; -} - -inline const bool& options:: -generate_man () const +inline const std::vector<std::string>& options:: +class_ () const { - return this->generate_man_; + return this->class__; } -inline const bool& options:: -generate_html () const +inline const std::map<std::string, std::string>& options:: +docvar () const { - return this->generate_html_; + return this->docvar_; } inline const std::vector<std::string>& options:: @@ -449,18 +467,6 @@ html_epilogue_file () const return this->html_epilogue_file_; } -inline const std::vector<std::string>& options:: -class_ () const -{ - return this->class__; -} - -inline const bool& options:: -stdout_ () const -{ - return this->stdout__; -} - inline const std::string& options:: hxx_suffix () const { diff --git a/cli/semantics/unit.hxx b/cli/semantics/unit.hxx index cd4198b..772d2f7 100644 --- a/cli/semantics/unit.hxx +++ b/cli/semantics/unit.hxx @@ -293,6 +293,7 @@ namespace semantics { } + using namespace_::add_edge_left; using namespace_::add_edge_right; private: @@ -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.</p> <h1>OPTIONS</h1> - -<!-- - The following documentation was generated by CLI, a command - line interface compiler for C++. ---> - <dl class="options"> <dt><code><b>--help</b></code></dt> <dd>Print usage information and exit.</dd> @@ -118,11 +112,33 @@ <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>--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>--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-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>--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>--suppress-undocumented</b></code></dt> <dd>Suppress the generation of documentation entries for undocumented options.</dd> @@ -152,22 +168,24 @@ <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>--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>--generate-html</b></code></dt> - <dd>Generate documentation in the HTML format.</dd> + <dt><code><b>--docvar</b></code>|<code><b>-v</b></code> <i>name</i>=<i>val</i></dt> + <dd>Set documentation variable <i>name</i> to the value <i>val</i>. + Documentation variables can be substituted in prologues and epilogues (see + <code><b>--*-prologue*</b></code> and <code><b>--*-epilogue*</b></code> + options) using the <code><b>$</b></code><i>name</i><code><b>$</b></code> + expansion syntax (use <code><b>$$</b></code> to escape expansion). They + can also be defined in <code><b>.cli</b></code> files using the + <code>"\<i>name</i>=<i>val</i>"</code> syntax.</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 @@ -243,21 +261,6 @@ <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> |