Auto merge of #6405 - ehuss:new-man, r=alexcrichton

New man pages.

This is a rewrite and update of the man pages. This also adds them to the website documentation. They are now in Asciidoc format to make it easy to output multiple formats and have decent formatting. There is a Makefile with instructions on how to rebuild the man pages.

Closes #5729.

src/doc/Makefile

@@ -0,0 +1,28 @@
+# 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/src/commands/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,src/commands/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): src/commands/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 $@

src/doc/asciidoc-extension.rb

@@ -0,0 +1,109 @@
+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 = 'commands/index.html'
+      else
+        html_target = %(commands/#{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 (using mdbook's 0.1's base-style
+# links). 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'
+      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
+
+# 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
+end

src/doc/man/cargo-bench.adoc

@@ -0,0 +1,139 @@
+= cargo-bench(1)
+:doctype: manpage
+:actionverb: Benchmark
+:nouns: benchmarks
+
+== NAME
+
+cargo-bench - Execute benchmarks of a package
+
+== SYNOPSIS
+
+`cargo bench [_OPTIONS_] [BENCHNAME] [-- _BENCH-OPTIONS_]`
+
+== DESCRIPTION
+
+Compile and execute benchmarks.
+
+The benchmark filtering argument `BENCHNAME` and all the arguments following
+the two dashes (`--`) are passed to the benchmark binaries and thus to
+_libtest_ (rustc's built in unit-test and micro-benchmarking framework).  If
+you're passing arguments to both Cargo and the binary, the ones after `--` go
+to the binary, the ones before go to Cargo.  For details about libtest's
+arguments see the output of `cargo bench -- --help`.  As an example, this will
+run only the benchmark named `foo` (and skip other similarly named benchmarks
+like `foobar`):
+
+    cargo bench -- foo --exact
+
+Benchmarks are built with the `--test` option to `rustc` which creates an
+executable with a `main` function that automatically runs all functions
+annotated with the `#[bench]` attribute. The libtest harness may be disabled
+by setting `harness = false` in the target manifest settings, in which case
+your code will need to provide its own `main` function to handle running
+benchmarks.
+
+== OPTIONS
+
+=== Benchmark Options
+
+include::options-test.adoc[]
+
+=== Package Selection
+
+include::options-packages.adoc[]
+
+=== Target Selection
+
+When no target selection options are given, `cargo bench` will build the
+following targets of the selected packages:
+
+- lib – used to link with binaries and benchmarks
+- bins (only if benchmark targets are built and required features are
+  available)
+- lib as a benchmark
+- bins as benchmarks
+- benchmark targets
+
+The default behavior can be changed by setting the `bench` flag for the target
+in the manifest settings. Setting examples to `bench = true` will build and
+run the example as a benchmark. Setting targets to `bench = false` will stop
+them from being benchmarked by default. Target selection options that take a
+target by name ignore the `bench` flag and will always benchmark the given
+target.
+
+include::options-targets.adoc[]
+
+include::options-features.adoc[]
+
+=== Compilation Options
+
+include::options-target-triple.adoc[]
+
+=== Output Options
+
+include::options-target-dir.adoc[]
+
+=== Display Options
+
+By default the Rust test harness hides output from benchmark execution to keep
+results readable. Benchmark output can be recovered (e.g. for debugging) by
+passing `--nocapture` to the benchmark binaries:
+
+    cargo bench -- --nocapture
+
+include::options-display.adoc[]
+
+include::options-message-format.adoc[]
+
+=== Manifest Options
+
+include::options-manifest-path.adoc[]
+
+include::options-locked.adoc[]
+
+=== Common Options
+
+include::options-common.adoc[]
+
+=== Miscellaneous Options
+
+The `--jobs` argument affects the building of the benchmark executable but
+does not affect how many threads are used when running the benchmarks. The
+Rust test harness runs benchmarks serially in a single thread.
+
+include::options-jobs.adoc[]
+
+== PROFILES
+
+Profiles may be used to configure compiler options such as optimization levels
+and debug settings. See
+linkcargo:reference/manifest.html#the-profile-sections[the reference]
+for more details.
+
+Benchmarks are always built with the `bench` profile. Binary and lib targets
+are built separately as benchmarks with the `bench` profile. Library targets
+are built with the `release` profiles when linked to binaries and benchmarks.
+Dependencies use the `release` profile.
+
+If you need a debug build of a benchmark, try building it with
+man:cargo-build[1] which will use the `test` profile which is by default
+unoptimized and includes debug information. You can then run the debug-enabled
+benchmark manually.
+
+include::section-environment.adoc[]
+
+include::section-exit-status.adoc[]
+
+== EXAMPLES
+
+. Build and execute all the benchmarks of the current package:
+
+    cargo bench
+
+. Run only a specific benchmark within a specific benchmark target:
+
+    cargo bench --bench bench_name -- modname::some_benchmark
+
+== SEE ALSO
+man:cargo[1], man:cargo-test[1]

src/doc/man/cargo-build.adoc

@@ -0,0 +1,93 @@
+= cargo-build(1)
+:doctype: manpage
+:actionverb: Build
+
+== NAME
+
+cargo-build - Compile the current package
+
+== SYNOPSIS
+
+`cargo build [_OPTIONS_]`
+
+== DESCRIPTION
+
+Compile local packages and all of their dependencies.
+
+== OPTIONS
+
+=== Package Selection
+
+include::options-packages.adoc[]
+
+=== Target Selection
+
+When no target selection options are given, `cargo build` will build all
+binary and library targets of the selected packages. Binaries are skipped if
+they have `required-features` that are missing.
+
+include::options-targets.adoc[]
+
+include::options-features.adoc[]
+
+=== Compilation Options
+
+include::options-target-triple.adoc[]
+
+include::options-release.adoc[]
+
+=== Output Options
+
+include::options-target-dir.adoc[]
+
+*--out-dir* _DIRECTORY_::
+    Copy final artifacts to this directory.
++
+This option is unstable and available only on the nightly channel and requires
+the `-Z unstable-options` flag to enable.
+
+=== Display Options
+
+include::options-display.adoc[]
+
+include::options-message-format.adoc[]
+
+*--build-plan*::
+    Outputs a series of JSON messages to stdout that indicate the commands to
+    run the build.
++
+This option is unstable and available only on the nightly channel and requires
+the `-Z unstable-options` flag to enable.
+
+=== Manifest Options
+
+include::options-manifest-path.adoc[]
+
+include::options-locked.adoc[]
+
+=== Common Options
+
+include::options-common.adoc[]
+
+=== Miscellaneous Options
+
+include::options-jobs.adoc[]
+
+include::section-profiles.adoc[]
+
+include::section-environment.adoc[]
+
+include::section-exit-status.adoc[]
+
+== EXAMPLES
+
+. Build the local package and all of its dependencies:
+
+    cargo build
+
+. Build with optimizations:
+
+    cargo build --release
+
+== SEE ALSO
+man:cargo[1], man:cargo-rustc[1]