New man pages.

Author: ehuss

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]