X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=src%2Fdoc%2Frustdoc%2Fsrc%2Fhow-to-write-documentation.md;h=688be7aedea38a17ebfd5b456c9081f1adc2caa0;hb=f434217aab9abf583ebc928b97ab4116921137aa;hp=9938cddc94106d337a58f0d379579b4f05f074d9;hpb=253631d73fdb310a437edff1134caee904e28b94;p=rust.git

diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md
index 9938cddc941..f89495cca3a 100644
--- a/src/doc/rustdoc/src/how-to-write-documentation.md
+++ b/src/doc/rustdoc/src/how-to-write-documentation.md
@@ -101,7 +101,7 @@ what an item is, how it is used, and for what purpose it exists.
 Let's see an example coming from the [standard library] by taking a look at the
 [`std::env::args()`][env::args] function:
 
-``````text
+``````markdown
 Returns the arguments which this program was started with (normally passed
 via the command line).
 
@@ -135,7 +135,7 @@ for argument in env::args() {
 
 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()`
-above will be shown on the [`std::env`] module documentation.  It is good
+above will be shown on the [`std::env`] module documentation. It is good
 practice to keep the summary to one line: concise writing is a goal of good
 documentation.
 
@@ -153,9 +153,10 @@ and finally provides a code example.
 
 ## Markdown
 
-`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]
+`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]
  - [current spec]
 
 In addition to the standard CommonMark syntax, `rustdoc` supports several
@@ -228,18 +229,31 @@ Example:
 
 ```md
 - [x] Complete task
-- [ ] IncComplete task
+- [ ] Incomplete task
 ```
 
-This will render as
+This will render as:
 
-<ul>
-    <li><input type="checkbox"></li>
-    <li><input type="checkbox" checked></li>
-</ul>
+> - [x] Complete task
+> - [ ] Incomplete task
 
 See the specification for the [task list extension] for more details.
 
+### 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!
+
 [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
 [commonmark markdown specification]: https://commonmark.org/
 [commonmark quick reference]: https://commonmark.org/help/