Auto merge of #8456 - ehuss:embedded-man, r=alexcrichton

Display embedded man pages for built-in commands.

This changes `cargo help COMMAND` to display the man page for the given command.  `cargo COMMAND --help` continues to show the basic clap output.

The man pages are embedded in the executable in a compressed format. There's also a copy of the man pages in text format for platforms that do not have the `man` executable (like Windows).

It is unfortunate to check in more pre-generated files. I hope in the future that the usage of asciidoc can be replaced with something else (possibly a custom markdown-based solution).

cc #6104

Author: bors

Cargo.toml

@@ -106,6 +106,10 @@ features = [
 cargo-test-macro = { path = "crates/cargo-test-macro", version = "0.1.0" }
 cargo-test-support = { path = "crates/cargo-test-support", version = "0.1.0" }
 
+[build-dependencies]
+flate2 = { version = "1.0.3", default-features = false, features = ["zlib"] }
+tar = { version = "0.4.26", default-features = false }
+
 [[bin]]
 name = "cargo"
 test = false

build.rs

@@ -0,0 +1,34 @@
+use flate2::{Compression, GzBuilder};
+use std::ffi::OsStr;
+use std::fs;
+use std::path::Path;
+
+fn main() {
+    compress_man();
+}
+
+fn compress_man() {
+    let out_path = Path::new(&std::env::var("OUT_DIR").unwrap()).join("man.tgz");
+    let dst = fs::File::create(out_path).unwrap();
+    let encoder = GzBuilder::new()
+        .filename("man.tar")
+        .write(dst, Compression::best());
+    let mut ar = tar::Builder::new(encoder);
+
+    let mut add_files = |dir, extension| {
+        for entry in fs::read_dir(dir).unwrap() {
+            let path = entry.unwrap().path();
+            if path.extension() != Some(extension) {
+                continue;
+            }
+            println!("cargo:rerun-if-changed={}", path.display());
+            ar.append_path_with_name(&path, path.file_name().unwrap())
+                .unwrap();
+        }
+    };
+
+    add_files(Path::new("src/etc/man"), OsStr::new("1"));
+    add_files(Path::new("src/doc/man/generated_txt"), OsStr::new("txt"));
+    let encoder = ar.into_inner().unwrap();
+    encoder.finish().unwrap();
+}

src/bin/cargo/cli.rs

@@ -10,6 +10,11 @@ pub fn main(config: &mut Config) -> CliResult {
     // CAUTION: Be careful with using `config` until it is configured below.
     // In general, try to avoid loading config values unless necessary (like
     // the [alias] table).
+
+    if commands::help::handle_embedded_help(config) {
+        return Ok(());
+    }
+
     let args = match cli().get_matches_safe() {
         Ok(args) => args,
         Err(e) => {

src/bin/cargo/commands/bench.rs

@@ -45,30 +45,7 @@ pub fn cli() -> App {
             "Run all benchmarks regardless of failure",
         ))
         .arg_unit_graph()
-        .after_help(
-            "\
-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`.
-
-If the `--package` argument is given, then SPEC is a package ID specification
-which indicates which package should be benchmarked. If it is not given, then
-the current package is benchmarked. For more information on SPEC and its format,
-see the `cargo help pkgid` command.
-
-All packages in the workspace are benchmarked if the `--workspace` flag is supplied. The
-`--workspace` flag is automatically assumed for a virtual manifest.
-Note that `--exclude` has to be specified in conjunction with the `--workspace` flag.
-
-The `--jobs` argument affects the building of the benchmark executable but does
-not affect how many jobs are used when running the benchmarks.
-
-Compilation can be customized with the `bench` profile in the manifest.
-",
-        )
+        .after_help("Run `cargo help bench` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {

src/bin/cargo/commands/build.rs

@@ -42,17 +42,7 @@ pub fn cli() -> App {
         .arg_message_format()
         .arg_build_plan()
         .arg_unit_graph()
-        .after_help(
-            "\
-All packages in the workspace are built if the `--workspace` flag is supplied. The
-`--workspace` flag is automatically assumed for a virtual manifest.
-Note that `--exclude` has to be specified in conjunction with the `--workspace` flag.
-
-Compilation can be configured via the use of profiles which are configured in
-the manifest. The default profile for this command is `dev`, but passing
-the --release flag will use the `release` profile instead.
-",
-        )
+        .after_help("Run `cargo help build` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {

src/bin/cargo/commands/check.rs

@@ -34,25 +34,7 @@ pub fn cli() -> App {
         .arg_manifest_path()
         .arg_message_format()
         .arg_unit_graph()
-        .after_help(
-            "\
-If the `--package` argument is given, then SPEC is a package ID specification
-which indicates which package should be built. If it is not given, then the
-current package is built. For more information on SPEC and its format, see the
-`cargo help pkgid` command.
-
-All packages in the workspace are checked if the `--workspace` flag is supplied. The
-`--workspace` flag is automatically assumed for a virtual manifest.
-Note that `--exclude` has to be specified in conjunction with the `--workspace` flag.
-
-Compilation can be configured via the use of profiles which are configured in
-the manifest. The default profile for this command is `dev`, but passing
-the `--release` flag will use the `release` profile instead.
-
-The `--profile test` flag can be used to check unit tests with the
-`#[cfg(test)]` attribute.
-",
-        )
+        .after_help("Run `cargo help check` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {

src/bin/cargo/commands/clean.rs

@@ -13,14 +13,7 @@ pub fn cli() -> App {
         .arg_release("Whether or not to clean release artifacts")
         .arg_profile("Clean artifacts of the specified profile")
         .arg_doc("Whether or not to clean just the documentation directory")
-        .after_help(
-            "\
-If the `--package` argument is given, then SPEC is a package ID specification
-which indicates which package's artifacts should be cleaned out. If it is not
-given, then all packages' artifacts are removed. For more information on SPEC
-and its format, see the `cargo help pkgid` command.
-",
-        )
+        .after_help("Run `cargo help clean` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {

src/bin/cargo/commands/doc.rs

@@ -31,22 +31,7 @@ pub fn cli() -> App {
         .arg_manifest_path()
         .arg_message_format()
         .arg_unit_graph()
-        .after_help(
-            "\
-By default the documentation for the local package and all dependencies is
-built. The output is all placed in `target/doc` in rustdoc's usual format.
-
-All packages in the workspace are documented if the `--workspace` flag is
-supplied. The `--workspace` flag is automatically assumed for a virtual
-manifest. Note that `--exclude` has to be specified in conjunction with the
-`--workspace` flag.
-
-If the `--package` argument is given, then SPEC is a package ID specification
-which indicates which package should be documented. If it is not given, then the
-current package is documented. For more information on SPEC and its format, see
-the `cargo help pkgid` command.
-",
-        )
+        .after_help("Run `cargo help doc` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {

src/bin/cargo/commands/fetch.rs

@@ -9,18 +9,7 @@ pub fn cli() -> App {
         .arg(opt("quiet", "No output printed to stdout").short("q"))
         .arg_manifest_path()
         .arg_target_triple("Fetch dependencies for the target triple")
-        .after_help(
-            "\
-If a lock file is available, this command will ensure that all of the Git
-dependencies and/or registries dependencies are downloaded and locally
-available. The network is never touched after a `cargo fetch` unless
-the lock file changes.
-
-If the lock file is not available, then this is the equivalent of
-`cargo generate-lockfile`. A lock file is generated and dependencies are also
-all updated.
-",
-        )
+        .after_help("Run `cargo help fetch` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {

src/bin/cargo/commands/fix.rs

@@ -72,37 +72,7 @@ pub fn cli() -> App {
                 .long("allow-staged")
                 .help("Fix code even if the working directory has staged changes"),
         )
-        .after_help(
-            "\
-This Cargo subcommand will automatically take rustc's suggestions from
-diagnostics like warnings and apply them to your source code. This is intended
-to help automate tasks that rustc itself already knows how to tell you to fix!
-The `cargo fix` subcommand is also being developed for the Rust 2018 edition
-to provide code the ability to easily opt-in to the new edition without having
-to worry about any breakage.
-
-Executing `cargo fix` will under the hood execute `cargo check`. Any warnings
-applicable to your crate will be automatically fixed (if possible) and all
-remaining warnings will be displayed when the check process is finished. For
-example if you'd like to prepare for the 2018 edition, you can do so by
-executing:
-
-    cargo fix --edition
-
-which behaves the same as `cargo check --all-targets`. Similarly if you'd like
-to fix code for different platforms you can do:
-
-    cargo fix --edition --target x86_64-pc-windows-gnu
-
-or if your crate has optional features:
-
-    cargo fix --edition --no-default-features --features foo
-
-If you encounter any problems with `cargo fix` or otherwise have any questions
-or feature requests please don't hesitate to file an issue at
-https://github.com/rust-lang/cargo
-",
-        )
+        .after_help("Run `cargo help fix` for more detailed information.\n")
 }
 
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {