diff options
Diffstat (limited to 'cli/doc')
| -rw-r--r-- | cli/doc/.gitignore | 6 | ||||
| -rw-r--r-- | cli/doc/buildfile | 236 | ||||
| -rw-r--r-- | cli/doc/cli-guide.xhtml | 6 | ||||
| -rw-r--r-- | cli/doc/pregenerated/cli.1 (renamed from cli/doc/bootstrap/cli.1) | 26 | ||||
| -rw-r--r-- | cli/doc/pregenerated/cli.xhtml (renamed from cli/doc/bootstrap/cli.xhtml) | 38 |
5 files changed, 223 insertions, 89 deletions
diff --git a/cli/doc/.gitignore b/cli/doc/.gitignore index 93bbd2d..84c93ab 100644 --- a/cli/doc/.gitignore +++ b/cli/doc/.gitignore @@ -1,5 +1,5 @@ +/cli.1 +/cli.xhtml + *.ps *.pdf - -/cli.xhtml -/cli.1 diff --git a/cli/doc/buildfile b/cli/doc/buildfile index 09202ad..753b620 100644 --- a/cli/doc/buildfile +++ b/cli/doc/buildfile @@ -16,15 +16,37 @@ pdf{*}: extension = pdf define html2ps: file html2ps{*}: extension = html2ps -./: css{default} xhtml{cli-guide} bootstrap/{man1 xhtml}{cli} +./: css{default} xhtml{cli-guide} -if $config.cli.develop +# Man pages. +# + +## Consumption build ($develop == false). +# + +# Use pregenerated versions in the consumption build. +# +./: pregenerated/{man1 xhtml}{*}: include = (!$develop) + +# Distribute pregenerated versions only in the consumption build. +# +pregenerated/{man1 xhtml}{*}: dist = (!$develop) + +# +## + +## Development build ($develop == true). +# + +./: {man1 xhtml}{cli}: include = $develop + +if $develop { - doc_version = [string] "$version.major\.$version.minor\.$version.patch" + 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. + # Let's take the last four-digit number to cover 2000-2021,2022. # doc_year = $regex.replace($copyright, '.+[-, ]([0-9][0-9][0-9][0-9]) .+', '\1') @@ -33,87 +55,145 @@ if $config.cli.develop # We use the cli version we've built to generate the documentation. # - # Note: avoid cleaning it through this dependency. - # include ../cli/ +} + +# Note: avoid cleaning exe{cli} through this dependency. +# +{man1 xhtml}{cli}: ../cli/exe{cli}: clean = false - {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. - # - ($<[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 - }} +# In the development build distribute regenerated versions, remapping their +# locations to the paths of the pregenerated versions (which are only +# distributed in the consumption build; see above). This way we make sure that +# the distributed files are always up-to-date. +# +{man1 xhtml}{cli}: dist = ($develop ? pregenerated/ : false) +man1{cli}: ../cli/cli{options} file{cli-prologue.1 cli-epilogue.1} +% +if $develop +{{ + diag 'cli --man' ($<[1]) -> $> + + # Use the copyright year to approximate the last authoring 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 pregenerated version, copy it over. Unlike + # the bootstrap compiler case, here we don't need to cause a build restart + # (since nothing depends on it). + # + if! diff $src_base/pregenerated/cli.1 $path($>) >- + cp $path($>) $src_base/pregenerated/cli.1 + end +}} + +xhtml{cli}: ../cli/cli{options} file{cli-prologue.xhtml cli-epilogue.xhtml} +% +if $develop +{{ + 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/pregenerated/cli.xhtml $path($>) >- + cp $path($>) $src_base/pregenerated/cli.xhtml + end +}} + +# +## + +# Manual. +# +# This case is slightly more involved because we make the generation of the +# manual's ps/pdf optional and also don't keep the result in the repository. +# Specifically: +# +# 1. In the consumption build we will install/redistribute ps/pdf if present. +# +# 2. In the development build we will generate ps/pdf if we are able to import +# the needed tools, issuing a warning otherwise. + +## Consumption build ($develop == false). +# + +# Use pregenerated versions, if exist, in the consumption build. +# +./: pregenerated/{ps pdf}{*}: include = (!$develop) + +# Distribute pregenerated versions only in the consumption build. +# +pregenerated/{ps pdf}{*}: dist = (!$develop) + +# +## + +## Development build ($develop == true). +# + +html2pdf = false + +if $develop +{ # 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 - { + html2pdf = ($html2ps != [null] && $ps2pdf != [null]) + + if! $html2pdf 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} + +./: {ps pdf}{cli-guide}: include = $html2pdf + +# In the development build distribute regenerated versions, remapping their +# locations to the paths of the pregenerated versions (which are only +# distributed in the consumption build; see above). This way we make sure that +# the distributed files are always up-to-date. +# +{ps pdf}{cli-guide}: dist = ($html2pdf ? pregenerated/ : false) + +# Note: the pregenerated files may not exist, thus --no-cleanup option is +# required for the cp builtin call. Strictly speaking we don't really need +# to copy them since they are not stored in the repository, but let's do +# that for consistency with the distributed source tree. +# +# @@ TMP Note that cli-guide.xhtml and guide.html2ps still have copyright +# years hard-coded. +# +ps{cli-guide}: xhtml{cli-guide} html2ps{guide} $html2ps +% +if $html2pdf +{{ + options = + + diag html2ps ($<[0]) -> $> + $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0]) + + cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.ps +}} + +pdf{cli-guide}: ps{cli-guide} $ps2pdf +% +if $html2pdf +{{ + options = -dOptimize=true -dEmbedAllFonts=true + + diag ps2pdf ($<[0]) -> $> + $ps2pdf $options $path($<[0]) $path($>) + + cp --no-cleanup $path($>) $src_base/pregenerated/cli-guide.pdf +}} + +# +## diff --git a/cli/doc/cli-guide.xhtml b/cli/doc/cli-guide.xhtml index 675db03..94c006c 100644 --- a/cli/doc/cli-guide.xhtml +++ b/cli/doc/cli-guide.xhtml @@ -1084,12 +1084,12 @@ include <string>; class options { - std::map<std::string, std::string> --map | -m; + std::map<std::string, bool> --map | -m; }; </pre> - <p>The possible option values for this interface are: <code>-m a=A</code>, - <code>-m =B</code> (key is an empty string), <code>-m c=</code> (value + <p>The possible option values for this interface are: <code>-m a=1</code>, + <code>-m =true</code> (key is an empty string), <code>-m c=</code> (value is an empty string), or <code>-m d</code> (same as <code>-m d=</code>).</p> <p>The last component in the option definition is optional documentation. diff --git a/cli/doc/bootstrap/cli.1 b/cli/doc/pregenerated/cli.1 index d684d30..d452ca4 100644 --- a/cli/doc/bootstrap/cli.1 +++ b/cli/doc/pregenerated/cli.1 @@ -1,7 +1,7 @@ .\" Process this file with .\" groff -man -Tascii cli.1 .\" -.TH CLI 1 "January 2021" "CLI 1.2.0-b.8" +.TH CLI 1 "January 2023" "CLI 1.2.0" .SH NAME cli \- command line interface compiler for C++ .\" @@ -157,6 +157,9 @@ 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--export-symbol\fR \fIsymbol\fR" +Insert \fIsymbol\fR in places where DLL export/import control statements +(\fB__declspec(dllexport/dllimport)\fR) are necessary\. .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\. @@ -166,6 +169,15 @@ Generate documentation in the man page format\. Generate documentation in the HTML format\. .IP "\fB--generate-txt\fR" Generate documentation in the plain text format, similar to usage\. +.IP "\fB--generate-dep\fR" +Generate \fBmake\fR dependency information\. This option triggers the creation +of the \fB\.d\fR file containing the dependencies of the generated files on +the main \fB\.cli\fR file as well as all the \fB\.cli\fR files that it +includes or sources, transitively\. Paths specified with the +\fB--*-prologue-file\fR and \fB--*-epilogue-file\fR options are also added as +dependencies\. Note, however, that paths specified with the +\fB--options-file\fR option are not added (since they may or may not contain +options that affect the output)\. .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 @@ -206,6 +218,10 @@ the long usage function has the \fB*long_usage()\fR suffix\. 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--ascii-tree\fR" +Convert UTF-8 \fBtree(1)\fR output to ASCII\. Specifically, box-drawing +characters used in the \fB--charset=UTF-8\fR output are replaced with ASCII +characters used in the \fB--charset=ASCII\fR output\. .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 @@ -341,6 +357,12 @@ 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--dep-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.d\fR to construct the name of the +generated dependency file\. See also \fB--dep-file\fR\. +.IP "\fB--dep-file\fR \fIpath\fR" +Use \fIpath\fR as the generated dependency file path instead of deriving it +from the input file name\. .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 @@ -409,7 +431,7 @@ Send bug reports to the cli-users@codesynthesis.com mailing list. .\" COPYRIGHT .\" .SH COPYRIGHT -Copyright (c) 2009-2021 Code Synthesis Tools CC. +Copyright (c) 2009-2023 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 diff --git a/cli/doc/bootstrap/cli.xhtml b/cli/doc/pregenerated/cli.xhtml index b62bf57..2a4f751 100644 --- a/cli/doc/bootstrap/cli.xhtml +++ b/cli/doc/pregenerated/cli.xhtml @@ -2,9 +2,9 @@ <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> - <title>CLI 1.2.0-b.8 Compiler Command Line Manual</title> + <title>CLI 1.2.0 Compiler Command Line Manual</title> - <meta name="copyright" content="© 2009-2021 Code Synthesis Tools CC"/> + <meta name="copyright" content="© 2009-2023 Code Synthesis Tools CC"/> <meta name="keywords" content="cli,command,line,interface,compiler,c++"/> <meta name="description" content="CLI Compiler Command Line Manual"/> @@ -192,6 +192,11 @@ arg+{ --foo } # 'arg+{' ...</pre> <code><b>std::ostream</b></code> that should be used to print usage and exception information.</dd> + <dt><code><b>--export-symbol</b></code> <code><i>symbol</i></code></dt> + <dd>Insert <code><i>symbol</i></code> in places where DLL export/import + control statements (<code><b>__declspec(dllexport/dllimport)</b></code>) + are necessary.</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 @@ -208,6 +213,18 @@ arg+{ --foo } # 'arg+{' ...</pre> <dd>Generate documentation in the plain text format, similar to usage.</dd> + <dt><code><b>--generate-dep</b></code></dt> + <dd>Generate <code><b>make</b></code> dependency information. This option + triggers the creation of the <code><b>.d</b></code> file containing the + dependencies of the generated files on the main <code><b>.cli</b></code> + file as well as all the <code><b>.cli</b></code> files that it includes or + sources, transitively. Paths specified with the + <code><b>--*-prologue-file</b></code> and + <code><b>--*-epilogue-file</b></code> options are also added as + dependencies. Note, however, that paths specified with the + <code><b>--options-file</b></code> option are not added (since they may or + may not contain options that affect the output).</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 @@ -258,6 +275,12 @@ arg+{ --foo } # 'arg+{' ...</pre> potentially in separate files, and would like their usage to have the same indentation level.</dd> + <dt><code><b>--ascii-tree</b></code></dt> + <dd>Convert UTF-8 <code><b>tree(1)</b></code> output to ASCII. + Specifically, box-drawing characters used in the + <code><b>--charset=UTF-8</b></code> output are replaced with ASCII + characters used in the <code><b>--charset=ASCII</b></code> output.</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 @@ -474,6 +497,15 @@ arg+{ --foo } # 'arg+{' ...</pre> <code><b>.txt</b></code> to construct the name of the generated text file.</dd> + <dt><code><b>--dep-suffix</b></code> <code><i>suffix</i></code></dt> + <dd>Use <code><i>suffix</i></code> instead of the default + <code><b>.d</b></code> to construct the name of the generated dependency + file. See also <code><b>--dep-file</b></code>.</dd> + + <dt><code><b>--dep-file</b></code> <code><i>path</i></code></dt> + <dd>Use <code><i>path</i></code> as the generated dependency file path + instead of deriving it from the input file name.</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 @@ -560,7 +592,7 @@ arg+{ --foo } # 'arg+{' ...</pre> </div> <div id="footer"> - Copyright © 2009-2021 Code Synthesis Tools CC. + Copyright © 2009-2023 Code Synthesis Tools CC. <div id="terms"> Permission is granted to copy, distribute and/or modify this |