summaryrefslogtreecommitdiff
path: root/cli/doc
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2020-06-06 22:42:16 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2020-08-03 11:05:02 +0300
commitaec14867cce71c5a5e849335fbec1f6e4f7068ea (patch)
tree465cb8fd088a6a4b6ecb4fcdc5b69eb881a27320 /cli/doc
parentf2fcd319a8a140eba983e2dfea8d81ad82f504f5 (diff)
Use ad hoc recipe for parsing code and documentation generating
Diffstat (limited to 'cli/doc')
-rw-r--r--cli/doc/buildfile130
-rw-r--r--cli/doc/cli-prologue.12
-rw-r--r--cli/doc/cli-prologue.xhtml2
-rwxr-xr-xcli/doc/doc.sh78
4 files changed, 124 insertions, 88 deletions
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