Docs, CI, and tools for building man pages.

.github/workflows/main.yml

@@ -23,6 +23,7 @@ jobs:
     - run: cd crates/crates-io && cargo fmt --all -- --check
     - run: cd crates/resolver-tests && cargo fmt --all -- --check
     - run: cd crates/cargo-platform && cargo fmt --all -- --check
+    - run: cd crates/mdman && cargo fmt --all -- --check
 
   test:
     runs-on: ${{ matrix.os }}
@@ -65,6 +66,7 @@ jobs:
     - run: cargo test --features 'deny-warnings'
     - run: cargo test --features 'deny-warnings' -p cargo-test-support
     - run: cargo test -p cargo-platform
+    - run: cargo test --manifest-path crates/mdman/Cargo.toml
 
   resolver:
     runs-on: ubuntu-latest
@@ -89,6 +91,7 @@ jobs:
     - uses: actions/checkout@v2
     - run: rustup update nightly && rustup default nightly
     - run: rustup component add rust-docs
+    - run: ci/validate-man.sh
     - run: |
         mkdir mdbook
         curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.3.7/mdbook-v0.3.7-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook

ci/validate-man.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# This script validates that there aren't any changes to the man pages.
+
+set -e
+
+cd src/doc
+
+changes=$(git status --porcelain .)
+if [ -n "$changes" ]
+then
+    echo "git directory must be clean before running this script."
+    exit 1
+fi
+
+./build-man.sh
+
+changes=$(git status --porcelain .)
+if [ -n "$changes" ]
+then
+    echo "Detected changes in man pages:"
+    echo "$changes"
+    echo
+    echo "Please run './build-man.sh' in the src/doc directory to rebuild the"
+    echo "man pages, and commit the changes."
+    exit 1
+fi

src/doc/README.md

@@ -1,17 +1,17 @@
 # Cargo documentation
 
-This directory contains Cargo's documentation. There are two parts, [The Cargo Book]
-which is built with [mdbook] and the man pages, which are built with [Asciidoctor].
-The man pages are also included in The Cargo Book as HTML.
+This directory contains Cargo's documentation. There are two parts, [The Cargo
+Book] which is built with [mdbook] and the man pages, which are built with
+[mdman].
 
 [The Cargo Book]: https://doc.rust-lang.org/cargo/
+[mdBook]: https://github.com/rust-lang/mdBook
+[mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/
 
 ### Building the book
 
 Building the book requires [mdBook]. To get it:
 
-[mdBook]: https://github.com/rust-lang/mdBook
-
 ```console
 $ cargo install mdbook
 ```
@@ -35,27 +35,27 @@ every file must be linked there.
 
 ### Building the man pages
 
-Building the man pages requires [Asciidoctor]. See the linked page for
-installation instructions. It also requires the `make` build tool and `ruby`.
+The man pages use a tool called [mdman] to convert markdown to a man page
+format. Check out the documentation at
+[`mdman/doc/`](../../crates/mdman/doc/)
+for more details.
 
-[Asciidoctor]: https://asciidoctor.org/
+The man pages are converted from a templated markdown (located in the
+[`src/doc/man/`](man)
+directory) to three different formats:
 
-The source files are located in the [`src/doc/man`](man) directory. The
-[`Makefile`](Makefile) is used to rebuild the man pages. It outputs the man
-pages into [`src/etc/man`](../etc/man) and the HTML versions into
-[`src/doc/man/generated`](man/generated). The Cargo Book has some markdown
-stub files in [`src/doc/src/commands`](src/commands) which load the generated
-HTML files.
+1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man).
+2. Markdown (with some HTML) for the Cargo Book, saved in
+   [`src/doc/src/commands/`](src/commands).
+3. Plain text (needed for embedded man pages on platforms without man such as
+   Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt).
 
-To build the man pages, run `make` in the `src/doc` directory:
+To rebuild the man pages, run the script `build-man.sh` in the `src/doc` directory.
 
 ```console
-$ make
+$ ./build-man.sh
 ```
 
-The build script uses a few Asciidoctor extensions. See
-[`asciidoc-extension.rb`](asciidoc-extension.rb) for details.
-
 ## Contributing
 
 We'd love your help with improving the documentation! Please feel free to

src/doc/build-man.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+#
+# This script builds the Cargo man pages.
+#
+# The source for the man pages are located in src/doc/man/ in markdown format.
+# These also are handlebars templates, see crates/mdman/README.md for details.
+#
+# The generated man pages are placed in the src/etc/man/ directory. The pages
+# are also expanded into markdown (after being expanded by handlebars) and
+# saved in the src/doc/src/commands/ directory. These are included in the
+# Cargo book, which is converted to HTML by mdbook.
+
+set -e
+
+OPTIONS="--url https://doc.rust-lang.org/cargo/commands/ \
+    --man rustc:1=https://doc.rust-lang.org/rustc/index.html \
+    --man rustdoc:1=https://doc.rust-lang.org/rustdoc/index.html"
+
+cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \
+    -t md -o src/commands man/cargo*.md \
+    $OPTIONS
+
+cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \
+    -t txt -o man/generated_txt man/cargo*.md \
+    $OPTIONS
+
+cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \
+    -t man -o ../etc/man man/cargo*.md \
+    $OPTIONS

src/doc/theme/head.hbs

@@ -0,0 +1,5 @@
+<style>
+    dd {
+        margin-bottom: 1em;
+    }
+</style>