Ensure em dashes are recognizable in markup

[Enyium]

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.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @weihanglo (or someone else) soon.

Please see the contribution instructions for more information.

[weihanglo]

Thanks for raising up this issue. I don't entirely agree with the solution, however. It would be better if we can keep the original source as readable as rendered one. Let's see what others say.

[Enyium]

Just also saw it used here: https://github.com/dtolnay/indoc/blob/master/README.md?plain=1#L75.

[weihanglo]

As a non-English native speaker, choosing from different kinds of dashes is sometimes a headache to me. Yet, some developers prefer to read docs in their terminal emulators. I don't quite feel this patch more readable than the old one. The example you provided has the same problem:

Perhaps instead of this patch, we need a rule and an automation to help us fix this issue.

BTW, it seems like several crates from dtolnay pick HTML entities over literals. Curious to know the reason behind the back.

[Enyium]

I'm not sure what is expected from me now. Your comment sounds like more opinions from your collegues are needed.

I can understand that — isn't great when reading the docs as raw markup. But in the case of Cargo docs, when is that really the case?

I don't know about @dtolnay's reasoning. When it comes to doc comments on code items, I'm torn between nice rendering and readability of raw markup, but ultimately favor the latter. Ideally, -- would render an em dash.

[ehuss]

We can consider enabling smart punctuation (it's an option in book.toml), though it is a triple --- for emdash. I too would prefer to avoid using HTML entities, but I understand in most editors emdash isn't really obvious.

[Enyium]

I noticed generated docs contain the typographically correct apostrophe ’ where I wrote '. So, there's already something like that going on. Looks like a good basis to extend it with replacing -- with an en dash and --- with an em dash. I don't know what different systems are involved, though, considering this discussion was originally only about online Cargo docs. All docs should benefit from such a change. I already have a list in the following form in a doc comment of my yet unpublished code:

//! `function_1()` - Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
//! `function_2()` - At vero eos et accusam et justo duo dolores et ea rebum.
//! `function_3()` - Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

[weihanglo]

They are two different systems AFAIK. The tool “The Cargo Book” uses is called mdbook, whereas rustdoc is a tool in https://github.com/rust-lang/rust/tree/master/src/librustdoc.

Eric has mentioned smart punctuations feature in mdbook, which is off by default. We could enable it here and then update each page accordingly. Do you want to give this approach a shot?

[Enyium]

Eric has mentioned smart punctuations feature in mdbook, which is off by default. We could enable it here and then update each page accordingly. Do you want to give this approach a shot?

I could do that.

---

I just checked with cargo doc --open, and it already converts -- and ---, which is good news so far. So, I guess it also happens for docs.rs. But why does the rendered documentation VS Code with rust-analyzer shows when hovering over items still display -- and --- with gaps?

[weihanglo]

I just checked with cargo doc --open, and it already converts -- and ---, which is good news so far. So, I guess it also happens for docs.rs. But why does the rendered documentation VS Code with rust-analyzer shows when hovering over items still display -- and --- with gaps?

I guess rust-analyzer provides just raw contents to the LSP client, which is effectively VS Code. The display depends on how a client renders them. rust-analyzer indeed can provide unicode version of them, yet I don't feel like rendering should be a thing done by a language server.

[Enyium]

I don't feel like rendering should be a thing done by a language server.

And just the smart-punctuation prestage? Is it possible on it's own, while otherwise still serving markdown to the IDE? Since it's an addition to markdown, we may not ever see it rendered better.

[weihanglo]

… while otherwise still serving markdown to the IDE? …

Let's focus on the PR itself. If you want a further discussion, feel free to chat on the dedicated rust-analyzer zulip stream.

[Enyium]

Sorry for the noise. Seems like renaming a branch closes the PR.

[Enyium]

I carefully changed .md files in src/doc. Among the the source texts that I changed to --- were hyphens (Markdown list dashes unchanged), double-hyphens (command line switches and switch separators unchanged) and em dashes.

[weihanglo]

Thanks for your quick reply!

One thing I forgot to mention. We also need to enable output.html.curly-quotes in src/doc/contrib/book.toml.

[Enyium]

May I add a translation of src/doc/build-man.sh to a Windows batch script?

[weihanglo]

May I add a translation of src/doc/build-man.sh to a Windows batch script?

I don't have enough knowledge for reviewing Windows batch script. I might redirect it to another reviewer for such a change.

[Enyium]

• Rebased my commits to include respective test changes in commit that makes it break. Include cargo fmt changes in suitable commit.
• Rebased branch onto latest commit from master and resolved conflicts.

[weihanglo]

Yeah we eventually got here! Thank you for your contribution and patience so far!

This PR changes the help manual rendering, including

• Enabled smart punctuation in mdbook for The Cargo book and Cargo Contributor Guide.
• Upgraded pulldown-cmark to v0.9.2. This upgrade breaks some tests, but they are indeed the correct behavior (see Ensure em dashes are recognizable in markup #11646 (comment)).
• Implemented the same smart punctuation functionality in mdman for roff and text output. This changes the rendered result of OptionsHelper in mdman. It renders

  {{#option "_named-arg..._"}}
  A named argument.
  {{/option}}

  to an <dt> containing an id with unicode ellipsis option-options-named-arg…, which previously was just three dots option-options-named-arg.... I scanned the codebase and it seems that in Cargo we don't have such an option, so it is unlikely to break old links. (See Ensure em dashes are recognizable in markup #11646 (comment))

After this PR, when writing contents for The Cargo book or Cargo Contributor Guide, use --- for em dash. That's the whole point. If anyone feels wrong to merge this, let us know here or on Zulip. We can always consider a revert.

[weihanglo]

@bors r+

[bors]

📌 Commit b1754b2 has been approved by weihanglo

It is now in the queue for this repository.

[bors]

⌛ Testing commit b1754b2 with merge 4262636...

[bors]

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing 4262636 to master...