From eb73ba6975b3c465469fa399747a1c0827972e0d Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 16 Jul 2020 15:39:26 +0200
Subject: Review

---
 cli/build/root.build |  2 ++
 cli/cli/buildfile    | 19 +++++--------------
 cli/doc/buildfile    | 38 ++++++++++++++++++++------------------
 3 files changed, 27 insertions(+), 32 deletions(-)

(limited to 'cli')

diff --git a/cli/build/root.build b/cli/build/root.build
index f041a74..af59ccb 100644
--- a/cli/build/root.build
+++ b/cli/build/root.build
@@ -46,6 +46,8 @@ test.target = $cxx.target
 
 # Extract the copyright notice from the LICENSE file.
 #
+# Note that cat is a builtin which means this is both portable and fast.
+#
 copyright = $process.run_regex(cat $src_root/LICENSE,    \
                                'Copyright \(c\) (.+)\.', \
                                '\1')
diff --git a/cli/cli/buildfile b/cli/cli/buildfile
index 0b07265..108b3e3 100644
--- a/cli/cli/buildfile
+++ b/cli/cli/buildfile
@@ -27,7 +27,8 @@ 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.
+# Provide the options parsing code generation recipe if the cli program is
+# available.
 #
 if ($cli != [null])
 {
@@ -38,8 +39,8 @@ if ($cli != [null])
               --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
+    # Include 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).
     #
     dist  = true
@@ -49,19 +50,9 @@ if ($cli != [null])
     # 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}
-
+    diag cli ($<[0])
     $cli $options -o $out_base $path($<)
   }}
 }
diff --git a/cli/doc/buildfile b/cli/doc/buildfile
index 211e232..78f0e62 100644
--- a/cli/doc/buildfile
+++ b/cli/doc/buildfile
@@ -22,7 +22,7 @@ html2ps{*}: extension = html2ps
 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
+# Import the html2ps and ps2pdf14 programs only if present on the system. This
 # way a distribution that includes pre-generated files can be built without
 # installing these programs.
 #
@@ -34,17 +34,16 @@ import? ps2pdf14 = ps2pdf14%exe{ps2pdf14}
 # 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.
+# Generate the man pages if the cli program is available 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
+  man_options = -v project="CLI" -v version="$version.project_id" \
+                -v copyright="$copyright" --suppress-undocumented
 
   man1{cli}: $src_root/cli/cli{options}          \
              file{cli-prologue.1 cli-epilogue.1} \
@@ -53,17 +52,18 @@ if ($cli != [null])
     dist  = true
     clean = ($src_root != $out_root)
   }
-  % [diag=cli]
   {{
+    diag cli $>: ($<[0])
+
     # 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($>)
+    $cli --generate-man -v date="$date" $man_options \
+         --man-prologue-file $path($<[1])            \
+         --man-epilogue-file $path($<[2])            \
+         --stdout $path($<[0]) >$path($>)
   }}
 
   xhtml{cli}: $src_root/cli/cli{options}                  \
@@ -73,17 +73,19 @@ if ($cli != [null])
     dist  = true
     clean = ($src_root != $out_root)
   }
-  % [diag=cli]
   {{
-    $cli --generate-html $options          \
+    diag cli $>: ($<[0])
+    $cli --generate-html $man_options      \
          --html-prologue-file $path($<[1]) \
          --html-epilogue-file $path($<[2]) \
-         $path($<[0]) >$path($>)
+         --stdout $path($<[0]) >$path($>)
   }}
 }
 else
   ./: {man1 xhtml}{+cli} file{cli-prologue* cli-epilogue*}
 
+# @@ TODO: get rid of subdirectory.
+#
 guide/
 {
   ../: xhtml{index}
@@ -96,16 +98,16 @@ guide/
   {
     ../: ps{cli-guide}
 
-    ps{cli-guide}: html2ps{guide} xhtml{index} $html2ps
+    ps{cli-guide}: xhtml{index} html2ps{guide} $html2ps
     {
       options =
 
       dist  = true
       clean = ($src_root != $out_root)
     }
-    % [diag=html2ps]
     {{
-      $html2ps $options -f $path($<[0]) -o $path($>) $path($<[1])
+      diag html2ps ($<[0])
+      $html2ps $options -f $path($<[1]) -o $path($>) $path($<[0])
     }}
 
     if ($ps2pdf14 != [null])
@@ -119,8 +121,8 @@ guide/
         dist  = true
         clean = ($src_root != $out_root)
       }
-      % [diag=ps2pdf14]
       {{
+        diag ps2pdf14 ($<[0])
         $ps2pdf14 $options $path($<[0]) $path($>)
       }}
     }
-- 
cgit v1.1