Change:
Split off from . modify labels: T-rustdoc C-enhancement <!-- TRIAGEBOTSTART --<!-- TRIAGEBOTASSIGNSTART --<!-- TRIAGEBOTASSIGNDATASTARTTRIAGEBOTASSIGNDATAEND --<!-- TRIAGEBOTASSIGNEND --<!-- TRIAGEBOTEND --
claim
Uh, it looks like rustbot is editing my message and adding weird comments:
Cc
It looks like smart punctuation doesn't work in headers: ! wasn't able to reproduce this in pulldown itself; I'm guessing rustdoc is doing something special with headers. Cc
Triagebot does that as a way of easily storing data per-issue (we could do it in the database now, we didn't have one back then). But it's expected and shouldn't really be a problem.
Is this a good thing? Wouldn't keeping things as it is is better?
I think if you want to argue against doing this, giving reasons would be helpful. I personally think given that we already use emoji and otherwise non-ASCII characters readily, it should be reasonable for us to generate smart quotes as well.
I do think emoji and other non-ASCII characters if specified would be good except for smart quote. It's like saying to use greek question mark which is the same as semi-colon when a semi-colon was seen in documentation to make it look a bit cooler. One thing is copying, when others are copying the text, it will copy the utf-8 version of smart quotes which when displayed in terminals which in turn will make it look ugly and hard for text processing. Auto changing text to emoji I am okay with that. But not automatically changing single quotes, double quotes and semi-colons. Personally I don't see much benefit to that, usually if users want it they would specifically type it out but otherwise it would be similar. In my humble opinion, looks wise the smart quotes are more ugly, but easier to distinguish opening and closing quotes, but still when copied and pasted it may not look so good.

Discussion:
Let's see an example coming from the [standard library] by taking a look at the [`std::env::args()`][env::args] function: <del> ``````text </del> <ins> ``````markdown </ins> Returns the arguments which this program was started with (normally passed via the command line).

Everything before the first empty line will be reused to describe the component in searches and module overviews.  For example, the function `std::env::args()` <del> above will be shown on the [`std::env`] module documentation.  It is good </del> <ins> above will be shown on the [`std::env`] module documentation. It is good </ins> practice to keep the summary to one line: concise writing is a goal of good documentation.

## Markdown <del> `rustdoc` uses the [CommonMark markdown specification]. You might be interested into taking a look at their website to see what's possible to do. - [commonmark quick reference] </del> <ins> `rustdoc` uses the [CommonMark Markdown specification]. You might be interested in taking a look at their website to see what's possible: - [CommonMark quick reference] </ins> - [current spec] In addition to the standard CommonMark syntax, `rustdoc` supports several

See the specification for the [task list extension] for more details. <ins> ### Smart punctuation Some ASCII punctuation sequences will be automatically turned into fancy Unicode characters: | ASCII sequence | Unicode | |----------------|---------| | `--`           | –       | | `---`          | —       | | `...`          | …       | | `"`            | “ or ”, depending on context | | `'`            | ‘ or ’, depending on context | So, no need to manually enter those Unicode characters! </ins> [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/ [commonmark markdown specification]: https://commonmark.org/ [commonmark quick reference]: https://commonmark.org/help/

| Options::ENABLE_FOOTNOTES | Options::ENABLE_STRIKETHROUGH | Options::ENABLE_TASKLISTS <ins> | Options::ENABLE_SMART_PUNCTUATION </ins> } /// A subset of [`opts()`] used for rendering summaries. pub(crate) fn summary_opts() -> Options { <del> Options::ENABLE_STRIKETHROUGH </del> <ins> Options::ENABLE_STRIKETHROUGH | Options::ENABLE_SMART_PUNCTUATION </ins> } /// When `to_string` is called, this struct will emit the HTML corresponding to

t("Hard-break  nsummary", "Hard-break summary"); t("hello [Rust] :)nn[Rust]: https://www.rust-lang.org", "hello Rust :)"); t("hello [Rust](https://www.rust-lang.org "Rust") :)", "hello Rust :)"); <del> t("code `let x = i32;` ...", "code <code>let x = i32;</code> ..."); t("type `Type<'static>` ...", "type <code>Type<'static></code> ..."); </del> <ins> t("code `let x = i32;` ...", "code <code>let x = i32;</code> …"); t("type `Type<'static>` ...", "type <code>Type<'static></code> …"); </ins> t("# top header", "top header"); t("## header", "header"); t("first paragraphnnsecond paragraph", "first paragraph");

t("Hard-break  nsummary", "Hard-break summary"); t("hello [Rust] :)nn[Rust]: https://www.rust-lang.org", "hello Rust :)"); t("hello [Rust](https://www.rust-lang.org "Rust") :)", "hello Rust :)"); <del> t("code `let x = i32;` ...", "code `let x = i32;` ..."); t("type `Type<'static>` ...", "type `Type<'static>` ..."); </del> <ins> t("code `let x = i32;` ...", "code `let x = i32;` …"); t("type `Type<'static>` ...", "type `Type<'static>` …"); </ins> t("# top header", "top header"); t("## header", "header"); t("first paragraphnnsecond paragraph", "first paragraph");

} t("`Struct<'a, T>`", "<p><code>Struct&lt;'a, T&gt;</code></p>n"); <del> t("Struct<'a, T>", "<p>Struct&lt;'a, T&gt;</p>n"); </del> <ins> t("Struct<'a, T>", "<p>Struct&lt;’a, T&gt;</p>n"); </ins> t("Struct<br>", "<p>Struct&lt;br&gt;</p>n"); }

// @has add_docs/struct.MyStruct.html <del> // @has add_docs/struct.MyStruct.html "Doc comment from 'pub use', Doc comment from definition" </del> <ins> // @has add_docs/struct.MyStruct.html "Doc comment from ‘pub use’, Doc comment from definition" </ins> /// Doc comment from 'pub use', pub use inner::MyStruct;

<ins> // ignore-tidy-linelength #![crate_name = "foo"] //! This is the "start" of the 'document'! How'd you know that "it's" the start? //! //! # Header with "smart punct'" //! //! [link with "smart punct'" -- yessiree!][] //! //! [link with "smart punct'" -- yessiree!]: https://www.rust-lang.org //! //! # Code should not be smart-punct'd //! //! `this inline code -- it shouldn't have "smart punct"` //! //! ``` //! let x = "don't smart-punct me -- please!"; //! ``` //! //! ```text //! I say "don't smart-punct me -- please!" //! ``` // @has "foo/index.html" "//p" "This is the “start” of the ‘document’! How’d you know that “it’s” the start?" // @has "foo/index.html" "//h1" "Header with “smart punct’”" // @has "foo/index.html" '//a[@href="https://www.rust-lang.org"]' "link with “smart punct’” – yessiree!" // @has "foo/index.html" '//code' "this inline code -- it shouldn't have "smart punct"" // @has "foo/index.html" '//pre' "let x = "don't smart-punct me -- please!";" // @has "foo/index.html" '//pre' "I say "don't smart-punct me -- please!"" </ins>