doc: Convert all help files to manpages

Now `crucible help $COMMAND` opens the manpage crucible-$COMMAND(1).

Documenting Crucible with manpages allows the help text to flow to the
terminal width. Manpages also allow us to write well-formatted
documentation in a standard, easily-recognizable layout.

The manpages are built with asciidoc. (I followed Git as a precedent,
which also uses asciidoc). configure.ac now requires the programs
'asciidoc' and 'a2x', which are configured through the precious
variables ASCIIDOC and A2X.

12 files changed, 167 insertions, 80 deletions

diff --git a/doc/crucible-bootstrap.1.txt b/doc/crucible-bootstrap.1.txt
new file mode 100644
index 0000000..319c70d
--- /dev/null
+++ b/doc/crucible-bootstrap.1.txt
@@ -0,0 +1,16 @@
+crucible-bootstrap(1)
+=====================
+:doctype: manpage
+
+NAME
+----
+crucible-bootstrap - bootstrap test data
+
+SYNOPSIS
+--------
+[verse]
+*crucible bootstrap* <test-name> [--width <image-width>] [--height <image-height>]
+
+DESCRIPTION
+-----------
+TODO
diff --git a/doc/crucible-bootstrap.txt b/doc/crucible-bootstrap.txt
deleted file mode 100644
index eb03dd7..0000000
--- a/doc/crucible-bootstrap.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-NAME
-    crucible booststrap - bootstrap test data
-
-SYNOPSIS
-    crucible bootstrap <test-name>
-        [--width <image-width>]
-        [--height <image-height>]
-
-DESCRIPTION
-    TODO
diff --git a/doc/crucible-help.1.txt b/doc/crucible-help.1.txt
new file mode 100644
index 0000000..e973f03
--- /dev/null
+++ b/doc/crucible-help.1.txt
@@ -0,0 +1,17 @@
+crucible-help(1)
+================
+:doctype: manpage
+
+NAME
+----
+crucible-help - show help about Crucible
+
+SYNOPSIS
+--------
+[verse]
+*crucible help* [<command-name>|<topic>]
+
+DESCRIPTION
+-----------
+Show help for the given command or topic. If none is given, then print help for
+the main crucible command.
diff --git a/doc/crucible-help.txt b/doc/crucible-help.txt
deleted file mode 100644
index 5b3f6c7..0000000
--- a/doc/crucible-help.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-NAME
-    crucible help - show help about Crucible
-
-SYNOPSIS
-    crucible help [<command-name>|<topic>]
-
-DESCRIPTION
-    Show help for the given command or topic. If none is given, then print help
-    for the main crucible command.
diff --git a/doc/crucible-ls-example-tests.1.txt b/doc/crucible-ls-example-tests.1.txt
new file mode 100644
index 0000000..5a12b0e
--- /dev/null
+++ b/doc/crucible-ls-example-tests.1.txt
@@ -0,0 +1,21 @@
+crucible-ls-example-tests(1)
+============================
+:doctype: manpage
+
+NAME
+----
+crucible-ls-example-tests - list names of example tests
+
+SYNOPSIS
+--------
+[verse]
+*crucible ls-example-tests*
+
+DESCRIPTION
+-----------
+List all example tests. Example tests are those whose names match the glob
+pattern "example.*".
+
+SEE ALSO
+--------
+*crucible-ls-tests(1)*
diff --git a/doc/crucible-ls-example-tests.txt b/doc/crucible-ls-example-tests.txt
deleted file mode 100644
index a859f57..0000000
--- a/doc/crucible-ls-example-tests.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-NAME
-    crucible ls-example-tests - list names of example tests
-
-SYNOPSIS
-    crucible ls-example-tests
-
-DESCRIPTION
-    This command takes no arguments.
diff --git a/doc/crucible-ls-tests.1.txt b/doc/crucible-ls-tests.1.txt
new file mode 100644
index 0000000..88a4b00
--- /dev/null
+++ b/doc/crucible-ls-tests.1.txt
@@ -0,0 +1,20 @@
+crucible-ls-tests(1)
+====================
+:doctype: manpage
+
+NAME
+----
+crucible-ls-tests - list test names
+
+SYNOPSIS
+--------
+[verse]
+*crucible ls-tests*
+
+DESCRIPTION
+-----------
+List all tests, except example tests.
+
+SEE ALSO
+--------
+*crucible-ls-example-tests(1)*
diff --git a/doc/crucible-ls-tests.txt b/doc/crucible-ls-tests.txt
deleted file mode 100644
index 83ba519..0000000
--- a/doc/crucible-ls-tests.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-NAME
-    crucible ls-tests - list test names
-
-SYNOPSIS
-    crucible ls-tests
-
-DESCRIPTION
-    This command takes no arguments.
diff --git a/doc/crucible-run.1.txt b/doc/crucible-run.1.txt
new file mode 100644
index 0000000..c070ff3
--- /dev/null
+++ b/doc/crucible-run.1.txt
@@ -0,0 +1,77 @@
+crucible-run(1)
+===============
+:doctype: manpage
+
+NAME
+----
+crucible-run - run tests
+
+SYNOPSIS
+--------
+[verse]
+*crucible run* [--no-cleanup] [--dump|--no-dump] [<pattern>...]
+
+DESCRIPTION
+-----------
+Run tests in the order given on the command line. If no tests are given, then
+run all tests (except example tests). The list of <pattern>s may consist of
+a mixture of literal test names and glob patterns.
+
+You can list all non-example tests with *crucible-ls-tests(1)*, and list
+examples tests with *crucible-ls-example-tests(1)*.  (Example tests are those
+whose names match "example.*").
+
+OPTIONS
+-------
+--no-cleanup::
+    Disable each test's cleanup phase. This is useful because a test may crash
+    during cleanup but otherwise pass.
+
+--dump, --no-dump [default: disabled]::
+    Dump (or disable dumping) test images into Crucible's data directory.
+
+EXAMPLES
+--------
+* Run all tests (except example tests).
++
+----
+$ crucible run
+----
+
+* Run all example tests.
++
+----
+$ crucible run 'example.*'
+----
+
+* Run all functional and stress tests.
++
+----
+$ crucible run 'functional.*' 'stress.*'
+----
+
+* Run one test.
++
+----
+$ crucible run functional.miptree.2d.levels01
+----
+
+* Run multiple tests by name.
++
+----
+$ crucible run functional.miptree.2d.levels01 \
+               functional.miptree.2d.levels02 \
+               functional.miptree.cubemap.levels09
+----
+
+* Run multiple tests by glob patterns.
++
+----
+$ crucible run 'functional.miptree.cubemap.*' \
+               'functional.txf.*'
+----
+
+SEE ALSO
+--------
+*crucible-ls-tests(1)*,
+*crucible-ls-example-tests(1)*
diff --git a/doc/crucible-run.txt b/doc/crucible-run.txt
deleted file mode 100644
index f61ecea..0000000
--- a/doc/crucible-run.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-NAME
-    crucible run - run tests
-
-SYNOPSIS
-    crucible run [--no-cleanup] [--dump|--no-dump] [<testname>...]
-
-DESCRIPTION
-    Run tests in the order given on the command line. If no tests are given
-    then run all tests. Example tests are not run, except those whose names
-    match a given glob pattern (see `crucible help ls-example-tests`).
-
-OPTIONS
-    --no-cleanup
-        Disable each test's cleanup phase. This is useful because a test may
-        crash during cleanup but otherwise pass.
-
-    --dump, --no-dump [default: --no-dump]
-        Dump (or disable dumping) test images into Crucible's data directory.
-
-EXAMPLES
-    Run all tests (except example tests).
-        $ crucible run
-
-    Run one test.
-        $ crucible run functional.miptree.2d.levels01
-
-    Run multiple tests.
-        $ crucible run functional.miptree.2d.levels01 \\
-                       functional.miptree.2d.levels02 \\
-                       functional.miptree.cubemap.levels09
-
-    Run tests that match glob patterns.
-        $ crucible run 'functional.miptree.cubemap.*' \\
-                       'functional.txf.*'
-
-    Run all example tests.
-        $ crucible run 'example.*'
diff --git a/doc/crucible-version.1.txt b/doc/crucible-version.1.txt
new file mode 100644
index 0000000..c968306
--- /dev/null
+++ b/doc/crucible-version.1.txt
@@ -0,0 +1,16 @@
+crucible-version(1)
+===================
+:doctype: manpage
+
+NAME
+----
+crucible-version - show version info
+
+SYNOPSIS
+---------
+[verse]
+*crucible version*
+
+DESCRIPTION
+-----------
+Just print Crucible's version. That's all :)
diff --git a/doc/crucible-version.txt b/doc/crucible-version.txt
deleted file mode 100644
index 3b9bed2..0000000
--- a/doc/crucible-version.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-NAME
-    crucible version - show version info
-
-SYNOPSIS
-    crucible version
-
-DESCRIPTION
-    This command takes no arguments.