Fix mdman to not incorrectly strip <p> tags (#16158)

This fixes an issue with how mdman was generating HTML for command-line
options. It was incorrectly stripping the `<p>` tag in the description
of the flag when the description had multiple blocks. The code was
assuming the description was just a single paragraph, but that isn't
correct when there are multiple paragraphs or other block-level elements
like lists. This resulted in broken HTML tags.

The solution here is to stop stripping the `<p>` tags from the
description, and instead to just use CSS to fix the spacing that it
creates. (The specific CSS here will be part of mdbook 0.5.)

This will be required for mdbook 0.5 because it is stricter about having
properly balanced HTML tags.

Author: weihanglo

crates/mdman/doc/out/mdman.md

@@ -54,35 +54,40 @@ man page:
 <dl>
 
 <dt class="option-term" id="option-mdman--t"><a class="option-anchor" href="#option-mdman--t"></a><code>-t</code> <em>type</em></dt>
-<dd class="option-desc">Specifies the output type. The following output types are supported:</p>
+<dd class="option-desc"><p>Specifies the output type. The following output types are supported:</p>
 <ul>
 <li><code>man</code> — A troff-style man page. Outputs with a numbered extension (like
 <code>.1</code>) matching the man page section.</li>
 <li><code>md</code> — A markdown file, after all handlebars processing has been finished.
 Outputs with the <code>.md</code> extension.</li>
 <li><code>txt</code> — A text file, rendered for situations where a man page viewer isn’t
 available. Outputs with the <code>.txt</code> extension.</li>
-</ul></dd>
+</ul>
+</dd>
 
 
 <dt class="option-term" id="option-mdman--o"><a class="option-anchor" href="#option-mdman--o"></a><code>-o</code> <em>outdir</em></dt>
-<dd class="option-desc">Specifies the directory where to save the output.</dd>
+<dd class="option-desc"><p>Specifies the directory where to save the output.</p>
+</dd>
 
 
 <dt class="option-term" id="option-mdman---url"><a class="option-anchor" href="#option-mdman---url"></a><code>--url</code> <em>base_url</em></dt>
-<dd class="option-desc">Specifies a base URL to use for relative URLs within the document. Any
-relative URL will be joined with this URL.</dd>
+<dd class="option-desc"><p>Specifies a base URL to use for relative URLs within the document. Any
+relative URL will be joined with this URL.</p>
+</dd>
 
 
 <dt class="option-term" id="option-mdman---man"><a class="option-anchor" href="#option-mdman---man"></a><code>--man</code> <em>name</em><code>:</code><em>section</em><code>=</code><em>url</em></dt>
-<dd class="option-desc">Specifies a URL to use for the given man page. When the <code>{{man name section}}</code> expression is used, the given URL will be inserted as a link. This
+<dd class="option-desc"><p>Specifies a URL to use for the given man page. When the <code>{{man name section}}</code> expression is used, the given URL will be inserted as a link. This
 may be specified multiple times. If a man page reference does not have a
 matching <code>--man</code> entry, then a relative link to a file named <em>name</em><code>.md</code> will
-be used.</dd>
+be used.</p>
+</dd>
 
 
 <dt class="option-term" id="option-mdman-sources…"><a class="option-anchor" href="#option-mdman-sources…"></a><em>sources…</em></dt>
-<dd class="option-desc">The source input filename, may be specified multiple times.</dd>
+<dd class="option-desc"><p>The source input filename, may be specified multiple times.</p>
+</dd>
 
 
 </dl>

crates/mdman/src/format/md.rs

@@ -67,8 +67,7 @@ impl super::Formatter for MdFormatter {
         let rendered_block = self.render_html(block)?;
         write!(
             result,
-            "<dd class=\"option-desc\">{}</dd>\n\n",
-            unwrap_p(&rendered_block)
+            "<dd class=\"option-desc\">{rendered_block}</dd>\n\n",
         )?;
         Ok(result)
     }

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

@@ -34,7 +34,8 @@ Shortcut unknown: [shortcut unknown]
 
 <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>
+<dd class="option-desc"><p>Testing an <a href="included_link.html">included link</a>.</p>
+</dd>
 
 </dl>
 
@@ -44,8 +45,9 @@ Shortcut unknown: [shortcut unknown]
 <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>
+<dd class="option-desc"><p>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></p>
+</dd>
 
 
 </dl>

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

@@ -53,6 +53,25 @@ This has multiple flags.
 .RS 4
 A named argument.
 .RE
+.sp
+\fB\-\-complex\fR
+.RS 4
+This option has a list.
+.sp
+.RS 4
+\h'-04'\(bu\h'+03'alpha
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+03'beta
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+03'gamma
+.RE
+.sp
+Then text continues here.
+.RE
 .SS "Common Options"
 .sp
 \fB@\fR\fIfilename\fR

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

@@ -29,16 +29,30 @@ A description of the command.
 <dl>
 
 <dt class="option-term" id="option-options---foo-bar"><a class="option-anchor" href="#option-options---foo-bar"></a><code>--foo-bar</code></dt>
-<dd class="option-desc">Demo <em>emphasis</em>, <strong>strong</strong>, <del>strike</del></dd>
+<dd class="option-desc"><p>Demo <em>emphasis</em>, <strong>strong</strong>, <del>strike</del></p>
+</dd>
 
 
 <dt class="option-term" id="option-options--p"><a class="option-anchor" href="#option-options--p"></a><code>-p</code> <em>spec</em></dt>
 <dt class="option-term" id="option-options---package"><a class="option-anchor" href="#option-options---package"></a><code>--package</code> <em>spec</em></dt>
-<dd class="option-desc">This has multiple flags.</dd>
+<dd class="option-desc"><p>This has multiple flags.</p>
+</dd>
 
 
 <dt class="option-term" id="option-options-named-arg…"><a class="option-anchor" href="#option-options-named-arg…"></a><em>named-arg…</em></dt>
-<dd class="option-desc">A named argument.</dd>
+<dd class="option-desc"><p>A named argument.</p>
+</dd>
+
+
+<dt class="option-term" id="option-options---complex"><a class="option-anchor" href="#option-options---complex"></a><code>--complex</code></dt>
+<dd class="option-desc"><p>This option has a list.</p>
+<ul>
+<li>alpha</li>
+<li>beta</li>
+<li>gamma</li>
+</ul>
+<p>Then text continues here.</p>
+</dd>
 
 
 </dl>
@@ -47,19 +61,23 @@ A description of the command.
 
 <dl>
 <dt class="option-term" id="option-options-@filename"><a class="option-anchor" href="#option-options-@filename"></a><code>@</code><em>filename</em></dt>
-<dd class="option-desc">Load from filename.</dd>
+<dd class="option-desc"><p>Load from filename.</p>
+</dd>
 
 
 <dt class="option-term" id="option-options---foo"><a class="option-anchor" href="#option-options---foo"></a><code>--foo</code> [<em>bar</em>]</dt>
-<dd class="option-desc">Flag with optional value.</dd>
+<dd class="option-desc"><p>Flag with optional value.</p>
+</dd>
 
 
 <dt class="option-term" id="option-options---foo[=bar]"><a class="option-anchor" href="#option-options---foo[=bar]"></a><code>--foo</code>[<code>=</code><em>bar</em>]</dt>
-<dd class="option-desc">Alternate syntax for optional value (with required = for disambiguation).</dd>
+<dd class="option-desc"><p>Alternate syntax for optional value (with required = for disambiguation).</p>
+</dd>
 
 
 <dt class="option-term" id="option-options---split-block"><a class="option-anchor" href="#option-options---split-block"></a><code>--split-block</code></dt>
-<dd class="option-desc">An option where the description has a <code>block statement that is split across multiple lines</code></dd>
+<dd class="option-desc"><p>An option where the description has a <code>block statement that is split across multiple lines</code></p>
+</dd>
 
 
 </dl>

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

@@ -32,6 +32,17 @@ OPTIONS
        named-arg…
            A named argument.
 
+       --complex
+           This option has a list.
+
+           o  alpha
+
+           o  beta
+
+           o  gamma
+
+           Then text continues here.
+
    Common Options
        @filename
            Load from filename.

crates/mdman/tests/compare/options.md

@@ -40,6 +40,16 @@ This has multiple flags.
 A named argument.
 {{/option}}
 
+{{#option "`--complex`"}}
+This option has a list.
+
+- alpha
+- beta
+- gamma
+
+Then text continues here.
+{{/option}}
+
 {{/options}}
 
 ### Common Options

src/doc/book.toml

@@ -3,6 +3,7 @@ title = "The Cargo Book"
 authors = ["Alex Crichton", "Steve Klabnik", "Carol Nichols", "with contributions from the Rust community"]
 
 [output.html]
+additional-css = ["theme/cargo.css"]
 smart-punctuation = true # Enable smart-punctuation feature for more than quotes.
 git-repository-url = "https://github.com/rust-lang/cargo/tree/master/src/doc/src"
 edit-url-template = "https://github.com/rust-lang/cargo/edit/master/src/doc/{path}"