- 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 }}
- 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
- 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
--- /dev/null
+#!/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
+++ /dev/null
-# This Makefile is used to build the Cargo man pages.
-#
-# The source for the man pages are located in src/doc/man in Asciidoctor
-# format. See https://asciidoctor.org/ for more information.
-#
-# Just run `make` and it will generate the man pages in src/etc/man and the
-# HTML pages in src/doc/man/generated.
-#
-# There are some Asciidoctor extensions, see the file `asciidoc-extensions.rb`
-# for the documentation.
-
-MAN_SOURCE = $(sort $(wildcard man/cargo*.adoc))
-COMMANDS = $(notdir $(MAN_SOURCE))
-HTML = $(patsubst %.adoc,man/generated/%.html,$(COMMANDS))
-MAN_LOCATION = ../etc/man
-MAN = $(patsubst %.adoc,$(MAN_LOCATION)/%.1,$(COMMANDS))
-ASCIIDOCOPTS = -r ./asciidoc-extension.rb
-OTHER_DEPS = asciidoc-extension.rb $(filter-out $(MAN_SOURCE),$(sort $(wildcard man/*.adoc)))
-
-all: commands-html man
-commands-html: $(HTML)
-man: $(MAN)
-
-$(HTML): man/generated/%.html : man/%.adoc asciidoc-extension.rb $(OTHER_DEPS)
- asciidoctor $(ASCIIDOCOPTS) -s $< -o $@
-
-$(MAN): $(MAN_LOCATION)/%.1 : man/%.adoc $(OTHER_DEPS)
- asciidoctor $(ASCIIDOCOPTS) -b manpage $< -o $@
# 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
```
### 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
+++ /dev/null
-require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
-
-include Asciidoctor
-
-# An inline macro that generates links to related man pages.
-#
-# Usage
-#
-# man:gittutorial[7]
-#
-class ManInlineMacro < Extensions::InlineMacroProcessor
- use_dsl
-
- named :man
- name_positional_attributes 'volnum'
-
- def process parent, target, attrs
- manname = target
- suffix = if (volnum = attrs['volnum'])
- "(#{volnum})"
- else
- nil
- end
- text = %(#{manname}#{suffix})
- if parent.document.basebackend? 'html'
- parent.document.register :links, target
- if manname == 'rustc'
- html_target = 'https://doc.rust-lang.org/rustc/index.html'
- elsif manname == 'rustdoc'
- html_target = 'https://doc.rust-lang.org/rustdoc/index.html'
- elsif manname == 'cargo'
- html_target = 'index.html'
- else
- html_target = %(#{manname}.html)
- end
- %(#{(create_anchor parent, text, type: :link, target: html_target).render})
- elsif parent.document.backend == 'manpage'
- %(\x1b\\fB#{manname}\x1b\\fP#{suffix})
- else
- text
- end
- end
-end
-
-# Creates a link to something in the cargo documentation.
-#
-# For HTML this creates a relative link. For the man page it gives a direct
-# link to doc.rust-lang.org.
-#
-# Usage
-#
-# linkcargo:reference/manifest.html[the manifest]
-#
-class LinkCargoInlineMacro < Extensions::InlineMacroProcessor
- use_dsl
-
- named :linkcargo
- name_positional_attributes 'text'
-
- def process parent, target, attrs
- text = attrs['text']
- if parent.document.basebackend? 'html'
- target = %(../#{target})
- parent.document.register :links, target
- %(#{(create_anchor parent, text, type: :link, target: target).render})
- elsif parent.document.backend == 'manpage'
- target = %(https://doc.rust-lang.org/cargo/#{target})
- %(#{(create_anchor parent, text, type: :link, target: target).render})
- else
- %(#{text} <#{target}>)
- end
- end
-end
-
-# Backticks in the manpage renderer use the CR font (courier), but in most
-# cases in a terminal this doesn't look any different. Instead, use bold which
-# should follow man page conventions better.
-class MonoPostprocessor < Extensions::Postprocessor
- def process document, output
- if document.basebackend? 'manpage'
- output = output.gsub(/\\f\(CR/, '\\fB')
- end
- output
- end
-end
-
-# Man pages are ASCII only. Unfortunately asciidoc doesn't process these
-# characters for us. The `cargo tree` manpage needs a little assistance.
-class SpecialCharPostprocessor < Extensions::Postprocessor
- def process document, output
- if document.basebackend? 'manpage'
- output = output.gsub(/│/, '|')
- .gsub(/├/, '|')
- .gsub(/└/, '`')
- .gsub(/─/, '\-')
- end
- output
- end
-end
-
-# General utility for converting text. Example:
-#
-# convert:lowercase[{somevar}]
-class ConvertInlineMacro < Extensions::InlineMacroProcessor
- use_dsl
-
- named :convert
- name_positional_attributes 'text'
-
- def process parent, target, attrs
- text = attrs['text']
- case target
- when 'lowercase'
- text.downcase
- end
- end
-end
-
-Extensions.register :uri_schemes do
- inline_macro ManInlineMacro
- inline_macro LinkCargoInlineMacro
- inline_macro ConvertInlineMacro
- postprocessor MonoPostprocessor
- postprocessor SpecialCharPostprocessor
-end
--- /dev/null
+#!/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
+++ /dev/null
-<style>
- /* Include some space between definition elements. */
- dd {
- margin-bottom: 1em;
- }
- /* asciidoctor includes extra <p> tags which causes too much spacing. */
- dd p {
- margin-top: 0;
- }
- li p {
- margin: 0;
- }
- /* asciidoctor uses a content class which conflicts with mdbook's content
- class which causes too much spacing. */
- .content {
- padding-bottom: 0;
- }
-</style>
--- /dev/null
+<style>
+ dd {
+ margin-bottom: 1em;
+ }
+</style>
projects / cargo.git / commitdiff