From 2d507c0f2e6ca663062f827d4c3dc3271edd353a Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Sat, 6 Jun 2020 22:42:16 +0300
Subject: Use ad hoc recipe for parsing code and documentation generating

---
 cli/README-GIT             |   7 +++
 cli/build/root.build       |  15 +++---
 cli/cli/buildfile          |  77 ++++++++++++++++-----------
 cli/doc/buildfile          | 130 ++++++++++++++++++++++++++++++++++++++++++---
 cli/doc/cli-prologue.1     |   2 +-
 cli/doc/cli-prologue.xhtml |   2 +-
 cli/doc/doc.sh             |  78 ---------------------------
 7 files changed, 185 insertions(+), 126 deletions(-)
 create mode 100644 cli/README-GIT
 delete mode 100755 cli/doc/doc.sh

diff --git a/cli/README-GIT b/cli/README-GIT
new file mode 100644
index 0000000..5e76279
--- /dev/null
+++ b/cli/README-GIT
@@ -0,0 +1,7 @@
+If you plan to prepare the package distribution, then configure the project to
+import cli, html2ps, and ps2pdf14 programs. This makes sure that the presence
+of these programs is not optional anymore and thus the package distribution is
+guaranteed to contain all the documentation files. For example:
+
+$ b configure: config.cli=.../cli config.html2ps=html2ps \
+  config.ps2pdf14=ps2pdf14
diff --git a/cli/build/root.build b/cli/build/root.build
index 476b192..ec59426 100644
--- a/cli/build/root.build
+++ b/cli/build/root.build
@@ -12,14 +12,11 @@
 # cli package configuration to point to its own binary (or a binary in another
 # build configuration if you want to play it safe).
 #
-# Note, though, that currently referring to the cli target in the project
-# itself ends up with the 'dependency cycle detected' error. In the future we
-# will fix that by using an ad hoc recipe instead of the cli module. But for
-# now you can workaround this issue by pointing to a binary in another
-# configuration.
-#
 config [path] config.cli
 
+define cli: file
+cli{*}: extension = cli
+
 cxx.std = latest
 
 using cxx
@@ -52,3 +49,9 @@ if ($config.cli != [null] && $config.cli != false)
 # Specify the test target for cross-testing.
 #
 test.target = $cxx.target
+
+# Extract the copyright notice from the LICENSE file.
+#
+copyright = $process.run_regex(cat $src_root/LICENSE,    \
+                               'Copyright \(c\) (.+)\.', \
+                               '\1')
diff --git a/cli/cli/buildfile b/cli/cli/buildfile
index 2385a7d..0b07265 100644
--- a/cli/cli/buildfile
+++ b/cli/cli/buildfile
@@ -3,6 +3,12 @@
 
 import libs = libcutl%lib{cutl}
 
+# Import the cli program only if explicitly requested. This way a distribution
+# that includes pre-generated files can be built without installing cli.
+#
+if ($config.cli != [null] && $config.cli != false)
+  import! [metadata] cli = cli%exe{cli}
+
 ./: exe{cli}: cxx{cli} libue{cli}
 
 # Target metadata, see also --build2-metadata in cli.cxx.
@@ -21,6 +27,45 @@ libue{cli}: {hxx ixx txx cxx}{** -cli -version -options -**.test...} \
 
 hxx{version}: in{version} $src_root/manifest
 
+# Regenerate the options parsing code if the cli program is imported.
+#
+if ($cli != [null])
+{
+  <{hxx ixx cxx}{options}>: cli{options} $cli
+  {
+    options = --include-with-brackets --include-prefix cli   \
+              --guard-prefix CLI --generate-file-scanner     \
+              --generate-specifier --generate-modifier       \
+              --suppress-undocumented --reserved-name stdout
+
+    # Include the generated cli files into the distribution and don't remove
+    # them when cleaning in src (so that clean results in a state identical to
+    # distributed).
+    #
+    dist  = true
+    clean = ($src_root != $out_root)
+
+    # We keep the generated code in the repository so copy it back to src
+    # in case of a forwarded configuration.
+    #
+    backlink = overwrite
+
+    # @@ The headers are installed by default. Needs to be fixed in build2.
+    #    Another workaround is making options.cxx a primary ad hoc group
+    #    member.
+    #
+    install = false
+  }
+  {{
+    # @@ Change this to `diag cli ($<[0])` if/when it results with the same
+    #    diagnostics.
+    #
+    diag cli $directory($<[0])/cli{options}
+
+    $cli $options -o $out_base $path($<)
+  }}
+}
+
 # Unit tests.
 #
 exe{*.test}:
@@ -42,36 +87,4 @@ for t: cxx{**.test...}
 #
 # Pass the copyright notice extracted from the LICENSE file.
 #
-copyright = $process.run_regex(cat $src_root/LICENSE,    \
-                               'Copyright \(c\) (.+)\.', \
-                               '\1')
-
 obj{cli}: cxx.poptions += -DCLI_COPYRIGHT=\"$copyright\"
-
-# Generated options parsing code.
-#
-# @@ This will eventually be replaced with an ah hoc recipe.
-#
-if ($config.cli != [null] && $config.cli != false)
-{
-  cli.cxx{options}: cli{options}
-
-  cli.options += --include-with-brackets --include-prefix cli \
---guard-prefix CLI --generate-file-scanner --generate-specifier \
---generate-modifier --suppress-undocumented --reserved-name stdout
-
-  cli.cxx{*}:
-  {
-    # Include the generated cli files into the distribution and don't remove
-    # them when cleaning in src (so that clean results in a state identical to
-    # distributed).
-    #
-    dist  = true
-    clean = ($src_root != $out_root)
-
-    # We keep the generated code in the repository so copy it back to src
-    # in case of a forwarded configuration.
-    #
-    backlink = overwrite
-  }
-}
diff --git a/cli/doc/buildfile b/cli/doc/buildfile
index f47adad..211e232 100644
--- a/cli/doc/buildfile
+++ b/cli/doc/buildfile
@@ -7,14 +7,128 @@ 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
+
+# Import the cli program only if explicitly requested. This way a distribution
+# that includes pre-generated files can be built without installing cli.
+#
+if ($config.cli != [null] && $config.cli != false)
+  import! [metadata] cli = cli%exe{cli}
+
+# Import the html2ps and ps2pdf14 programs only if present in the system. This
+# way a distribution that includes pre-generated files can be built without
+# installing these programs.
+#
+import? html2ps  = html2ps%exe{html2ps}
+import? ps2pdf14 = ps2pdf14%exe{ps2pdf14}
+
+./: css{default}
+
+# Note that we include all the generated files into the distribution and don't
+# remove them when cleaning in src (so that clean results in a state identical
+# to distributed).
+#
+
+# Generate the manual files if the cli program is imported and handle
+# (install, distribute, etc) the pre-generated files otherwise, if present.
+#
+if ($cli != [null])
+{
+  ./: {man1 xhtml}{cli}
+
+  options = -v project="CLI" -v version="$version.project_id" \
+            -v copyright="$copyright" --suppress-undocumented --stdout
+
+  man1{cli}: $src_root/cli/cli{options}          \
+             file{cli-prologue.1 cli-epilogue.1} \
+             $cli
+  {
+    dist  = true
+    clean = ($src_root != $out_root)
+  }
+  % [diag=cli]
+  {{
+    # Note that the date change doesn't change the script semantics, thus the
+    # variable is defined locally.
+    #
+    date +"%B %Y" | set date
+
+    $cli --generate-man -v date="$date" $options \
+         --man-prologue-file $path($<[1])        \
+         --man-epilogue-file $path($<[2])        \
+         $path($<[0]) >$path($>)
+  }}
 
-./: file{doc.sh}
+  xhtml{cli}: $src_root/cli/cli{options}                  \
+              file{cli-prologue.xhtml cli-epilogue.xhtml} \
+              $cli
+  {
+    dist  = true
+    clean = ($src_root != $out_root)
+  }
+  % [diag=cli]
+  {{
+    $cli --generate-html $options          \
+         --html-prologue-file $path($<[1]) \
+         --html-epilogue-file $path($<[2]) \
+         $path($<[0]) >$path($>)
+  }}
+}
+else
+  ./: {man1 xhtml}{+cli} file{cli-prologue* cli-epilogue*}
+
+guide/
+{
+  ../: xhtml{index}
+
+  # Generate the user guide ps/pdf files if the html2ps and ps2pdf14 programs
+  # are imported and handle (install, distribute, etc) the pre-generated files
+  # otherwise, if present.
+  #
+  if ($html2ps != [null])
+  {
+    ../: ps{cli-guide}
+
+    ps{cli-guide}: html2ps{guide} xhtml{index} $html2ps
+    {
+      options =
+
+      dist  = true
+      clean = ($src_root != $out_root)
+    }
+    % [diag=html2ps]
+    {{
+      $html2ps $options -f $path($<[0]) -o $path($>) $path($<[1])
+    }}
+
+    if ($ps2pdf14 != [null])
+    {
+      ../: pdf{cli-guide}
+
+      pdf{cli-guide}: ps{cli-guide} $ps2pdf14
+      {
+        options = -dOptimize=true -dEmbedAllFonts=true
+
+        dist  = true
+        clean = ($src_root != $out_root)
+      }
+      % [diag=ps2pdf14]
+      {{
+        $ps2pdf14 $options $path($<[0]) $path($>)
+      }}
+    }
+    else
+      ../: pdf{+cli-guide}
+  }
+  else
+    ../: {ps pdf}{+cli-guide}
+}
+
+doc{*}: install.subdirs = true
diff --git a/cli/doc/cli-prologue.1 b/cli/doc/cli-prologue.1
index 165cd1a..2b34fee 100644
--- a/cli/doc/cli-prologue.1
+++ b/cli/doc/cli-prologue.1
@@ -1,7 +1,7 @@
 .\" Process this file with
 .\" groff -man -Tascii cli.1
 .\"
-.TH CLI 1 "December 2009" "CLI 1.2.0"
+.TH CLI 1 "$date$" "$project$ $version$"
 .SH NAME
 cli \- command line interface compiler for C++
 .\"
diff --git a/cli/doc/cli-prologue.xhtml b/cli/doc/cli-prologue.xhtml
index 9a57f0e..386c4f0 100644
--- a/cli/doc/cli-prologue.xhtml
+++ b/cli/doc/cli-prologue.xhtml
@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 
 <head>
-  <title>CLI 1.2.0 Compiler Command Line Manual</title>
+  <title>$project$ $version$ Compiler Command Line Manual</title>
 
   <meta name="copyright" content="&#169; $copyright$"/>
   <meta name="keywords" content="cli,command,line,interface,compiler,c++"/>
diff --git a/cli/doc/doc.sh b/cli/doc/doc.sh
deleted file mode 100755
index dde9aca..0000000
--- a/cli/doc/doc.sh
+++ /dev/null
@@ -1,78 +0,0 @@
-#! /usr/bin/env bash
-
-version=1.2.0-b.6
-
-trap 'exit 1' ERR
-set -o errtrace # Trap in functions.
-
-function info () { echo "$*" 1>&2; }
-function error () { info "$*"; exit 1; }
-
-date="$(date +"%B %Y")"
-copyright="$(sed -n -re 's%^Copyright \(c\) (.+)\.$%\1%p' ../LICENSE)"
-
-while [ $# -gt 0 ]; do
-  case $1 in
-    --clean)
-      rm -f cli.xhtml cli.1
-      rm -f guide/cli-guide.ps guide/cli-guide.pdf
-      exit 0
-      ;;
-    *)
-      error "unexpected $1"
-      ;;
-  esac
-done
-
-function compile () # <input-name> <output-name>
-{
-  local i=$1; shift
-  local o=$1; shift
-
-  # Use a bash array to handle empty arguments.
-  #
-  local ops=()
-  while [ $# -gt 0 ]; do
-    ops=("${ops[@]}" "$1")
-    shift
-  done
-
-  # --html-suffix .xhtml
-  ../cli/cli -I .. \
--v project="cli" \
--v version="$version" \
--v date="$date" \
--v copyright="$copyright" \
-"${ops[@]}" --generate-html  --stdout \
---html-prologue-file cli-prologue.xhtml \
---html-epilogue-file cli-epilogue.xhtml \
-"../cli/$i.cli" >"$o.xhtml"
-
-  # --man-suffix .1
-  ../cli/cli -I .. \
--v project="cli" \
--v version="$version" \
--v date="$date" \
--v copyright="$copyright" \
-"${ops[@]}" --generate-man  --stdout \
---man-prologue-file cli-prologue.1 \
---man-epilogue-file cli-epilogue.1 \
-"../cli/$i.cli" >"$o.1"
-}
-
-compile options cli --suppress-undocumented
-
-# Manual.
-#
-
-#function compile_doc ()
-#{
-#  html2ps -f doc.html2ps:a4.html2ps -o "$n-a4.ps" "$n.xhtml"
-#  ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true "$n-a4.ps" "$n-a4.pdf"
-#
-#  html2ps -f doc.html2ps:letter.html2ps -o "$n-letter.ps" "$n.xhtml"
-#  ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true "$n-letter.ps" "$n-letter.pdf"
-#}
-
-html2ps -f guide/guide.html2ps -o guide/cli-guide.ps guide/index.xhtml
-ps2pdf14 -dOptimize=true -dEmbedAllFonts=true guide/cli-guide.ps guide/cli-guide.pdf
-- 
cgit v1.1