Use ad hoc recipes to compile options.cli file

1 files changed, 180 insertions, 7 deletions

diff --git a/doc/buildfile b/doc/buildfile
index 45b7ac2..832897c 100644
--- a/doc/buildfile
+++ b/doc/buildfile
@@ -7,14 +7,187 @@ css{*}: extension = css
 define xhtml: doc
 xhtml{*}: extension = xhtml
 
-./: css{default}
+define ps: doc
+ps{*}: extension = ps
 
-# @@ BUILD2 TMP: auto-generated and not in git (also odb-manual.* below)
+define pdf: doc
+pdf{*}: extension = pdf
+
+define html2ps: file
+html2ps{*}: extension = html2ps
+
+./: css{default} xhtml{manual} doc{*.png} file{*.svg}
+
+# Man pages.
+#
+
+## Consumption build ($develop == false).
+#
+
+# Use pregenerated versions in the consumption build.
 #
-./: file{odb-*.1} file{odb-*.xhtml}
-    # {man1 xhtml}{odb}
+./: pregenerated/{man1 xhtml}{*}: include = (!$develop)
+
+# Distribute pregenerated versions only in the consumption build.
+#
+pregenerated/{man1 xhtml}{*}: dist = (!$develop)
+
+#
+##
+
+## Development build ($develop == true).
+#
+
+./: {man1 xhtml}{odb}: include = $develop
+
+if $develop
+{
+  doc_version = [string] "$version.major\.$version.minor\.$version.patch"
+  if $version.pre_release
+    doc_version += "-$version.pre_release_string"
 
-./: doc{manual.xhtml} doc{*.png} file{*.svg +*.html2ps}
-    #doc{odb-manual.ps odb-manual.pdf}
+  doc_version = "3.0.0"
 
-./: file{doc.sh}
+  # 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')
+
+  man_options = -v project="ODB" -v version="$doc_version" \
+                -v copyright="$copyright" --suppress-undocumented
+
+  import! [metadata] cli = cli%exe{cli}
+}
+
+# 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}{odb}: dist = ($develop ? pregenerated/ : false)
+
+# @@ TMP Note that the project, version, and date variables we are passing to
+#        cli are currently unused since the respective values are hard-coded
+#        in the odb-prologue.* files.
+#
+man1{odb}: ../odb/cli{options} file{odb-prologue.1 odb-epilogue.1} $cli
+%
+if $develop
+{{
+  # Use the copyright year to approximate the last authoring date.
+  #
+  $cli --generate-man $man_options      \
+       -v date="January $doc_year"      \
+       --man-prologue-file $path($<[1]) \
+       --man-epilogue-file $path($<[2]) \
+       --stdout $path($<[0]) >$path($>)
+
+  # If the result differs from the pregenerated version, copy it over.
+  #
+  if! diff $src_base/pregenerated/odb.1 $path($>) >-
+    cp $path($>) $src_base/pregenerated/odb.1
+  end
+}}
+
+xhtml{odb}: ../odb/cli{options} file{odb-prologue.xhtml odb-epilogue.xhtml} $cli
+%
+if $develop
+{{
+  $cli --generate-html $man_options      \
+       --html-prologue-file $path($<[1]) \
+       --html-epilogue-file $path($<[2]) \
+       --stdout $path($<[0]) >$path($>)
+
+  if! diff $src_base/pregenerated/odb.xhtml $path($>) >-
+    cp $path($>) $src_base/pregenerated/odb.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}
+
+  html2pdf = ($html2ps != [null] && $ps2pdf != [null])
+
+  if! $html2pdf
+    warn "html2ps and/or ps2pdf14 are not available, not generating .ps and .pdf documentation"
+}
+
+./: {ps pdf}{odb-manual}: 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}{odb-manual}: dist = ($html2pdf ? pregenerated/ : false)
+
+# Note: the pregenerated file 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 manual.{xhtml,html2ps} still have copyright years, ODB
+#        version, document revision/date, etc hard-coded.
+#
+ps{odb-manual}: {xhtml html2ps}{manual} $html2ps
+%
+if $html2pdf
+{{
+  options =
+
+  diag html2ps ($<[0])
+  $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0])
+
+  cp --no-cleanup $path($>) $src_base/pregenerated/odb-manual.ps
+}}
+
+pdf{odb-manual}: ps{odb-manual} $ps2pdf
+%
+if $html2pdf
+{{
+  options = -dOptimize=true -dEmbedAllFonts=true
+
+  diag ps2pdf ($<[0])
+  $ps2pdf $options $path($<[0]) $path($>)
+
+  cp --no-cleanup $path($>) $src_base/pregenerated/odb-manual.pdf
+}}
+
+#
+##