Auto merge of #8577 - ehuss:mdman, r=alexcrichton

Add mdman for generating man pages.

This introduces a new utility called `mdman` that converts a markdown-formatted document to a man page. This replaces asciidoctor, with the intent to make it easier to contribute, easier to have consistent formatting across platforms, and easier to generate plain-text documents for use on Windows (for #8456). This also includes a number of formatting fixes.

There is some documentation in the `mdman/doc` directory explaining how to use it, and the docs in `src/doc/README.md` have been updated (this explains the structure of the files). The Makefile has been replaced with a simple shell script.

CI has been updated to verify the checked-in docs are up-to-date. Perhaps in the future, these can be generated automatically (perhaps by `build.rs`?), but since that requires a bit of build system work (like upstream rust), this is deferred till later.

.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