Auto merge of #11646 - Enyium:patch-1, r=weihanglo

Ensure em dashes are recognizable in markup

An em dash (—) isn't well-recognizable in a monospace font. There were already a couple of locations where a hyphen was used instead. These were also corrected to `—`. `—` should reduce the probability of a hyphen being used for new entries.

Author: bors

.github/workflows/contrib.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Install mdbook
       run: |
         mkdir mdbook
-        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.9/mdbook-v0.4.9-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.26/mdbook-v0.4.26-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
         echo `pwd`/mdbook >> $GITHUB_PATH
     - name: Deploy docs
       run: |

crates/mdman/Cargo.lock

@@ -8,7 +8,7 @@ description = "Creates a man page page from markdown."
 [dependencies]
 anyhow = "1.0.31"
 handlebars = { version = "3.2.1", features = ["dir_source"] }
-pulldown-cmark = { version = "0.7.2", default-features = false }
+pulldown-cmark = { version = "0.9.2", default-features = false }
 same-file = "1.0.6"
 serde_json = "1.0.56"
 url = "2.2.2"

crates/mdman/Cargo.toml

@@ -3,7 +3,7 @@
 use crate::util::{header_text, parse_name_and_section};
 use crate::EventIter;
 use anyhow::{bail, Error};
-use pulldown_cmark::{Alignment, Event, LinkType, Tag};
+use pulldown_cmark::{Alignment, Event, HeadingLevel, LinkType, Tag};
 use std::fmt::Write;
 use url::Url;
 
@@ -122,10 +122,10 @@ impl<'e> ManRenderer<'e> {
                                 self.output.push_str(".sp\n");
                             }
                         }
-                        Tag::Heading(n) => {
-                            if n == 1 {
+                        Tag::Heading(level, ..) => {
+                            if level == HeadingLevel::H1 {
                                 self.push_top_header()?;
-                            } else if n == 2 {
+                            } else if level == HeadingLevel::H2 {
                                 // Section header
                                 let text = header_text(&mut self.parser)?;
                                 self.flush();
@@ -255,7 +255,7 @@ impl<'e> ManRenderer<'e> {
                 Event::End(tag) => {
                     match &tag {
                         Tag::Paragraph => self.flush(),
-                        Tag::Heading(_n) => {}
+                        Tag::Heading(..) => {}
                         Tag::BlockQuote => {
                             self.flush();
                             // restore left margin, restore line length
@@ -400,21 +400,27 @@ impl<'e> ManRenderer<'e> {
 }
 
 fn escape(s: &str) -> Result<String, Error> {
+    // Note: Possible source on output escape sequences: https://man7.org/linux/man-pages/man7/groff_char.7.html.
+    //       Otherwise, use generic escaping in the form `\[u1EE7]` or `\[u1F994]`.
+
     let mut replaced = s
         .replace('\\', "\\(rs")
         .replace('-', "\\-")
         .replace('\u{00A0}', "\\ ") // non-breaking space (non-stretchable)
         .replace('–', "\\[en]") // \u{2013} en-dash
         .replace('—', "\\[em]") // \u{2014} em-dash
+        .replace('‘', "\\[oq]") // \u{2018} left single quote
+        .replace('’', "\\[cq]") // \u{2019} right single quote or apostrophe
+        .replace('“', "\\[lq]") // \u{201C} left double quote
+        .replace('”', "\\[rq]") // \u{201D} right double quote
+        .replace('…', "\\[u2026]") // \u{2026} ellipsis
         .replace('│', "|") // \u{2502} box drawing light vertical (could use \[br])
         .replace('├', "|") // \u{251C} box drawings light vertical and right
         .replace('└', "`") // \u{2514} box drawings light up and right
         .replace('─', "\\-") // \u{2500} box drawing light horizontal
     ;
     if replaced.starts_with('.') {
         replaced = format!("\\&.{}", &replaced[1..]);
-    } else if replaced.starts_with('\'') {
-        replaced = format!("\\(aq{}", &replaced[1..]);
     }
 
     if let Some(ch) = replaced.chars().find(|ch| {

crates/mdman/src/format/man.rs

@@ -3,7 +3,7 @@
 use crate::util::{header_text, unwrap};
 use crate::EventIter;
 use anyhow::{bail, Error};
-use pulldown_cmark::{Alignment, Event, LinkType, Tag};
+use pulldown_cmark::{Alignment, Event, HeadingLevel, LinkType, Tag};
 use std::fmt::Write;
 use std::mem;
 use url::Url;
@@ -116,24 +116,24 @@ impl<'e> TextRenderer<'e> {
                                 self.flush();
                             }
                         }
-                        Tag::Heading(n) => {
+                        Tag::Heading(level, ..) => {
                             self.flush();
-                            if n == 1 {
+                            if level == HeadingLevel::H1 {
                                 let text = header_text(&mut self.parser)?;
                                 self.push_to_line(&text.to_uppercase());
                                 self.hard_break();
                                 self.hard_break();
-                            } else if n == 2 {
+                            } else if level == HeadingLevel::H2 {
                                 let text = header_text(&mut self.parser)?;
                                 self.push_to_line(&text.to_uppercase());
                                 self.flush();
                                 self.indent = 7;
                             } else {
                                 let text = header_text(&mut self.parser)?;
-                                self.push_indent((n as usize - 2) * 3);
+                                self.push_indent((level as usize - 2) * 3);
                                 self.push_to_line(&text);
                                 self.flush();
-                                self.indent = (n as usize - 1) * 3 + 1;
+                                self.indent = (level as usize - 1) * 3 + 1;
                             }
                         }
                         Tag::BlockQuote => {
@@ -223,7 +223,7 @@ impl<'e> TextRenderer<'e> {
                         self.flush();
                         self.hard_break();
                     }
-                    Tag::Heading(_n) => {}
+                    Tag::Heading(..) => {}
                     Tag::BlockQuote => {
                         self.indent -= 3;
                     }

crates/mdman/src/format/text.rs

@@ -69,6 +69,7 @@ pub(crate) fn md_parser(input: &str, url: Option<Url>) -> EventIter {
     options.insert(Options::ENABLE_TABLES);
     options.insert(Options::ENABLE_FOOTNOTES);
     options.insert(Options::ENABLE_STRIKETHROUGH);
+    options.insert(Options::ENABLE_SMART_PUNCTUATION);
     let parser = Parser::new_ext(input, options);
     let parser = parser.into_offset_iter();
     // Translate all links to include the base url.

crates/mdman/src/lib.rs

@@ -31,7 +31,7 @@ pub fn header_text<'e>(parser: &mut EventIter<'e>) -> Result<CowStr<'e>, Error>
         e => bail!("expected plain text in man header, got {:?}", e),
     };
     match parser.next() {
-        Some((Event::End(Tag::Heading(_)), _range)) => {
+        Some((Event::End(Tag::Heading(..)), _range)) => {
             return Ok(text);
         }
         e => bail!("expected plain text in man header, got {:?}", e),

crates/mdman/src/util.rs

@@ -66,14 +66,8 @@ With a second paragraph inside it
 .sp
 .RS 4
 \h'-04'\(bu\h'+02'Milk
-.sp
-.RS 4
-\h'-04' 5.\h'+01'Don't start at one.
-.RE
-.sp
-.RS 4
-\h'-04' 6.\h'+01'tamarind
-.RE
+5. Don\[cq]t start at one.
+6. tamarind
 .RE
 .RE
 .sp

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

@@ -43,11 +43,7 @@ LISTS
 
           o  Eggs
 
-          o  Milk
-
-             5. Don't start at one.
-
-             6. tamarind
+          o  Milk 5. Don’t start at one. 6. tamarind
 
        2. Second element
 

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

@@ -12,7 +12,7 @@ my\-command \- A brief description
 .br
 \fBmy\-command\fR (\fB\-m\fR | \fB\-M\fR) [\fIoldbranch\fR] \fInewbranch\fR
 .br
-\fBmy\-command\fR (\fB\-d\fR | \fB\-D\fR) [\fB\-r\fR] \fIbranchname\fR\&...
+\fBmy\-command\fR (\fB\-d\fR | \fB\-D\fR) [\fB\-r\fR] \fIbranchname\fR\[u2026]
 .SH "DESCRIPTION"
 A description of the command.
 .sp
@@ -49,7 +49,7 @@ Demo \fIemphasis\fR, \fBstrong\fR, ~~strike~~
 This has multiple flags.
 .RE
 .sp
-\fInamed\-arg...\fR
+\fInamed\-arg\[u2026]\fR
 .RS 4
 A named argument.
 .RE