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}}