Auto merge of #8793 - ehuss:fix-man-links, r=alexcrichton

Fix man page links inside `option` blocks.

Links inside `{{#option}}` blocks were erroneously being converted to absolute links when emitting the `md` format because they were being rendered as HTML.  This wasn't intended and caused some links to fail. It also causes problems for offline viewing (since the links are to an external website).

Also, man-page links like `{{man "cargo-foo" 1}}` were linking to `.md` extension, but since they are processed as markdown into HTML, mdbook's `.md` to `.html` translation wasn't getting applied. The simple fix is to always use `.html`.

This revealed a legitimate error in a link in `cargo-publish.md` which had the wrong anchor link (`#registrydefault`).

This also revealed that the CI check that the man pages are in sync wasn't working quite right (it was not checking the `etc/man` directory for changes).

Author: bors

ci/validate-man.sh

@@ -5,7 +5,7 @@ set -e
 
 cd src/doc
 
-changes=$(git status --porcelain .)
+changes=$(git status --porcelain)
 if [ -n "$changes" ]
 then
     echo "git directory must be clean before running this script."
@@ -14,7 +14,7 @@ fi
 
 ./build-man.sh
 
-changes=$(git status --porcelain .)
+changes=$(git status --porcelain)
 if [ -n "$changes" ]
 then
     echo "Detected changes in man pages:"

crates/mdman/src/format/md.rs

@@ -4,22 +4,20 @@ use crate::util::unwrap;
 use crate::ManMap;
 use anyhow::{bail, format_err, Error};
 use std::fmt::Write;
-use url::Url;
 
 pub struct MdFormatter {
-    url: Option<Url>,
     man_map: ManMap,
 }
 
 impl MdFormatter {
-    pub fn new(url: Option<Url>, man_map: ManMap) -> MdFormatter {
-        MdFormatter { url, man_map }
+    pub fn new(man_map: ManMap) -> MdFormatter {
+        MdFormatter { man_map }
     }
 }
 
 impl MdFormatter {
     fn render_html(&self, input: &str) -> Result<String, Error> {
-        let parser = crate::md_parser(input, self.url.clone());
+        let parser = crate::md_parser(input, None);
         let mut html_output: String = String::with_capacity(input.len() * 3 / 2);
         pulldown_cmark::html::push_html(&mut html_output, parser.map(|(e, _r)| e));
         Ok(html_output)
@@ -78,7 +76,7 @@ impl super::Formatter for MdFormatter {
     fn linkify_man_to_md(&self, name: &str, section: u8) -> Result<String, Error> {
         let s = match self.man_map.get(&(name.to_string(), section)) {
             Some(link) => format!("[{}({})]({})", name, section, link),
-            None => format!("[{}({})]({}.md)", name, section, name),
+            None => format!("[{}({})]({}.html)", name, section, name),
         };
         Ok(s)
     }

crates/mdman/src/lib.rs

@@ -50,7 +50,7 @@ pub fn convert(
 ) -> Result<String, Error> {
     let formatter: Box<dyn Formatter + Send + Sync> = match format {
         Format::Man => Box::new(format::man::ManFormatter::new(url)),
-        Format::Md => Box::new(format::md::MdFormatter::new(url, man_map)),
+        Format::Md => Box::new(format::md::MdFormatter::new(man_map)),
         Format::Text => Box::new(format::text::TextFormatter::new(url)),
     };
     let expanded = hbs::expand(file, &*formatter)?;

crates/mdman/tests/compare/expected/links.1

@@ -29,3 +29,17 @@ Shortcut unknown: [shortcut unknown]
 \fBother\-cmd\fR(1)
 .sp
 \fBlocal\-cmd\fR(1)
+.sp
+\fISome link\fR <https://example.org/foo.html>
+.sp
+\fB\-\-include\fR
+.RS 4
+Testing an \fIincluded link\fR <https://example.org/included_link.html>\&.
+.RE
+.SH "OPTIONS"
+.sp
+\fB\-\-foo\-bar\fR
+.RS 4
+Example \fIlink\fR <https://example.org/bar.html>\&.
+See \fBother\-cmd\fR(1), \fBlocal\-cmd\fR(1)
+.RE

crates/mdman/tests/compare/expected/links.md

@@ -28,7 +28,28 @@ Shortcut unknown: [shortcut unknown]
 
 [other-cmd(1)](https://example.org/commands/other-cmd.html)
 
-[local-cmd(1)](local-cmd.md)
+[local-cmd(1)](local-cmd.html)
+
+[Some link](foo.html)
+
+<dl>
+<dt class="option-term" id="option-links---include"><a class="option-anchor" href="#option-links---include"></a><code>--include</code></dt>
+<dd class="option-desc">Testing an <a href="included_link.html">included link</a>.</dd>
+
+</dl>
+
+
+## OPTIONS
+
+<dl>
+
+<dt class="option-term" id="option-links---foo-bar"><a class="option-anchor" href="#option-links---foo-bar"></a><code>--foo-bar</code></dt>
+<dd class="option-desc">Example <a href="bar.html">link</a>.
+See <a href="https://example.org/commands/other-cmd.html">other-cmd(1)</a>, <a href="local-cmd.html">local-cmd(1)</a></dd>
+
+
+</dl>
+
 
 [bar]: https://example.com/bar
 [collapsed]: https://example.com/collapsed

crates/mdman/tests/compare/expected/links.txt

@@ -28,3 +28,13 @@ DESCRIPTION
 
        local-cmd(1)
 
+       Some link <https://example.org/foo.html>
+
+       --include
+           Testing an included link <https://example.org/included_link.html>.
+
+OPTIONS
+       --foo-bar
+           Example link <https://example.org/bar.html>. See other-cmd(1),
+           local-cmd(1)
+

crates/mdman/tests/compare/expected/options.md

@@ -74,4 +74,4 @@ A description of the command.
        my-command --xyz
 
 ## SEE ALSO
-[other-command(1)](other-command.md) [abc(7)](abc.md)
+[other-command(1)](other-command.html) [abc(7)](abc.html)

crates/mdman/tests/compare/includes/links-include.md

@@ -0,0 +1,7 @@
+[Some link](foo.html)
+
+{{#options}}
+{{#option "`--include`"}}
+Testing an [included link](included_link.html).
+{{/option}}
+{{/options}}

crates/mdman/tests/compare/links.md

@@ -30,6 +30,20 @@ Shortcut unknown: [shortcut unknown]
 
 {{man "local-cmd" 1}}
 
+{{> links-include}}
+
+## OPTIONS
+
+{{#options}}
+
+{{#option "`--foo-bar`"}}
+Example [link](bar.html).
+See {{man "other-cmd" 1}}, {{man "local-cmd" 1}}
+{{/option}}
+
+{{/options}}
+
+
 [bar]: https://example.com/bar
 [collapsed]: https://example.com/collapsed
 [shortcut]: https://example.com/shortcut

src/doc/man/cargo-publish.md

@@ -57,7 +57,7 @@ config files](../reference/config.html). If not specified, and there is a
 [`package.publish`](../reference/manifest.html#the-publish-field) field in
 `Cargo.toml` with a single registry, then it will publish to that registry.
 Otherwise it will use the default registry, which is defined by the
-[`registry.default`](../reference/config.html#registry-default) config key
+[`registry.default`](../reference/config.html#registrydefault) config key
 which defaults to `crates-io`.
 {{/option}}
 

src/doc/man/generated_txt/cargo-publish.txt

@@ -64,7 +64,7 @@ OPTIONS
            field in Cargo.toml with a single registry, then it will publish to
            that registry. Otherwise it will use the default registry, which is
            defined by the registry.default
-           <https://doc.rust-lang.org/cargo/reference/config.html#registry-default>
+           <https://doc.rust-lang.org/cargo/reference/config.html#registrydefault>
            config key which defaults to crates-io.
 
    Compilation Options

src/doc/src/commands/cargo-bench.md

@@ -80,7 +80,7 @@ virtual workspace will include all workspace members (equivalent to passing
 
 <dt class="option-term" id="option-cargo-bench--p"><a class="option-anchor" href="#option-cargo-bench--p"></a><code>-p</code> <em>spec</em>...</dt>
 <dt class="option-term" id="option-cargo-bench---package"><a class="option-anchor" href="#option-cargo-bench---package"></a><code>--package</code> <em>spec</em>...</dt>
-<dd class="option-desc">Benchmark only the specified packages. See <a href="https://doc.rust-lang.org/cargo/commands/cargo-pkgid.md">cargo-pkgid(1)</a> for the
+<dd class="option-desc">Benchmark only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the
 SPEC format. This flag may be specified multiple times.</dd>
 
 
@@ -224,10 +224,10 @@ architecture. The general format of the triple is
 <code>&lt;arch&gt;&lt;sub&gt;-&lt;vendor&gt;-&lt;sys&gt;-&lt;abi&gt;</code>. Run <code>rustc --print target-list</code> for a
 list of supported targets.</p>
 <p>This may also be specified with the <code>build.target</code>
-<a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</p>
+<a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="https://doc.rust-lang.org/cargo/guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 
@@ -239,7 +239,7 @@ target artifacts are placed in a separate directory. See the
 <dt class="option-term" id="option-cargo-bench---target-dir"><a class="option-anchor" href="#option-cargo-bench---target-dir"></a><code>--target-dir</code> <em>directory</em></dt>
 <dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be
 specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the
-<code>build.target-dir</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>. Defaults
+<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. Defaults
 to <code>target</code> in the root of the workspace.</dd>
 
 
@@ -260,7 +260,7 @@ passing `--nocapture` to the benchmark binaries:
 <dd class="option-desc">Use verbose output. May be specified twice for &quot;very verbose&quot; output which
 includes extra output such as dependency warnings and build script output.
 May also be specified with the <code>term.verbose</code>
-<a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
+<a href="../reference/config.html">config value</a>.</dd>
 
 
 <dt class="option-term" id="option-cargo-bench--q"><a class="option-anchor" href="#option-cargo-bench--q"></a><code>-q</code></dt>
@@ -277,7 +277,7 @@ terminal.</li>
 <li><code>never</code>: Never display colors.</li>
 </ul>
 <p>May also be specified with the <code>term.color</code>
-<a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
+<a href="../reference/config.html">config value</a>.</dd>
 
 
 
@@ -288,7 +288,7 @@ and consists of comma-separated values. Valid values:</p>
 <li><code>human</code> (default): Display in a human-readable text format.</li>
 <li><code>short</code>: Emit shorter, human-readable text messages.</li>
 <li><code>json</code>: Emit JSON messages to stdout. See
-<a href="https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages">the reference</a>
+<a href="../reference/external-tools.html#json-messages">the reference</a>
 for more details.</li>
 <li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains
 the &quot;short&quot; rendering from rustc.</li>
@@ -333,9 +333,9 @@ proceed without the network if possible.</p>
 <p>Beware that this may result in different dependency resolution than online
 mode. Cargo will restrict itself to crates that are downloaded locally, even
 if there might be a newer version as indicated in the local copy of the index.
-See the <a href="https://doc.rust-lang.org/cargo/commands/cargo-fetch.md">cargo-fetch(1)</a> command to download dependencies before going
+See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going
 offline.</p>
-<p>May also be specified with the <code>net.offline</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
+<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd>
 
 
 </dl>
@@ -374,7 +374,7 @@ Rust test harness runs benchmarks serially in a single thread.
 <dt class="option-term" id="option-cargo-bench--j"><a class="option-anchor" href="#option-cargo-bench--j"></a><code>-j</code> <em>N</em></dt>
 <dt class="option-term" id="option-cargo-bench---jobs"><a class="option-anchor" href="#option-cargo-bench---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
-<code>build.jobs</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>. Defaults to
+<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of CPUs.</dd>
 
 
@@ -393,7 +393,7 @@ 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
-[cargo-build(1)](cargo-build.md) which will use the `test` profile which is by default
+[cargo-build(1)](cargo-build.html) which will use the `test` profile which is by default
 unoptimized and includes debug information. You can then run the debug-enabled
 benchmark manually.
 
@@ -420,4 +420,4 @@ details on environment variables that Cargo reads.
        cargo bench --bench bench_name -- modname::some_benchmark
 
 ## SEE ALSO
-[cargo(1)](cargo.md), [cargo-test(1)](cargo-test.md)
+[cargo(1)](cargo.html), [cargo-test(1)](cargo-test.html)

src/doc/src/commands/cargo-build.md

@@ -32,7 +32,7 @@ virtual workspace will include all workspace members (equivalent to passing
 
 <dt class="option-term" id="option-cargo-build--p"><a class="option-anchor" href="#option-cargo-build--p"></a><code>-p</code> <em>spec</em>...</dt>
 <dt class="option-term" id="option-cargo-build---package"><a class="option-anchor" href="#option-cargo-build---package"></a><code>--package</code> <em>spec</em>...</dt>
-<dd class="option-desc">Build only the specified packages. See <a href="https://doc.rust-lang.org/cargo/commands/cargo-pkgid.md">cargo-pkgid(1)</a> for the
+<dd class="option-desc">Build only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the
 SPEC format. This flag may be specified multiple times.</dd>
 
 
@@ -163,10 +163,10 @@ architecture. The general format of the triple is
 <code>&lt;arch&gt;&lt;sub&gt;-&lt;vendor&gt;-&lt;sys&gt;-&lt;abi&gt;</code>. Run <code>rustc --print target-list</code> for a
 list of supported targets.</p>
 <p>This may also be specified with the <code>build.target</code>
-<a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</p>
+<a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="https://doc.rust-lang.org/cargo/guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 
@@ -185,7 +185,7 @@ selection.</dd>
 <dt class="option-term" id="option-cargo-build---target-dir"><a class="option-anchor" href="#option-cargo-build---target-dir"></a><code>--target-dir</code> <em>directory</em></dt>
 <dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be
 specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the
-<code>build.target-dir</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>. Defaults
+<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. Defaults
 to <code>target</code> in the root of the workspace.</dd>
 
 
@@ -208,7 +208,7 @@ See https://github.com/rust-lang/cargo/issues/6790 for more information.</dd>
 <dd class="option-desc">Use verbose output. May be specified twice for &quot;very verbose&quot; output which
 includes extra output such as dependency warnings and build script output.
 May also be specified with the <code>term.verbose</code>
-<a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
+<a href="../reference/config.html">config value</a>.</dd>
 
 
 <dt class="option-term" id="option-cargo-build--q"><a class="option-anchor" href="#option-cargo-build--q"></a><code>-q</code></dt>
@@ -225,7 +225,7 @@ terminal.</li>
 <li><code>never</code>: Never display colors.</li>
 </ul>
 <p>May also be specified with the <code>term.color</code>
-<a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
+<a href="../reference/config.html">config value</a>.</dd>
 
 
 
@@ -236,7 +236,7 @@ and consists of comma-separated values. Valid values:</p>
 <li><code>human</code> (default): Display in a human-readable text format.</li>
 <li><code>short</code>: Emit shorter, human-readable text messages.</li>
 <li><code>json</code>: Emit JSON messages to stdout. See
-<a href="https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages">the reference</a>
+<a href="../reference/external-tools.html#json-messages">the reference</a>
 for more details.</li>
 <li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains
 the &quot;short&quot; rendering from rustc.</li>
@@ -289,9 +289,9 @@ proceed without the network if possible.</p>
 <p>Beware that this may result in different dependency resolution than online
 mode. Cargo will restrict itself to crates that are downloaded locally, even
 if there might be a newer version as indicated in the local copy of the index.
-See the <a href="https://doc.rust-lang.org/cargo/commands/cargo-fetch.md">cargo-fetch(1)</a> command to download dependencies before going
+See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going
 offline.</p>
-<p>May also be specified with the <code>net.offline</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
+<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd>
 
 
 </dl>
@@ -326,7 +326,7 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-build--j"><a class="option-anchor" href="#option-cargo-build--j"></a><code>-j</code> <em>N</em></dt>
 <dt class="option-term" id="option-cargo-build---jobs"><a class="option-anchor" href="#option-cargo-build---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
-<code>build.jobs</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>. Defaults to
+<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of CPUs.</dd>
 
 
@@ -373,4 +373,4 @@ details on environment variables that Cargo reads.
        cargo build --release
 
 ## SEE ALSO
-[cargo(1)](cargo.md), [cargo-rustc(1)](cargo-rustc.md)
+[cargo(1)](cargo.html), [cargo-rustc(1)](cargo-rustc.html)