@@ -129,33 +129,14 @@ When introducing a new concept, start with a simple, relatable, and concrete
129
129
example. A good opening example grounds the concept for the learner and provides
130
130
motivation for the more detailed explanation that will follow.
131
131
132
- ### Rust Code
133
-
134
- When showing Rust code inline, please use the same spacing as ` rustfmt ` : ` 3 * x `
135
- instead of ` 3*x ` . However, feel free to remove newlines when it can make the
136
- code more compact and easier to understand, e.g., you can define a struct on one
137
- line if it is not the focus of your example:
138
-
139
- <!-- dprint-ignore-start -->
140
-
141
- ``` rust
142
- struct Person { name : String }
143
- ```
144
-
145
- <!-- dprint-ignore-end -->
146
-
147
- Enclose the code block in ` <!-- dprint-ignore-start --> ` and
148
- ` <!-- dprint-ignore-end --> ` to suppress the automatic formatting. Please use
149
- this sparingly.
150
-
151
- #### Use Meaningful Examples
132
+ ### Use Meaningful Examples
152
133
153
134
Code samples on the slides should be short and do something meaningful. Avoid
154
135
using generic placeholders like ` Foo ` , ` Bar ` , and ` Baz ` . Using descriptive names
155
136
from a real-world, even if simplified, domain makes the code easier to
156
137
understand and relate to.
157
138
158
- #### Interactive Code Snippets
139
+ ### Plan Interactive Code Snippets
159
140
160
141
All Rust code blocks in the course are not static text but are live, editable
161
142
playgrounds. An important teaching method is for the instructor to edit these
@@ -166,37 +147,6 @@ Contributors should design their slides with this interactivity in mind. The
166
147
initial state of the code should be a good starting point for a live
167
148
demonstration.
168
149
169
- ### Code Blocks
170
-
171
- Code blocks are a critical part of the course. To ensure they are consistent and
172
- behave as expected, please follow these conventions.
173
-
174
- #### Language Identifiers
175
-
176
- Use the following language identifiers for fenced code blocks:
177
-
178
- - ** ` rust ` ** : For Rust code examples.
179
- - ** ` shell ` ** : For shell commands. Use a ` $ ` prompt for consistency. Omit the
180
- prompt for multi-line commands or when the output is shown.
181
- - ** ` bob ` ** : For ASCII art diagrams generated by ` mdbook-bob ` .
182
- - ** ` ignore ` ** : For code snippets that are not complete, self-contained programs
183
- or are for illustrative purposes only and should not be compiled.
184
-
185
- #### mdbook Annotations
186
-
187
- You can add annotations to Rust code blocks to control how they are tested and
188
- displayed:
189
-
190
- - ** ` editable ` ** : Makes the code block an interactive playground where users can
191
- edit and run the code. This should be used for most Rust examples.
192
- - ** ` compile_fail ` ** : Indicates that the code is expected to fail compilation.
193
- This is used to demonstrate specific compiler errors.
194
- - ** ` should_panic ` ** : Indicates that the code is expected to panic when run.
195
- - ** ` warnunused ` ** : Re-enables ` unused ` lints for a code block. By default, the
196
- course's test runner disables lints for unused variables, imports, etc., to
197
- avoid distracting warnings. Use this annotation only when a warning is part of
198
- the lesson.
199
-
200
150
### ` mdbook ` and ` mdbook-course ` Conventions
201
151
202
152
The project uses ` mdbook ` features in specific ways, as well as a custom
@@ -318,6 +268,56 @@ explanation of what the resource contains and why it is relevant. A vague
318
268
reference is not helpful, but a specific one can be a great tool for
319
269
self-learners.
320
270
271
+ ## Code Blocks Mechanics
272
+
273
+ Code blocks are a critical part of the course. To ensure they are consistent and
274
+ behave as expected, please follow these conventions.
275
+
276
+ ### Language Identifiers
277
+
278
+ Use the following language identifiers for fenced code blocks:
279
+
280
+ - ** ` rust ` ** : For Rust code examples.
281
+ - ** ` shell ` ** : For shell commands. Use a ` $ ` prompt for consistency. Omit the
282
+ prompt for multi-line commands or when the output is shown.
283
+ - ** ` bob ` ** : For ASCII art diagrams generated by ` mdbook-bob ` .
284
+ - ** ` ignore ` ** : For code snippets that are not complete, self-contained programs
285
+ or are for illustrative purposes only and should not be compiled.
286
+
287
+ ### mdbook Annotations
288
+
289
+ You can add annotations to Rust code blocks to control how they are tested and
290
+ displayed:
291
+
292
+ - ** ` editable ` ** : Makes the code block an interactive playground where users can
293
+ edit and run the code. This should be used for most Rust examples.
294
+ - ** ` compile_fail ` ** : Indicates that the code is expected to fail compilation.
295
+ This is used to demonstrate specific compiler errors.
296
+ - ** ` should_panic ` ** : Indicates that the code is expected to panic when run.
297
+ - ** ` warnunused ` ** : Re-enables ` unused ` lints for a code block. By default, the
298
+ course's test runner disables lints for unused variables, imports, etc., to
299
+ avoid distracting warnings. Use this annotation only when a warning is part of
300
+ the lesson.
301
+
302
+ ### Rust Code Formatting
303
+
304
+ When showing Rust code inline, please use the same spacing as ` rustfmt ` : ` 3 * x `
305
+ instead of ` 3*x ` . However, feel free to remove newlines when it can make the
306
+ code more compact and easier to understand, e.g., you can define a struct on one
307
+ line if it is not the focus of your example:
308
+
309
+ <!-- dprint-ignore-start -->
310
+
311
+ ``` rust
312
+ struct Person { name : String }
313
+ ```
314
+
315
+ <!-- dprint-ignore-end -->
316
+
317
+ Enclose the code block in ` <!-- dprint-ignore-start --> ` and
318
+ ` <!-- dprint-ignore-end --> ` to suppress the automatic formatting. Please use
319
+ this sparingly.
320
+
321
321
## Translations
322
322
323
323
This section is about what you write in the translation. We describe
0 commit comments