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.

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}