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) | 19 | ||||
| -rw-r--r-- | cli/doc/pregenerated/cli.xhtml (renamed from cli/doc/bootstrap/cli.xhtml) | 27 |
5 files changed, 205 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 2c9645e..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 2022" "CLI 1.2.0-b.8" +.TH CLI 1 "January 2023" "CLI 1.2.0" .SH NAME cli \- command line interface compiler for C++ .\" @@ -169,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 @@ -348,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 @@ -416,7 +431,7 @@ Send bug reports to the cli-users@codesynthesis.com mailing list. .\" COPYRIGHT .\" .SH COPYRIGHT -Copyright (c) 2009-2022 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 96dc913..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-2022 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"/> @@ -213,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 @@ -485,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 @@ -571,7 +592,7 @@ arg+{ --foo } # 'arg+{' ...</pre> </div> <div id="footer"> - Copyright © 2009-2022 Code Synthesis Tools CC. + Copyright © 2009-2023 Code Synthesis Tools CC. <div id="terms"> Permission is granted to copy, distribute and/or modify this |