diff options
author | Karen Arutyunov <karen@codesynthesis.com> | 2020-06-06 22:42:16 +0300 |
---|---|---|
committer | Boris Kolpackov <boris@codesynthesis.com> | 2021-09-20 16:06:46 +0200 |
commit | 2181ec73117f2e18cc622ead6256c8104b631214 (patch) | |
tree | c9d1bb2a8d3140b6cc6dd162be8129f14e38a717 /cli/doc/buildfile | |
parent | a599248e9dfab9f5d57c06bed56f75941cb00047 (diff) |
Use ad hoc recipe for parsing code and documentation generating
The overall approach is to store pre-generated bootstrap options.?xx
and cli.{1,xhtml} and automatically update them in the development
build (config.cli.develop=true). See README.md in the root of the
repository for details.
Diffstat (limited to 'cli/doc/buildfile')
-rw-r--r-- | cli/doc/buildfile | 117 |
1 files changed, 109 insertions, 8 deletions
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} |