summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2011-01-04 16:00:08 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2011-01-04 16:00:08 +0200
commit039c03f71f6a9341649756f674c2153640d9d087 (patch)
tree165b5e69c3634648e2b71bd7bd80b9eac9c56092 /doc
parent53b8695810131792357c833cb6c8237df117ea3b (diff)
Restore deleted documentation files
Diffstat (limited to 'doc')
-rw-r--r--doc/cli.1233
-rw-r--r--doc/cli.xhtml264
2 files changed, 497 insertions, 0 deletions
diff --git a/doc/cli.1 b/doc/cli.1
new file mode 100644
index 0000000..3c4e64c
--- /dev/null
+++ b/doc/cli.1
@@ -0,0 +1,233 @@
+.\" Process this file with
+.\" groff -man -Tascii cli.1
+.\"
+.TH CLI 1 "December 2009" "CLI 1.1.0"
+.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
+.\"--------------------------------------------------------------------
+.\"
+.\" 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"
+Print version and exit\.
+
+.IP "\fB--output-dir\fP|\fB-o\fP \fIdir\fP"
+Write the generated files to \fIdir\fP instead of the current directory\.
+
+.IP "\fB--generate-modifier\fP"
+Generate option value modifiers in addition to accessors\.
+
+.IP "\fB--generate-specifier\fP"
+Generate functions for determining whether the option was specified on the
+command line\.
+
+.IP "\fB--generate-description\fP"
+Generate the option description list that can be examined at runtime\.
+
+.IP "\fB--generate-file-scanner\fP"
+Generate the argv_file_scanner implementation\. This scanner is capable of
+reading command line arguments from the argv array as well as files
+specified with command line options\.
+
+.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--suppress-undocumented\fP"
+Suppress the generation of documentation entries for undocumented options\.
+
+.IP "\fB--suppress-usage\fP"
+Suppress the generation of the usage printing code\.
+
+.IP "\fB--long-usage\fP"
+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--option-length\fP \fIlen\fP"
+Indent option descriptions \fIlen\fP 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--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--man-prologue\fP \fIfile\fP"
+Insert the content of \fIfile\fP at the beginning of the man page file\.
+
+.IP "\fB--man-epilogue\fP \fIfile\fP"
+Insert the content of \fIfile\fP at the end of the man page file\.
+
+.IP "\fB--html-prologue\fP \fIfile\fP"
+Insert the content of \fIfile\fP at the beginning of the HTML file\.
+
+.IP "\fB--html-epilogue\fP \fIfile\fP"
+Insert the content of \fIfile\fP at the end of the 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\. This functionality is useful
+if you need 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\.
+
+.IP "\fB--ixx-suffix\fP \fIsuffix\fP"
+Use \fIsuffix\fP instead of the default \fB\.ixx\fP to construct the name of
+the generated inline file\.
+
+.IP "\fB--cxx-suffix\fP \fIsuffix\fP"
+Use \fIsuffix\fP instead of the default \fB\.cxx\fP to construct the name of
+the generated source file\.
+
+.IP "\fB--man-suffix\fP \fIsuffix\fP"
+Use \fIsuffix\fP instead of the default \fB\.1\fP to construct the name of
+the generated man page file\.
+
+.IP "\fB--html-suffix\fP \fIsuffix\fP"
+Use \fIsuffix\fP instead of the default \fB\.html\fP to construct the name
+of the generated HTML file\.
+
+.IP "\fB--option-prefix\fP \fIprefix\fP"
+Use \fIprefix\fP instead of the default \fB-\fP 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\fP \fIsep\fP"
+Use \fIsep\fP instead of the default \fB--\fP 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--include-with-brackets\fP"
+Use angle brackets (<>) instead of quotes ("") in the generated
+\fB#include\fP directives\.
+
+.IP "\fB--include-prefix\fP \fIprefix\fP"
+Add \fIprefix\fP to the generated \fB#include\fP directive paths\.
+
+.IP "\fB--guard-prefix\fP \fIprefix\fP"
+Add \fIprefix\fP 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\fP \fIname\fP=\fIrep\fP"
+Add \fIname\fP with an optional \fIrep\fP 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\fP \fIfile\fP"
+Read additional options from \fIfile\fP with each option appearing on a
+separate line optionally followed by space and an option value\. Empty lines
+and lines starting with \fB#\fP are ignored\. Option values can be enclosed
+in double (\fB"\fP) or single (\fB'\fP) 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"'\fP\. 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\fP 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-2011 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/doc/cli.xhtml b/doc/cli.xhtml
new file mode 100644
index 0000000..58ff1f2
--- /dev/null
+++ b/doc/cli.xhtml
@@ -0,0 +1,264 @@
+<!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.1.0 Compiler Command Line Manual</title>
+
+ <meta name="copyright" content="&copy; 2009-2011 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;
+ }
+
+ #commands dt {
+ padding-top : 0.4em;
+ }
+
+ #commands dd {
+ padding-bottom : 0.4em;
+ padding-left : 2em;
+ }
+
+ .options dt {
+ padding-top : 0.4em;
+ }
+
+ .options dd {
+ padding-top : 0.1em;
+ padding-bottom : 0.4em;
+ padding-left : 1.4em;
+ }
+
+</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>
+
+<!--
+ 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>
+
+ <dt><code><b>--version</b></code></dt>
+ <dd>Print version and exit.</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-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>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-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-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>--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>--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>--man-prologue</b></code> <i>file</i></dt>
+ <dd>Insert the content of <i>file</i> at the beginning of the man page file.</dd>
+
+ <dt><code><b>--man-epilogue</b></code> <i>file</i></dt>
+ <dd>Insert the content of <i>file</i> at the end of the man page file.</dd>
+
+ <dt><code><b>--html-prologue</b></code> <i>file</i></dt>
+ <dd>Insert the content of <i>file</i> at the beginning of the HTML file.</dd>
+
+ <dt><code><b>--html-epilogue</b></code> <i>file</i></dt>
+ <dd>Insert the content of <i>file</i> at the end of the 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>. This
+ functionality is useful if you need 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 (&lt;>) 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>
+ 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">
+ &copy; 2009-2011 <a href="http://www.codesynthesis.com">Code Synthesis Tools CC</a>
+
+ <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>