From 72aa808cfeb12bdb4320156273525613b09a826a Mon Sep 17 00:00:00 2001 From: Nils-Hero Lindemann Date: Mon, 19 Jan 2026 01:43:27 +0100 Subject: [PATCH 1/3] Denote examples better by using `:` in the text and `> ` in the markdown. I replaced with a more distinct example in the first two `> ` blocks to denote better to the reader that these are examples. [The way it is currently written in the reference](https://doc.rust-lang.org/stable/reference/#conventions) can create confusion. I looked a while at it, trying to make sense why you would write examples for terms in italics too (= I parsed this sentence as meta language), until I grasped that this sentence *is* an example (= the sentence is to be parsed as object language). This is partly due to the fact that `> ` blocks are not rendered in a special way at this position in the book. And further, the first example (the second paragraph of the first list item) was missing the `> `s. --- src/introduction.md | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index d5eb4888a3..7606734382 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -63,22 +63,25 @@ That said, there is no wrong way to read this book. Read it however you feel hel Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here. -* Statements that define a term contain that term in *italics*. - Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. +* Statements that define a term write that term in italics: - An *example term* is an example of a term being defined. + > A *crab* is an animal with ten legs and a shell. + + Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition: + + > Rust uses a pictogram of a [crab](#) as its logo. * The main text describes the latest stable edition. Differences to previous editions are separated in edition blocks: > [!EDITION-2018] > Before the 2018 edition, the behavior was this. As of the 2018 edition, the behavior is that. -* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks. +* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks: > [!NOTE] > This is an example note. -* Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example. +* Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example: > [!EXAMPLE] > This is a code example. @@ -86,27 +89,30 @@ These conventions are documented here. > println!("hello world"); > ``` -* Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. +* Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box: > [!WARNING] > This is an example warning. -* Code snippets inline in the text are inside `` tags. +* Code snippets inline in the text are inside `` tags: + + > To print to the console use the `println!` macro. - Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. + Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner: - ```rust - # // This is a hidden line. - fn main() { - println!("This is a code example"); - } - ``` + > ```rust + > # // This is a hidden line. + > fn main() { + > println!("This is a code example"); + > } + > ``` All examples are written for the latest edition unless otherwise stated. -* The grammar and lexical productions are described in the [Notation] chapter. +* The grammar and lexical productions are described in the [Notation] chapter: + + > r[example.rule.label] -r[example.rule.label] * Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. The rule name can be clicked to link to that rule. From 95cd12064d3ef7dc4a31a3f88b8c892a0e6bac5c Mon Sep 17 00:00:00 2001 From: Nils-Hero Lindemann Date: Mon, 19 Jan 2026 01:55:10 +0100 Subject: [PATCH 2/3] Reverse faulty change This one is not an example. --- src/introduction.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 7606734382..f7b300d338 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -111,8 +111,7 @@ These conventions are documented here. * The grammar and lexical productions are described in the [Notation] chapter: - > r[example.rule.label] - +r[example.rule.label] * Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. The rule name can be clicked to link to that rule. From 6c1569a9de96726aa2af0aeab305db852c1e2279 Mon Sep 17 00:00:00 2001 From: Nils-Hero Lindemann Date: Mon, 19 Jan 2026 01:56:41 +0100 Subject: [PATCH 3/3] Amend to previous commit. --- src/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/introduction.md b/src/introduction.md index f7b300d338..2d2389d58c 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -109,7 +109,7 @@ These conventions are documented here. All examples are written for the latest edition unless otherwise stated. -* The grammar and lexical productions are described in the [Notation] chapter: +* The grammar and lexical productions are described in the [Notation] chapter. r[example.rule.label] * Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`.