diff options
Diffstat (limited to 'cli/doc')
-rw-r--r-- | cli/doc/.gitignore | 7 | ||||
-rw-r--r-- | cli/doc/bootstrap/cli.1 | 416 | ||||
-rw-r--r-- | cli/doc/bootstrap/cli.xhtml | 573 | ||||
-rw-r--r-- | cli/doc/buildfile | 117 | ||||
-rw-r--r-- | cli/doc/cli-guide.xhtml (renamed from cli/doc/guide/index.xhtml) | 0 | ||||
-rw-r--r-- | cli/doc/cli-prologue.1 | 2 | ||||
-rw-r--r-- | cli/doc/cli-prologue.xhtml | 2 | ||||
-rwxr-xr-x | cli/doc/doc.sh | 78 | ||||
-rw-r--r-- | cli/doc/guide.html2ps (renamed from cli/doc/guide/guide.html2ps) | 0 | ||||
-rw-r--r-- | cli/doc/guide/.gitignore | 2 |
10 files changed, 1105 insertions, 92 deletions
diff --git a/cli/doc/.gitignore b/cli/doc/.gitignore index 562ecbd..93bbd2d 100644 --- a/cli/doc/.gitignore +++ b/cli/doc/.gitignore @@ -1,2 +1,5 @@ -cli.xhtml -cli.1 +*.ps +*.pdf + +/cli.xhtml +/cli.1 diff --git a/cli/doc/bootstrap/cli.1 b/cli/doc/bootstrap/cli.1 new file mode 100644 index 0000000..dae4474 --- /dev/null +++ b/cli/doc/bootstrap/cli.1 @@ -0,0 +1,416 @@ +.\" Process this file with +.\" groff -man -Tascii cli.1 +.\" +.TH CLI 1 "January 2021" "CLI 1.2.0-b.7" +.SH NAME +cli \- command line interface compiler for C++ +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH SYNOPSIS +.\"-------------------------------------------------------------------- +.B cli +.B [ +.I options +.B ] +.I file +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH DESCRIPTION +.\"-------------------------------------------------------------------- +.B cli +generates C++ implementation and documentation in various formats for a +command line interface defined in the CLI language. For an input file in +the form +.B name.cli +the following is generated. By default or if the +.B --generate-cxx +option is specified, the following C++ files are generated: +.B name.hxx +(header file), +.B name.ixx +(inline file, generated unless the +.B --suppress-inline +option is specified), and +.B name.cxx (source file). +If the +.B --generate-html +option is specified, then the +.B name.html +HTML documentation file is generated. If the +.B --generate-man +option is specified, then the +.B name.1 +man page file is generated. When +.B --generate-html +or +.B --generate-man +is specified, the +.B --stdout +option can be used to redirect the output to STDOUT instead of a file. +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH OPTIONS +.\"-------------------------------------------------------------------- +.IP "\fB--help\fR" +Print usage information and exit\. +.IP "\fB--version\fR" +Print version and exit\. +.IP "\fB--include-path\fR|\fB-I\fR \fIdir\fR" +Search \fIdir\fR for bracket-included (\fB<>\fR) options files\. +.IP "\fB--output-dir\fR|\fB-o\fR \fIdir\fR" +Write the generated files to \fIdir\fR instead of the current directory\. +.IP "\fB--std\fR \fIversion\fR" +Specify the C++ standard that should be used during compilation\. Valid values +are \fBc++98\fR (default), \fBc++11\fR, and \fBc++14\fR\. +.IP "\fB--generate-modifier\fR" +Generate option value modifiers in addition to accessors\. +.IP "\fB--generate-specifier\fR" +Generate functions for determining whether the option was specified on the +command line\. +.IP "\fB--generate-parse\fR" +Generate \fBparse()\fR 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 option appending/overriding\. +.IP "\fB--generate-merge\fR" +Generate \fBmerge()\fR functions\. This is primarily useful for being able to +merge several already parsed options class instances, for example, to +implement option appending/overriding\. Note that this option forces +\fB--generate-specifier\fR\. +.IP "\fB--generate-description\fR" +Generate the option description list that can be examined at runtime\. +.IP "\fB--generate-file-scanner\fR" +Generate the \fBargv_file_scanner\fR implementation\. This scanner is capable +of reading command line arguments from the \fBargv\fR array as well as files +specified with command line options\. +.IP "\fB--generate-vector-scanner\fR" +Generate the \fBvector_scanner\fR implementation\. This scanner is capable of +reading command line arguments from \fBvector<string>\fR\. +.IP "\fB--generate-group-scanner\fR" +Generate the \fBgroup_scanner\fR implementation\. This scanner supports +grouping of arguments (usually options) to apply only to a certain argument\. + +Groups can be specified before (leading) and/or after (trailing) the argument +they apply to\. A leading group starts with '\fB{\fR' and ends with '\fB}+\fR' +while a trailing group starts with '\fB+{\fR' and ends with '\fB}\fR'\. For +example: + +.nf +{ --foo --bar }+ arg # 'arg' with '--foo' '--bar' +arg +{ fox=1 baz=2 } # 'arg' with 'fox=1' 'baz=2' +.fi + +Multiple leading and/or trailing groups can be specified for the same +argument\. For example: + +.nf +{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2' +.fi + +The group applies to a single argument only unless multiple arguments are +themselves grouped with '\fB{\fR' and '\fB}\fR'\. For example: + +.nf +{ --foo }+ arg1 arg2 +{ --bar } # 'arg1' with '--foo' + # 'arg2' with '--bar' + +{ --foo }+ { arg1 arg2 } +{ --bar } # 'arg1' with '--foo' '--bar' + # 'arg2' with '--foo' '--bar' +.fi + +The group separators ('\fB{\fR', '\fB}+'\fR, etc) must be separate command +line arguments\. In particular, they must not be adjacent either to the +arguments inside the group nor to the argument they apply to\. All such cases +will be treated as ordinary arguments\. For example: + +.nf +{--foo}+ arg # '{--foo}+' \.\.\. +arg+{ --foo } # 'arg+{' \.\.\. +.fi + +If one of the group separators needs to be specified as an argument verbatim, +then it must be escaped with '\fB\e\fR'\. For example: + +.nf +} # error: unexpected group separator +}x # '}x' +\\} # '}' +{ \\}+ }+ arg # 'arg' with '}+' +.fi +.IP "\fB--suppress-inline\fR" +Generate all functions non-inline\. By default simple functions are made +inline\. This option suppresses creation of the inline file\. +.IP "\fB--suppress-cli\fR" +Do not generate the CLI support types (scanners, parser, etc)\. Normally, the +support types are generated unless another \fB\.cli\fR was included, in which +case the support types are expected to be provided by its generated code\. +.IP "\fB--cli-namespace\fR \fIns\fR" +Generate the CLI support types in the \fIns\fR namespace (\fBcli\fR by +default)\. The namespace can be nested, for example \fBdetails::cli\fR\. If +the namespace is empty, then the support types are generated in the global +namespace\. +.IP "\fB--ostream-type\fR \fItype\fR" +Output stream type instead of the default \fBstd::ostream\fR that should be +used to print usage and exception information\. +.IP "\fB--generate-cxx\fR" +Generate C++ code\. If neither \fB--generate-man\fR, \fB--generate-html\fR, +nor \fB--generate-txt\fR is specified, this mode is assumed by default\. +.IP "\fB--generate-man\fR" +Generate documentation in the man page format\. +.IP "\fB--generate-html\fR" +Generate documentation in the HTML format\. +.IP "\fB--generate-txt\fR" +Generate documentation in the plain text format, similar to usage\. +.IP "\fB--stdout\fR" +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\fR" +Suppress the generation of documentation entries for undocumented options\. +.IP "\fB--suppress-usage\fR" +Suppress the generation of the usage printing code\. +.IP "\fB--long-usage\fR" +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\. +.IP "\fB--short-usage\fR" +If specified together with \fB--long-usage\fR, generate both short and long +usage versions\. In this mode, the long usage printing function is called +\fBprint_long_usage()\fR and in its implementation the long documentation +string is always used, even if the short version is provided\. +.IP "\fB--page-usage\fR \fIname\fR" +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 \fIname\fR 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: + +.nf +--page-usage print_ # print_usage() in global namespace +--page-usage app::print_ # print_usage() in app namespace +--page-usage print_$name$_ # print_foo_usage() if name is foo +.fi + +If both \fB--long-usage\fR and \fB--short-usage\fR options are specified, then +the long usage function has the \fB*long_usage()\fR suffix\. +.IP "\fB--option-length\fR \fIlen\fR" +Indent option descriptions \fIlen\fR 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\. +.IP "\fB--ansi-color\fR" +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 \fBless(1)\fR, it will display them +correctly\. +.IP "\fB--exclude-base\fR" +Exclude base class information from usage and documentation\. +.IP "\fB--include-base-last\fR" +Include base class information after derived for usage and documentation\. By +default, base classes are included first\. +.IP "\fB--class-doc\fR \fIname\fR=\fIkind\fR" +Specify the documentation \fIkind\fR that should be used for the options class +\fIname\fR\. The \fIname\fR value should be a fully-qualified class name, for +example, \fBapp::options\fR\. The \fIkind\fR value can be \fBshort\fR, +\fBlong\fR, \fBexclude\fR, or \fBexclude-base\fR\. If the value is +\fBexclude\fR, then the class documentation is excluded from usage and +man/HTML/text output\. If it is \fBexclude-base\fR, then it is only excluded +when used as a base\. For usage, the \fBshort\fR and \fBlong\fR values +determine which usage function will be called when the class is used as base +or as part of the page usage (see \fB--page-usage\fR)\. For man/HTML/text, +these values determine which documentation strings are used in the output\. +.IP "\fB--class\fR \fIname\fR" +Generate the man page, HTML, or text documentation only for the options class +\fIname\fR\. The \fIname\fR value should be a fully-qualified options class +name, for example, \fBapp::options\fR\. 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\fR|\fB-v\fR \fIname\fR=\fIval\fR" +Set documentation variable \fIname\fR to the value \fIval\fR\. Documentation +variables can be substituted in prologues and epilogues (see +\fB--*-prologue*\fR and \fB--*-epilogue*\fR options) using the +\fB$\fR\fIname\fR\fB$\fR expansion syntax (use \fB$$\fR to escape expansion)\. +They can also be defined in \fB\.cli\fR files using the +\&"\e\fIname\fR=\fIval\fR"\fR syntax\. +.IP "\fB--link-regex\fR \fIregex\fR" +Add \fIregex\fR 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 +\fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any character can be +used as a delimiter instead of '\fB/\fR' and the delimiter can be escaped +inside \fIpattern\fR and \fIreplacement\fR with a backslash (\fB\e\fR)\. 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 \fB--link-regex-trace\fR option to debug link +transformation\. +.IP "\fB--link-regex-trace\fR" +Trace the process of applying regular expressions specified with the +\fB--link-regex\fR option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. +.IP "\fB--html-heading-map\fR \fIc\fR=\fIh\fR" +Map CLI heading \fIc\fR (valid values: '\fBH\fR', '\fB0\fR', '\fB1\fR', +\&'\fBh\fR', and '\fB2\fR') to HTML heading \fIh\fR (for example, '\fBh1\fR', +\&'\fBh2\fR', etc)\. +.IP "\fB--omit-link-check\fR" +Don't check that local fragment link references (\el{#ref \.\.\.}) resolve to +ids\. +.IP "\fB--hxx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ header file\. +.IP "\fB--ixx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ inline file\. +.IP "\fB--cxx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ source file\. +.IP "\fB--man-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated man page file\. +.IP "\fB--html-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated HTML file\. +.IP "\fB--txt-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated text file\. +.IP "\fB--hxx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ header file\. +.IP "\fB--ixx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ inline file\. +.IP "\fB--cxx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ source file\. +.IP "\fB--man-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated man page file\. +.IP "\fB--html-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated HTML file\. +.IP "\fB--txt-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated text file\. +.IP "\fB--hxx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ header +file\. +.IP "\fB--ixx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ inline +file\. +.IP "\fB--cxx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ source +file\. +.IP "\fB--man-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated man page +file\. +.IP "\fB--html-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated HTML file\. +.IP "\fB--txt-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated text file\. +.IP "\fB--hxx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ header file\. +.IP "\fB--ixx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ inline file\. +.IP "\fB--cxx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ source file\. +.IP "\fB--man-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated man page file\. +.IP "\fB--html-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated HTML file\. +.IP "\fB--txt-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated text file\. +.IP "\fB--output-prefix\fR \fIprefix\fR" +Add \fIprefix\fR at the beginning of the generated output file name(s)\. +.IP "\fB--output-suffix\fR \fIsuffix\fR" +Add \fIsuffix\fR at the end of the generated output file name(s)\. Note that +it is added before any file type-specific suffixes; see \fB--*-suffix\fR +below\. +.IP "\fB--hxx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.hxx\fR to construct the name of +the generated header file\. +.IP "\fB--ixx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.ixx\fR to construct the name of +the generated inline file\. +.IP "\fB--cxx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.cxx\fR to construct the name of +the generated source file\. +.IP "\fB--man-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.1\fR to construct the name of the +generated man page file\. +.IP "\fB--html-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.html\fR to construct the name of +the generated HTML file\. +.IP "\fB--txt-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.txt\fR to construct the name of +the generated text file\. +.IP "\fB--option-prefix\fR \fIprefix\fR" +Use \fIprefix\fR instead of the default '\fB-\fR' 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\. +.IP "\fB--option-separator\fR \fIsep\fR" +Use \fIsep\fR instead of the default '\fB--\fR' 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\. +.IP "\fB--keep-separator\fR" +Leave the option separator in the scanner\. This is primarily useful for +incremental option parsing\. +.IP "\fB--no-combined-flags\fR" +Disable support for combining multiple single-character flags into a single +argument (the \fB-xyz\fR form that is equivalent to \fB-x\fR \fB-y\fR +\fB-z\fR)\. An argument is considered a combination of flags if it starts with +a single option prefix (\fB--option-prefix\fR) and only contains letters and +digits\. Note that an option with a value may not be part of such a +combination, not even if it is specified last\. +.IP "\fB--no-combined-values\fR" +Disable support for combining an option and its value into a single argument +with the assignment sign (the \fIoption\fR\fB=\fR\fIvalue\fR\fR form)\. This +functionality requires a non-empty option prefix (\fB--option-prefix\fR)\. +.IP "\fB--include-with-brackets\fR" +Use angle brackets (\fB<>\fR) instead of quotes (\fB""\fR) in the generated +\fB#include\fR directives\. +.IP "\fB--include-prefix\fR \fIprefix\fR" +Add \fIprefix\fR to the generated \fB#include\fR directive paths\. +.IP "\fB--guard-prefix\fR \fIprefix\fR" +Add \fIprefix\fR 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\. +.IP "\fB--reserved-name\fR \fIname\fR=\fIrep\fR" +Add \fIname\fR with an optional \fIrep\fR 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\. +.IP "\fB--options-file\fR \fIfile\fR" +Read additional options from \fIfile\fR\. Each option should appear on a +separate line optionally followed by space or equal sign (\fB=\fR) and an +option value\. Empty lines and lines starting with \fB#\fR are ignored\. +Option values can be enclosed in double (\fB"\fR) or single (\fB'\fR) 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 \fB'"x"'\fR\. 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 \fB--options-file\fR option is specified except that the shell escaping +and quoting is not required\. Repeat this option to specify more than one +options file\. +.\" +.\" DIAGNOSTICS +.\" +.SH DIAGNOSTICS +If the input file is not a valid CLI definition, +.B cli +will issue diagnostic messages to STDERR and exit with non-zero exit code. +.\" +.\" BUGS +.\" +.SH BUGS +Send bug reports to the cli-users@codesynthesis.com mailing list. +.\" +.\" COPYRIGHT +.\" +.SH COPYRIGHT +Copyright (c) 2009-2021 Code Synthesis Tools CC. + +Permission is granted to copy, distribute and/or modify this document under +the terms of the MIT License. Copy of this license can be obtained from +http://www.codesynthesis.com/licenses/mit.txt diff --git a/cli/doc/bootstrap/cli.xhtml b/cli/doc/bootstrap/cli.xhtml new file mode 100644 index 0000000..38b1bc8 --- /dev/null +++ b/cli/doc/bootstrap/cli.xhtml @@ -0,0 +1,573 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> + +<head> + <title>CLI 1.2.0-b.7 Compiler Command Line Manual</title> + + <meta name="copyright" content="© 2009-2021 Code Synthesis Tools CC"/> + <meta name="keywords" content="cli,command,line,interface,compiler,c++"/> + <meta name="description" content="CLI Compiler Command Line Manual"/> + + <link rel="stylesheet" type="text/css" href="default.css" /> + +<style type="text/css"> + + #synopsis { + list-style-type: none; + } + + #synopsis li { + padding-top : 0.0em; + padding-bottom : 0.0em; + } + + .options { + margin: 1em 0 1em 0; + } + + .options dt { + margin: 1em 0 0 0; + } + + .options dd { + margin: .1em 0 0 4.5em; + } + +</style> +</head> + +<body> +<div id="container"> + <div id="content"> + + <h1>NAME</h1> + + <p>cli - command line interface compiler for C++</p> + + <h1>SYNOPSIS</h1> + + <dl id="synopsis"> + <dt><code><b>cli</b> [<i>options</i>] <i>file</i></code></dt> + </dl> + + <h1>DESCRIPTION</h1> + + <p><code><b>cli</b></code> generates C++ implementation and + documentation in various formats for a command line interface + defined in the CLI language. For an input file in the form + <code><b>name.cli</b></code> the following is generated. By + default or if the <code><b>--generate-cxx</b></code> option is + specified, the following C++ files are generated: + <code><b>name.hxx</b></code> (header file), <code><b>name.ixx</b></code> + (inline file, generated unless the <code><b>--suppress-inline</b></code> + option is specified), and <code><b>name.cxx</b></code> (source file). + If the <code><b>--generate-html</b></code> option is specified, then + the <code><b>name.html</b></code> HTML documentation file is generated. + If the <code><b>--generate-man</b></code> option is specified, then + the <code><b>name.1</b></code> man page file is generated. When + <code><b>--generate-html</b></code> or <code><b>--generate-man</b></code> + is specified, the <code><b>--stdout</b></code> option can be used to + redirect the output to STDOUT instead of a file.</p> + + <h1>OPTIONS</h1> + <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> <code><i>dir</i></code></dt> + <dd>Search <code><i>dir</i></code> for bracket-included + (<code><b><></b></code>) options files.</dd> + + <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <code><i>dir</i></code></dt> + <dd>Write the generated files to <code><i>dir</i></code> instead of the + current directory.</dd> + + <dt><code><b>--std</b></code> <code><i>version</i></code></dt> + <dd>Specify the C++ standard that should be used during compilation. Valid + values are <code><b>c++98</b></code> (default), <code><b>c++11</b></code>, + and <code><b>c++14</b></code>.</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 + option appending/overriding.</dd> + + <dt><code><b>--generate-merge</b></code></dt> + <dd>Generate <code><b>merge()</b></code> functions. This is primarily + useful for being able to merge several already parsed options class + instances, for example, to implement option appending/overriding. Note + that this option forces <code><b>--generate-specifier</b></code>.</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>--generate-file-scanner</b></code></dt> + <dd>Generate the <code><b>argv_file_scanner</b></code> implementation. + This scanner is capable of reading command line arguments from the + <code><b>argv</b></code> array as well as files specified with command + line options.</dd> + + <dt><code><b>--generate-vector-scanner</b></code></dt> + <dd>Generate the <code><b>vector_scanner</b></code> implementation. This + scanner is capable of reading command line arguments from + <code><b>vector<string></b></code>.</dd> + + <dt><code><b>--generate-group-scanner</b></code></dt> + <dd>Generate the <code><b>group_scanner</b></code> implementation. This + scanner supports grouping of arguments (usually options) to apply only to + a certain argument. + + <p>Groups can be specified before (leading) and/or after (trailing) the + argument they apply to. A leading group starts with + '<code><b>{</b></code>' and ends with '<code><b>}+</b></code>' while a + trailing group starts with '<code><b>+{</b></code>' and ends with + '<code><b>}</b></code>'. For example:</p> + + <pre>{ --foo --bar }+ arg # 'arg' with '--foo' '--bar' +arg +{ fox=1 baz=2 } # 'arg' with 'fox=1' 'baz=2'</pre> + + <p>Multiple leading and/or trailing groups can be specified for the same + argument. For example:</p> + + <pre>{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'</pre> + + <p>The group applies to a single argument only unless multiple arguments + are themselves grouped with '<code><b>{</b></code>' and + '<code><b>}</b></code>'. For example:</p> + + <pre>{ --foo }+ arg1 arg2 +{ --bar } # 'arg1' with '--foo' + # 'arg2' with '--bar' + +{ --foo }+ { arg1 arg2 } +{ --bar } # 'arg1' with '--foo' '--bar' + # 'arg2' with '--foo' '--bar'</pre> + + <p>The group separators ('<code><b>{</b></code>', + '<code><b>}+'</b></code>, etc) must be separate command line arguments. In + particular, they must not be adjacent either to the arguments inside the + group nor to the argument they apply to. All such cases will be treated as + ordinary arguments. For example:</p> + + <pre>{--foo}+ arg # '{--foo}+' ... +arg+{ --foo } # 'arg+{' ...</pre> + + <p>If one of the group separators needs to be specified as an argument + verbatim, then it must be escaped with '<code><b>\</b></code>'. For + example:</p> + + <pre>} # error: unexpected group separator +}x # '}x' +\} # '}' +{ \}+ }+ arg # 'arg' with '}+'</pre></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>--suppress-cli</b></code></dt> + <dd>Do not generate the CLI support types (scanners, parser, etc). + Normally, the support types are generated unless another + <code><b>.cli</b></code> was included, in which case the support types are + expected to be provided by its generated code.</dd> + + <dt><code><b>--cli-namespace</b></code> <code><i>ns</i></code></dt> + <dd>Generate the CLI support types in the <code><i>ns</i></code> 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> <code><i>type</i></code></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>, + <code><b>--generate-html</b></code>, nor + <code><b>--generate-txt</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>--generate-txt</b></code></dt> + <dd>Generate documentation in the plain text format, similar to + usage.</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> + + <dt><code><b>--suppress-usage</b></code></dt> + <dd>Suppress the generation of the usage printing code.</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>--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 long usage printing + function is called <code><b>print_long_usage()</b></code> and in its + implementation the long documentation string is always used, even if the + short version is provided.</dd> + + <dt><code><b>--page-usage</b></code> <code><i>name</i></code></dt> + <dd>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). + + <p>The <code><i>name</i></code> 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:</p> + + <pre>--page-usage print_ # print_usage() in global namespace +--page-usage app::print_ # print_usage() in app namespace +--page-usage print_$name$_ # print_foo_usage() if name is foo</pre> + + <p>If both <code><b>--long-usage</b></code> and + <code><b>--short-usage</b></code> options are specified, then the long + usage function has the <code><b>*long_usage()</b></code> suffix.</p></dd> + + <dt><code><b>--option-length</b></code> <code><i>len</i></code></dt> + <dd>Indent option descriptions <code><i>len</i></code> 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>--ansi-color</b></code></dt> + <dd>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 + <code><b>less(1)</b></code>, it will display them correctly.</dd> + + <dt><code><b>--exclude-base</b></code></dt> + <dd>Exclude base class information from usage and documentation.</dd> + + <dt><code><b>--include-base-last</b></code></dt> + <dd>Include base class information after derived for usage and + documentation. By default, base classes are included first.</dd> + + <dt><code><b>--class-doc</b></code> <code><i>name</i></code>=<code><i>kind</i></code></dt> + <dd>Specify the documentation <code><i>kind</i></code> that should be used + for the options class <code><i>name</i></code>. The + <code><i>name</i></code> value should be a fully-qualified class name, for + example, <code><b>app::options</b></code>. The <code><i>kind</i></code> + value can be <code><b>short</b></code>, <code><b>long</b></code>, + <code><b>exclude</b></code>, or <code><b>exclude-base</b></code>. If the + value is <code><b>exclude</b></code>, then the class documentation is + excluded from usage and man/HTML/text output. If it is + <code><b>exclude-base</b></code>, then it is only excluded when used as a + base. For usage, the <code><b>short</b></code> and + <code><b>long</b></code> values determine which usage function will be + called when the class is used as base or as part of the page usage (see + <code><b>--page-usage</b></code>). For man/HTML/text, these values + determine which documentation strings are used in the output.</dd> + + <dt><code><b>--class</b></code> <code><i>name</i></code></dt> + <dd>Generate the man page, HTML, or text documentation only for the + options class <code><i>name</i></code>. The <code><i>name</i></code> value + 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>--docvar</b></code>|<code><b>-v</b></code> <code><i>name</i></code>=<code><i>val</i></code></dt> + <dd>Set documentation variable <code><i>name</i></code> to the value + <code><i>val</i></code>. 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><code><i>name</i></code><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>"\<code><i>name</i></code>=<code><i>val</i></code>"</code> + syntax.</dd> + + <dt><code><b>--link-regex</b></code> <code><i>regex</i></code></dt> + <dd>Add <code><i>regex</i></code> 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 + <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. Any + character can be used as a delimiter instead of '<code><b>/</b></code>' + and the delimiter can be escaped inside <code><i>pattern</i></code> and + <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>). + 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 + <code><b>--link-regex-trace</b></code> option to debug link + transformation.</dd> + + <dt><code><b>--link-regex-trace</b></code></dt> + <dd>Trace the process of applying regular expressions specified with the + <code><b>--link-regex</b></code> option. Use this option to find out why + your regular expressions don't do what you expected them to do.</dd> + + <dt><code><b>--html-heading-map</b></code> <code><i>c</i></code>=<code><i>h</i></code></dt> + <dd>Map CLI heading <code><i>c</i></code> (valid values: + '<code><b>H</b></code>', '<code><b>0</b></code>', '<code><b>1</b></code>', + '<code><b>h</b></code>', and '<code><b>2</b></code>') to HTML heading + <code><i>h</i></code> (for example, '<code><b>h1</b></code>', + '<code><b>h2</b></code>', etc).</dd> + + <dt><code><b>--omit-link-check</b></code></dt> + <dd>Don't check that local fragment link references (\l{#ref ...}) resolve + to ids.</dd> + + <dt><code><b>--hxx-prologue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the beginning of the generated C++ + header file.</dd> + + <dt><code><b>--ixx-prologue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the beginning of the generated C++ + inline file.</dd> + + <dt><code><b>--cxx-prologue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the beginning of the generated C++ + source file.</dd> + + <dt><code><b>--man-prologue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the beginning of the generated man + page file.</dd> + + <dt><code><b>--html-prologue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the beginning of the generated HTML + file.</dd> + + <dt><code><b>--txt-prologue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the beginning of the generated text + file.</dd> + + <dt><code><b>--hxx-epilogue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the end of the generated C++ header + file.</dd> + + <dt><code><b>--ixx-epilogue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the end of the generated C++ inline + file.</dd> + + <dt><code><b>--cxx-epilogue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the end of the generated C++ source + file.</dd> + + <dt><code><b>--man-epilogue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the end of the generated man page + file.</dd> + + <dt><code><b>--html-epilogue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the end of the generated HTML + file.</dd> + + <dt><code><b>--txt-epilogue</b></code> <code><i>text</i></code></dt> + <dd>Insert <code><i>text</i></code> at the end of the generated text + file.</dd> + + <dt><code><b>--hxx-prologue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the beginning of the + generated C++ header file.</dd> + + <dt><code><b>--ixx-prologue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the beginning of the + generated C++ inline file.</dd> + + <dt><code><b>--cxx-prologue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the beginning of the + generated C++ source file.</dd> + + <dt><code><b>--man-prologue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the beginning of the + generated man page file.</dd> + + <dt><code><b>--html-prologue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the beginning of the + generated HTML file.</dd> + + <dt><code><b>--txt-prologue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the beginning of the + generated text file.</dd> + + <dt><code><b>--hxx-epilogue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the end of the + generated C++ header file.</dd> + + <dt><code><b>--ixx-epilogue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the end of the + generated C++ inline file.</dd> + + <dt><code><b>--cxx-epilogue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the end of the + generated C++ source file.</dd> + + <dt><code><b>--man-epilogue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the end of the + generated man page file.</dd> + + <dt><code><b>--html-epilogue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the end of the + generated HTML file.</dd> + + <dt><code><b>--txt-epilogue-file</b></code> <code><i>file</i></code></dt> + <dd>Insert the content of <code><i>file</i></code> at the end of the + generated text file.</dd> + + <dt><code><b>--output-prefix</b></code> <code><i>prefix</i></code></dt> + <dd>Add <code><i>prefix</i></code> at the beginning of the generated + output file name(s).</dd> + + <dt><code><b>--output-suffix</b></code> <code><i>suffix</i></code></dt> + <dd>Add <code><i>suffix</i></code> at the end of the generated output file + name(s). Note that it is added before any file type-specific suffixes; see + <code><b>--*-suffix</b></code> below.</dd> + + <dt><code><b>--hxx-suffix</b></code> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> instead of the default + <code><b>.html</b></code> to construct the name of the generated HTML + file.</dd> + + <dt><code><b>--txt-suffix</b></code> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> instead of the default + <code><b>.txt</b></code> to construct the name of the generated text + file.</dd> + + <dt><code><b>--option-prefix</b></code> <code><i>prefix</i></code></dt> + <dd>Use <code><i>prefix</i></code> 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> <code><i>sep</i></code></dt> + <dd>Use <code><i>sep</i></code> 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>--keep-separator</b></code></dt> + <dd>Leave the option separator in the scanner. This is primarily useful + for incremental option parsing.</dd> + + <dt><code><b>--no-combined-flags</b></code></dt> + <dd>Disable support for combining multiple single-character flags into a + single argument (the <code><b>-xyz</b></code> form that is equivalent to + <code><b>-x</b></code> <code><b>-y</b></code> <code><b>-z</b></code>). An + argument is considered a combination of flags if it starts with a single + option prefix (<code><b>--option-prefix</b></code>) and only contains + letters and digits. Note that an option with a value may not be part of + such a combination, not even if it is specified last.</dd> + + <dt><code><b>--no-combined-values</b></code></dt> + <dd>Disable support for combining an option and its value into a single + argument with the assignment sign (the + <code><i>option</i><b>=</b><i>value</i></code> form). This functionality + requires a non-empty option prefix + (<code><b>--option-prefix</b></code>).</dd> + + <dt><code><b>--include-with-brackets</b></code></dt> + <dd>Use angle brackets (<code><b><></b></code>) instead of quotes + (<code><b>""</b></code>) in the generated <code><b>#include</b></code> + directives.</dd> + + <dt><code><b>--include-prefix</b></code> <code><i>prefix</i></code></dt> + <dd>Add <code><i>prefix</i></code> to the generated + <code><b>#include</b></code> directive paths.</dd> + + <dt><code><b>--guard-prefix</b></code> <code><i>prefix</i></code></dt> + <dd>Add <code><i>prefix</i></code> 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> <code><i>name</i></code>=<code><i>rep</i></code></dt> + <dd>Add <code><i>name</i></code> with an optional <code><i>rep</i></code> + 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> <code><i>file</i></code></dt> + <dd>Read additional options from <code><i>file</i></code>. Each option + should appear on a separate line optionally followed by space or equal + sign (<code><b>=</b></code>) 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> + will issue diagnostic messages to STDERR and exit with non-zero exit + code.</p> + + <h1>BUGS</h1> + + <p>Send bug reports to the + <a href="mailto:cli-users@codesynthesis.com">cli-users@codesynthesis.com</a> mailing list.</p> + + </div> + <div id="footer"> + Copyright © 2009-2021 Code Synthesis Tools CC. + + <div id="terms"> + Permission is granted to copy, distribute and/or modify this + document under the terms of the + <a href="http://www.codesynthesis.com/licenses/mit.txt">MIT License</a>. + </div> + </div> +</div> +</body> +</html> diff --git a/cli/doc/buildfile b/cli/doc/buildfile index f47adad..d56c7f5 100644 --- a/cli/doc/buildfile +++ b/cli/doc/buildfile @@ -7,14 +7,115 @@ css{*}: extension = css define xhtml: doc xhtml{*}: extension = xhtml -./: {man1 xhtml}{cli} \ - css{default} \ - file{cli-*} +define ps: doc +ps{*}: extension = ps -./: guide/doc{cli-guide*} \ - guide/xhtml{index} \ - guide/file{*.html2ps} +define pdf: doc +pdf{*}: extension = pdf -doc{*}: install.subdirs = true +define html2ps: file +html2ps{*}: extension = html2ps -./: file{doc.sh} +./: css{default} xhtml{cli-guide} bootstrap/{man1 xhtml}{cli} + +if $config.cli.develop +{ + doc_version = [string] "$version.major\.$version.minor\.$version.patch" + if $version.pre_release + doc_version += "-$version.pre_release_string" + + # Let's take the last for-digit number to cover 2000-2021,2022. + # + doc_year = $regex.replace($copyright, '.+[-, ]([0-9][0-9][0-9][0-9]) .+', '\1') + + man_options = -v project="CLI" -v version="$doc_version" \ + -v copyright="$copyright" --suppress-undocumented + + # We use the cli version we've built to generate the documentation. + # + # Note: avoid cleaning it through this dependency. + # + include ../cli/ + + {xhtml man1}{cli}: ../cli/exe{cli}: clean = false + + ./: man1{cli}: ../cli/cli{options} file{cli-prologue.1 cli-epilogue.1} + {{ + diag cli --man ($<[1]) + + # Use the copyright year to approximate the last authoring date. + # + date +"%B %Y" | set date + + ($<[0]) --generate-man $man_options \ + -v date="January $doc_year" \ + --man-prologue-file $path($<[2]) \ + --man-epilogue-file $path($<[3]) \ + --stdout $path($<[1]) >$path($>) + + # If the result differs from the bootstrap version, copy it over. Unlike + # the bootstrap cli case, here we don't need to cause a build restart. + # + if! diff $src_base/bootstrap/cli.1 $path($>) >- + cp $path($>) $src_base/bootstrap/cli.1 + end + }} + + ./: xhtml{cli}: $src_root/cli/cli{options} \ + file{cli-prologue.xhtml cli-epilogue.xhtml} + {{ + diag cli --html ($<[1]) + + ($<[0]) --generate-html $man_options \ + --html-prologue-file $path($<[2]) \ + --html-epilogue-file $path($<[3]) \ + --stdout $path($<[1]) >$path($>) + + if! diff $src_base/bootstrap/cli.xhtml $path($>) >- + cp $path($>) $src_base/bootstrap/cli.xhtml + end + }} + + # Import the html2ps and ps2pdf programs from the system, if available. + # + import? html2ps = html2ps%exe{html2ps} + import? ps2pdf = ps2pdf14%exe{ps2pdf14} + + if ($html2ps != [null] && $ps2pdf != [null]) + { + # Note that we include these generated files into the distribution and + # don't remove them when cleaning in src (so that clean results in a state + # identical to distributed). + # + ./: ps{cli-guide}: xhtml{cli-guide} html2ps{guide} $html2ps + { + options = + + dist = true + clean = ($src_root != $out_root) + } + {{ + diag html2ps ($<[0]) + $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0]) + }} + + ./: pdf{cli-guide}: ps{cli-guide} $ps2pdf + { + options = -dOptimize=true -dEmbedAllFonts=true + + dist = true + clean = ($src_root != $out_root) + } + {{ + diag ps2pdf ($<[0]) + $ps2pdf $options $path($<[0]) $path($>) + }} + } + else + { + warn "html2ps and/or ps2pdf14 are not available, not generating .ps and .pdf documentation" + ./: html2ps{guide} # Note: not keeping ps/pdf (could be outdated). + } +} +else + ./: file{cli-prologue* cli-epilogue*} html2ps{guide} {ps pdf}{+cli-guide} diff --git a/cli/doc/guide/index.xhtml b/cli/doc/cli-guide.xhtml index 675db03..675db03 100644 --- a/cli/doc/guide/index.xhtml +++ b/cli/doc/cli-guide.xhtml diff --git a/cli/doc/cli-prologue.1 b/cli/doc/cli-prologue.1 index 165cd1a..2b34fee 100644 --- a/cli/doc/cli-prologue.1 +++ b/cli/doc/cli-prologue.1 @@ -1,7 +1,7 @@ .\" Process this file with .\" groff -man -Tascii cli.1 .\" -.TH CLI 1 "December 2009" "CLI 1.2.0" +.TH CLI 1 "$date$" "$project$ $version$" .SH NAME cli \- command line interface compiler for C++ .\" diff --git a/cli/doc/cli-prologue.xhtml b/cli/doc/cli-prologue.xhtml index 9a57f0e..386c4f0 100644 --- a/cli/doc/cli-prologue.xhtml +++ b/cli/doc/cli-prologue.xhtml @@ -2,7 +2,7 @@ <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> - <title>CLI 1.2.0 Compiler Command Line Manual</title> + <title>$project$ $version$ Compiler Command Line Manual</title> <meta name="copyright" content="© $copyright$"/> <meta name="keywords" content="cli,command,line,interface,compiler,c++"/> diff --git a/cli/doc/doc.sh b/cli/doc/doc.sh deleted file mode 100755 index dde9aca..0000000 --- a/cli/doc/doc.sh +++ /dev/null @@ -1,78 +0,0 @@ -#! /usr/bin/env bash - -version=1.2.0-b.6 - -trap 'exit 1' ERR -set -o errtrace # Trap in functions. - -function info () { echo "$*" 1>&2; } -function error () { info "$*"; exit 1; } - -date="$(date +"%B %Y")" -copyright="$(sed -n -re 's%^Copyright \(c\) (.+)\.$%\1%p' ../LICENSE)" - -while [ $# -gt 0 ]; do - case $1 in - --clean) - rm -f cli.xhtml cli.1 - rm -f guide/cli-guide.ps guide/cli-guide.pdf - exit 0 - ;; - *) - error "unexpected $1" - ;; - esac -done - -function compile () # <input-name> <output-name> -{ - local i=$1; shift - local o=$1; shift - - # Use a bash array to handle empty arguments. - # - local ops=() - while [ $# -gt 0 ]; do - ops=("${ops[@]}" "$1") - shift - done - - # --html-suffix .xhtml - ../cli/cli -I .. \ --v project="cli" \ --v version="$version" \ --v date="$date" \ --v copyright="$copyright" \ -"${ops[@]}" --generate-html --stdout \ ---html-prologue-file cli-prologue.xhtml \ ---html-epilogue-file cli-epilogue.xhtml \ -"../cli/$i.cli" >"$o.xhtml" - - # --man-suffix .1 - ../cli/cli -I .. \ --v project="cli" \ --v version="$version" \ --v date="$date" \ --v copyright="$copyright" \ -"${ops[@]}" --generate-man --stdout \ ---man-prologue-file cli-prologue.1 \ ---man-epilogue-file cli-epilogue.1 \ -"../cli/$i.cli" >"$o.1" -} - -compile options cli --suppress-undocumented - -# Manual. -# - -#function compile_doc () -#{ -# html2ps -f doc.html2ps:a4.html2ps -o "$n-a4.ps" "$n.xhtml" -# ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true "$n-a4.ps" "$n-a4.pdf" -# -# html2ps -f doc.html2ps:letter.html2ps -o "$n-letter.ps" "$n.xhtml" -# ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true "$n-letter.ps" "$n-letter.pdf" -#} - -html2ps -f guide/guide.html2ps -o guide/cli-guide.ps guide/index.xhtml -ps2pdf14 -dOptimize=true -dEmbedAllFonts=true guide/cli-guide.ps guide/cli-guide.pdf diff --git a/cli/doc/guide/guide.html2ps b/cli/doc/guide.html2ps index a691002..a691002 100644 --- a/cli/doc/guide/guide.html2ps +++ b/cli/doc/guide.html2ps diff --git a/cli/doc/guide/.gitignore b/cli/doc/guide/.gitignore deleted file mode 100644 index 239cc7f..0000000 --- a/cli/doc/guide/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -*.ps -*.pdf |