Reorganize .cli files, add man/xhtml page generation (via script for now)

29 files changed, 219 insertions, 65 deletions

diff --git a/bpkg/bpkg-options.cli b/bpkg/bpkg.cli
index 97fb8b8..e9611ff 100644
--- a/bpkg/bpkg-options.cli
+++ b/bpkg/bpkg.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/bpkg-options.cli
+// file      : bpkg/bpkg.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg"
diff --git a/bpkg/buildfile b/bpkg/buildfile
index c33a8ce..9f4d904 100644
--- a/bpkg/buildfile
+++ b/bpkg/buildfile
@@ -60,41 +60,41 @@ if! $cli.loaded
   cli{*}: extension = cli
 }
 
-{hxx ixx cxx}{common-options}:        cli{common-options}
-{hxx ixx cxx}{configuration-options}: cli{configuration-options}
-{hxx ixx cxx}{bpkg-options}:          cli{bpkg-options}
+{hxx ixx cxx}{common-options}:        cli{common}
+{hxx ixx cxx}{configuration-options}: cli{configuration}
+{hxx ixx cxx}{bpkg-options}:          cli{bpkg}
 
 # Help command.
 #
-{hxx ixx cxx}{help-options}:  cli{help-options}
+{hxx ixx cxx}{help-options}: cli{help}
 
 # pkg-* command.
 #
 
-{hxx ixx cxx}{pkg-build-options}:     cli{pkg-build-options}
-{hxx ixx cxx}{pkg-clean-options}:     cli{pkg-clean-options}
-{hxx ixx cxx}{pkg-configure-options}: cli{pkg-configure-options}
-{hxx ixx cxx}{pkg-disfigure-options}: cli{pkg-disfigure-options}
-{hxx ixx cxx}{pkg-drop-options}:      cli{pkg-drop-options}
-{hxx ixx cxx}{pkg-fetch-options}:     cli{pkg-fetch-options}
-{hxx ixx cxx}{pkg-install-options}:   cli{pkg-install-options}
-{hxx ixx cxx}{pkg-purge-options}:     cli{pkg-purge-options}
-{hxx ixx cxx}{pkg-status-options}:    cli{pkg-status-options}
-{hxx ixx cxx}{pkg-uninstall-options}: cli{pkg-uninstall-options}
-{hxx ixx cxx}{pkg-unpack-options}:    cli{pkg-unpack-options}
-{hxx ixx cxx}{pkg-update-options}:    cli{pkg-update-options}
-{hxx ixx cxx}{pkg-verify-options}:    cli{pkg-verify-options}
+{hxx ixx cxx}{pkg-build-options}:     cli{pkg-build}
+{hxx ixx cxx}{pkg-clean-options}:     cli{pkg-clean}
+{hxx ixx cxx}{pkg-configure-options}: cli{pkg-configure}
+{hxx ixx cxx}{pkg-disfigure-options}: cli{pkg-disfigure}
+{hxx ixx cxx}{pkg-drop-options}:      cli{pkg-drop}
+{hxx ixx cxx}{pkg-fetch-options}:     cli{pkg-fetch}
+{hxx ixx cxx}{pkg-install-options}:   cli{pkg-install}
+{hxx ixx cxx}{pkg-purge-options}:     cli{pkg-purge}
+{hxx ixx cxx}{pkg-status-options}:    cli{pkg-status}
+{hxx ixx cxx}{pkg-uninstall-options}: cli{pkg-uninstall}
+{hxx ixx cxx}{pkg-unpack-options}:    cli{pkg-unpack}
+{hxx ixx cxx}{pkg-update-options}:    cli{pkg-update}
+{hxx ixx cxx}{pkg-verify-options}:    cli{pkg-verify}
 
 # cfg-* command.
 #
-{hxx ixx cxx}{cfg-create-options}: cli{cfg-create-options}
+{hxx ixx cxx}{cfg-create-options}: cli{cfg-create}
 
 # rep-* command.
 #
-{hxx ixx cxx}{cfg-add-options}:    cli{cfg-add-options}
-{hxx ixx cxx}{cfg-fetch-options}:  cli{cfg-fetch-options}
-{hxx ixx cxx}{rep-info-options}:   cli{rep-info-options}
-{hxx ixx cxx}{rep-create-options}: cli{rep-create-options}
+{hxx ixx cxx}{cfg-add-options}:    cli{cfg-add}
+{hxx ixx cxx}{cfg-fetch-options}:  cli{cfg-fetch}
+{hxx ixx cxx}{rep-info-options}:   cli{rep-info}
+{hxx ixx cxx}{rep-create-options}: cli{rep-create}
 
 # Option length must be the same to get commands/topics/options aligned.
 #
diff --git a/bpkg/cfg-add-options.cli b/bpkg/cfg-add.cli
index 9c81e4f..34909e9 100644
--- a/bpkg/cfg-add-options.cli
+++ b/bpkg/cfg-add.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/cfg-add-options.cli
+// file      : bpkg/cfg-add.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-cfg-add"
diff --git a/bpkg/cfg-create-options.cli b/bpkg/cfg-create.cli
index b073fdf..e28778e 100644
--- a/bpkg/cfg-create-options.cli
+++ b/bpkg/cfg-create.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/cfg-create-options.cli
+// file      : bpkg/cfg-create.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-cfg-create"
diff --git a/bpkg/cfg-fetch-options.cli b/bpkg/cfg-fetch.cli
index 6d420a6..6b889cc 100644
--- a/bpkg/cfg-fetch-options.cli
+++ b/bpkg/cfg-fetch.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/cfg-fetch-options.cli
+// file      : bpkg/cfg-fetch.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-cfg-fetch"
diff --git a/bpkg/common-options.cli b/bpkg/common.cli
index d811238..17ee1a6 100644
--- a/bpkg/common-options.cli
+++ b/bpkg/common.cli
@@ -1,4 +1,4 @@
-// file      : bpkg/common-options.cli
+// file      : bpkg/common.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
diff --git a/bpkg/configuration-options.cli b/bpkg/configuration.cli
index b9c6dbc..5b174b9 100644
--- a/bpkg/configuration-options.cli
+++ b/bpkg/configuration.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/configuration-options.cli
+// file      : bpkg/configuration.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\name=configuration" // Not a man page.
 
diff --git a/bpkg/help-options.cli b/bpkg/help.cli
index 4be6f10..69e818c 100644
--- a/bpkg/help-options.cli
+++ b/bpkg/help.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/help-options.cli
+// file      : bpkg/help.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-help"
diff --git a/bpkg/pkg-build-options.cli b/bpkg/pkg-build.cli
index 39b96f1..54e0252 100644
--- a/bpkg/pkg-build-options.cli
+++ b/bpkg/pkg-build.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-build-options.cli
+// file      : bpkg/pkg-build.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-build"
diff --git a/bpkg/pkg-clean-options.cli b/bpkg/pkg-clean.cli
index 0d10d5e..9452291 100644
--- a/bpkg/pkg-clean-options.cli
+++ b/bpkg/pkg-clean.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-clean-options.cli
+// file      : bpkg/pkg-clean.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-clean"
diff --git a/bpkg/pkg-configure-options.cli b/bpkg/pkg-configure.cli
index 0f4084f..4ef9707 100644
--- a/bpkg/pkg-configure-options.cli
+++ b/bpkg/pkg-configure.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-configure-options.cli
+// file      : bpkg/pkg-configure.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-configure"
diff --git a/bpkg/pkg-disfigure-options.cli b/bpkg/pkg-disfigure.cli
index 31bf1b8..6f5c80b 100644
--- a/bpkg/pkg-disfigure-options.cli
+++ b/bpkg/pkg-disfigure.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-disfigure-options.cli
+// file      : bpkg/pkg-disfigure.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-disfigure"
diff --git a/bpkg/pkg-drop-options.cli b/bpkg/pkg-drop.cli
index 7c8f7dc..6ec7130 100644
--- a/bpkg/pkg-drop-options.cli
+++ b/bpkg/pkg-drop.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-drop-options.cli
+// file      : bpkg/pkg-drop.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-drop"
diff --git a/bpkg/pkg-fetch-options.cli b/bpkg/pkg-fetch.cli
index 02a8192..ba1d5d9 100644
--- a/bpkg/pkg-fetch-options.cli
+++ b/bpkg/pkg-fetch.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-fetch-options.cli
+// file      : bpkg/pkg-fetch.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-fetch"
diff --git a/bpkg/pkg-install-options.cli b/bpkg/pkg-install.cli
index f6d410b..0c1385b 100644
--- a/bpkg/pkg-install-options.cli
+++ b/bpkg/pkg-install.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-install-options.cli
+// file      : bpkg/pkg-install.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-install"
diff --git a/bpkg/pkg-purge-options.cli b/bpkg/pkg-purge.cli
index 05fe716..da618d3 100644
--- a/bpkg/pkg-purge-options.cli
+++ b/bpkg/pkg-purge.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-purge-options.cli
+// file      : bpkg/pkg-purge.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-purge"
diff --git a/bpkg/pkg-status-options.cli b/bpkg/pkg-status.cli
index bd2959c..fb20f78 100644
--- a/bpkg/pkg-status-options.cli
+++ b/bpkg/pkg-status.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-status-options.cli
+// file      : bpkg/pkg-status.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-status"
diff --git a/bpkg/pkg-uninstall-options.cli b/bpkg/pkg-uninstall.cli
index 5e68ec3..536f6ec 100644
--- a/bpkg/pkg-uninstall-options.cli
+++ b/bpkg/pkg-uninstall.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-uninstall-options.cli
+// file      : bpkg/pkg-uninstall.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-uninstall"
diff --git a/bpkg/pkg-unpack-options.cli b/bpkg/pkg-unpack.cli
index f5f2fd5..847ecb2 100644
--- a/bpkg/pkg-unpack-options.cli
+++ b/bpkg/pkg-unpack.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-unpack-options.cli
+// file      : bpkg/pkg-unpack.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-unpack"
diff --git a/bpkg/pkg-update-options.cli b/bpkg/pkg-update.cli
index 37d838e..09a5f59 100644
--- a/bpkg/pkg-update-options.cli
+++ b/bpkg/pkg-update.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-update-options.cli
+// file      : bpkg/pkg-update.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/configuration-options.cli>;
+include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-update"
diff --git a/bpkg/pkg-verify-options.cli b/bpkg/pkg-verify.cli
index 7a94f25..850b7d4 100644
--- a/bpkg/pkg-verify-options.cli
+++ b/bpkg/pkg-verify.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/pkg-verify-options.cli
+// file      : bpkg/pkg-verify.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-verify"
diff --git a/bpkg/rep-create-options.cli b/bpkg/rep-create.cli
index 4969dd9..b472cfc 100644
--- a/bpkg/rep-create-options.cli
+++ b/bpkg/rep-create.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/rep-create-options.cli
+// file      : bpkg/rep-create.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-rep-create"
diff --git a/bpkg/rep-info-options.cli b/bpkg/rep-info.cli
index 2d8b45e..0db3004 100644
--- a/bpkg/rep-info-options.cli
+++ b/bpkg/rep-info.cli
@@ -1,8 +1,8 @@
-// file      : bpkg/rep-info-options.cli
+// file      : bpkg/rep-info.cli
 // copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 // license   : MIT; see accompanying LICENSE file
 
-include <bpkg/common-options.cli>;
+include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-rep-info"
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..ada8beb
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+bpkg*.xhtml
+bpkg*.1
diff --git a/doc/cli.sh b/doc/cli.sh
new file mode 100755
index 0000000..d022a47
--- /dev/null
+++ b/doc/cli.sh
@@ -0,0 +1,58 @@
+#! /usr/bin/env bash
+
+version="0.2.0"
+date="XX January 2016"
+
+trap 'exit 1' ERR
+set -o errtrace # Trap in functions.
+
+function info () { echo "$*" 1>&2; }
+function error () { info "$*"; exit 1; }
+
+while [ $# -gt 0 ]; do
+  case $1 in
+    --clean)
+      rm -f bpkg*.xhtml bpkg*.1
+      exit 0
+      ;;
+    *)
+      error "unexpected $1"
+      ;;
+  esac
+done
+
+function compile ()
+{
+  local n=$1; shift
+
+  # Use a bash array to handle empty arguments.
+  #
+  local o=()
+  while [ $# -gt 0 ]; do
+    o=("${o[@]}" "$1")
+    shift
+  done
+
+  cli -I .. -v version="$version" -v date="$date" --include-base-last "${o[@]}" \
+--generate-html --html-prologue-file prologue.xhtml --html-epilogue-file \
+epilogue.xhtml --html-suffix .xhtml ../bpkg/$n.cli
+
+  cli -I .. -v version="$version" -v date="$date" --include-base-last "${o[@]}" \
+--generate-man --man-prologue-file prologue.1 --man-epilogue-file epilogue.1 \
+--man-suffix .1 ../bpkg/$n.cli
+}
+
+o="--output-prefix bpkg- --class-doc bpkg::common_options=short"
+
+# A few special cases.
+#
+compile "common" $o --output-suffix "-options" --class-doc bpkg::common_options=long
+compile "bpkg" $o --output-prefix "" --suppress-undocumented --class-doc bpkg::commands=short --class-doc bpkg::topics=short
+
+pages="cfg-add cfg-create cfg-fetch help pkg-build pkg-clean pkg-configure \
+pkg-disfigure pkg-drop pkg-fetch pkg-install pkg-purge pkg-status \
+pkg-uninstall pkg-unpack pkg-update pkg-verify rep-create rep-info"
+
+for p in $pages; do
+  compile $p $o
+done
diff --git a/doc/epilogue.1 b/doc/epilogue.1
new file mode 100644
index 0000000..584f1c0
--- /dev/null
+++ b/doc/epilogue.1
@@ -0,0 +1,7 @@
+.SH BUGS
+Send bug reports to the @@ mailing list.
+.SH COPYRIGHT
+Copyright (c) 2014-2016 Code Synthesis Ltd
+
+Permission is granted to copy, distribute and/or modify this document under
+the terms of the MIT License.
diff --git a/doc/epilogue.xhtml b/doc/epilogue.xhtml
new file mode 100644
index 0000000..a835371
--- /dev/null
+++ b/doc/epilogue.xhtml
@@ -0,0 +1,11 @@
+  <h1>BUGS</h1>
+
+  <p>Send bug reports to the <a href="mailto:@@">@@</a> mailing list.</p>
+
+</div>
+
+<div id="footer">&#169; 2014-2016 Code Synthesis Ltd<br/>
+                 Distributed under the terms of the MIT License</div>
+
+</body>
+</html>
diff --git a/doc/prologue.1 b/doc/prologue.1
new file mode 100644
index 0000000..9a71279
--- /dev/null
+++ b/doc/prologue.1
@@ -0,0 +1,6 @@
+.\" Process this file with
+.\" groff -man -Tascii $name$.$section$
+.\"
+.TH $name$ $section$ "$date$" "bpkg $version$"
+.SH NAME
+\fB$name$\fR \- $summary$
diff --git a/doc/prologue.xhtml b/doc/prologue.xhtml
new file mode 100644
index 0000000..a307d1f
--- /dev/null
+++ b/doc/prologue.xhtml
@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta charset="UTF-8"/>
+  <title>$name$($section$) bpkg $version$</title>
+  <style type="text/css">
+    html
+    {
+      font-family: sans-serif;
+      font-weight: normal;
+      font-size:   18px;
+      line-height: 1.4em;
+
+      text-align: justify;
+    }
+
+    body {margin: 0;}
+    body {min-width: 17em;}
+    @media only screen and (min-width: 360px)
+    {
+      body {min-width: 19em;}
+    }
+
+    #content
+    {
+      max-width: 40em;
+      margin: 0 auto 0 auto;
+      padding: 0 .4em 0 1.5em;
+    }
+
+    #footer
+    {
+      color: #666;
+      font-size: 0.833em;
+      line-height: 1.3em;
+      text-align: center;
+      margin: 2.2em 0 1em 0;
+    }
+
+    h1
+    {
+      color: #333;
+      font-weight: normal;
+      font-size: 1.58em;
+      line-height: 1.4em;
+
+      margin: 1.6em 0 .6em -.92em;
+    }
+
+    code, pre {font-size: 0.94em;}
+
+    .options {
+      margin: 1em 0 1em 0;
+    }
+
+    .options dt {
+      margin: 1em 0 0 0;
+    }
+
+    .options dd {
+      margin: .1em 0 0 4.5em;
+    }
+  </style>
+</head>
+<body>
+<div id="content">
+
+  <h1>NAME</h1>
+
+  <p><b><code>$name$</code></b> &#8211; $summary$</p>