|
| 1 | +--- |
| 2 | +name: d2mcpp-authoring |
| 3 | +description: >- |
| 4 | + Authoring conventions, design principles, and file formats for the d2mcpp |
| 5 | + (D2X) Modern C++ tutorial project. Use this whenever you add or edit a C++ |
| 6 | + language-feature lesson — a book chapter, a dslings exercise, a reference |
| 7 | + solution, or when registering them in SUMMARY/xmake/changelog. Trigger it for |
| 8 | + any request like "add a chapter for X", "write a dslings exercise for fold |
| 9 | + expressions", "add the constexpr lesson", "fill the cpp14 section", or |
| 10 | + anything touching book/src, book/en/src, dslings/, or solutions/. Even small |
| 11 | + edits should follow these conventions so the bilingual + book/code/checker |
| 12 | + artifacts stay in sync. |
| 13 | +--- |
| 14 | + |
| 15 | +# d2mcpp (D2X) Authoring Conventions |
| 16 | + |
| 17 | +d2mcpp teaches **Modern C++ core language features** through a tightly coupled |
| 18 | +quartet: **Book (mdBook) + Code (dslings exercises) + Solution + Auto-checker |
| 19 | +(`d2x checker`)**, all of it **bilingual (zh + en)**. A "lesson" is never one |
| 20 | +file — it is a coordinated set across several directories. The cardinal sin here |
| 21 | +is producing a half-set (a chapter with no exercise, a zh file with no en |
| 22 | +counterpart, an exercise not registered in xmake). This skill exists so every |
| 23 | +lesson lands complete and consistent. |
| 24 | + |
| 25 | +Read `references/anatomy.md` for the full directory map and the exact list of |
| 26 | +files every lesson must touch. Use the ready-made scaffolds in `assets/` rather |
| 27 | +than reconstructing format from memory. |
| 28 | + |
| 29 | +## The design principle (decide this BEFORE writing) |
| 30 | + |
| 31 | +The project is organized **by standard** (`cpp11/ cpp14/ cpp17/ cpp20/ cpp23/`). |
| 32 | +Honor that axis: |
| 33 | + |
| 34 | +- **Teach each feature as the standard that introduced it actually delivered |
| 35 | + it** — the historical state, compiled at its introduction standard. The |
| 36 | + compiler-driven (dslings) format is at its best when the learner feels the |
| 37 | + C++11-era restriction first (e.g. `constexpr` single-return, `std::is_pod`, |
| 38 | + copy-elision behavior). Folding every later refinement back into the |
| 39 | + introduction chapter erases that, and empties out the later-standard sections. |
| 40 | +- **Independent later capabilities become their own chapter under the later |
| 41 | + standard's section** — this is what fills `cpp14/17/20`. Examples: fold |
| 42 | + expressions → cpp17, `using enum` → cpp20, designated initializers → cpp20, |
| 43 | + `if constexpr` → cpp17, `decltype(auto)` → cpp14, `consteval`/`constinit` → cpp20. |
| 44 | +- **Pure refinements / rule-tweaks / deprecations stay in the introduction |
| 45 | + chapter as a short "特性演进 / Feature Evolution" note** with a cross-link |
| 46 | + forward — they are not chapter-worthy on their own. Examples: `auto x{1}` |
| 47 | + deduction change, `std::is_pod` deprecation pointer, guaranteed copy elision |
| 48 | + remark, P0136 inheriting-constructor semantics fix. |
| 49 | +- **Compile each chapter at its introduction standard.** Do not globally pin a |
| 50 | + newer standard. If one exercise genuinely needs a later standard, make it an |
| 51 | + **explicit, commented exception** in xmake — never a bare `-- TODO` hack. |
| 52 | + |
| 53 | +Background and the full per-feature evolution analysis live in |
| 54 | +`.agents/docs/2026-06-08-cpp11-feature-evolution-and-cxx20-baseline.md`. Consult |
| 55 | +it when deciding where a feature's later improvements should go. |
| 56 | + |
| 57 | +The decision rule, compactly: |
| 58 | + |
| 59 | +| Kind of later change | Where it goes | |
| 60 | +|---|---| |
| 61 | +| New independent syntax/ability | New chapter in the later standard's section | |
| 62 | +| Relaxation/tweak/deprecation | "Feature Evolution" note in the intro chapter + forward link | |
| 63 | + |
| 64 | +## The unit of work: one lesson = these files, all bilingual |
| 65 | + |
| 66 | +When adding a feature numbered `NN` with slug `topic` (e.g. `06-scoped-enums`): |
| 67 | + |
| 68 | +1. `book/src/<std>/NN-topic.md` — zh chapter |
| 69 | +2. `book/en/src/<std>/NN-topic.md` — en chapter (translate prose, keep code identical) |
| 70 | +3. `dslings/<std>/NN-topic-K.cpp` — one or more exercises (`K` = 0,1,2…), zh comments |
| 71 | +4. `dslings/en/<std>/NN-topic-K.cpp` — en exercises (translate comments only) |
| 72 | +5. `solutions/<std>/NN-topic-K.cpp` — reference solution per exercise |
| 73 | +6. Register each exercise target in `dslings/<std>/xmake.lua` |
| 74 | +7. Register each solution target in `solutions/xmake.lua` |
| 75 | +8. Add the chapter line to **both** `book/src/SUMMARY.md` and `book/en/src/SUMMARY.md` |
| 76 | +9. Add a changelog entry to **both** `book/src/changelog.md` and `book/en/src/changelog.md` |
| 77 | + |
| 78 | +Missing any of these = an incomplete lesson. `references/anatomy.md` has the |
| 79 | +exact registration snippets and SUMMARY/changelog line formats. |
| 80 | + |
| 81 | +## Naming and numbering |
| 82 | + |
| 83 | +- Chapter/exercise prefix is a **two-digit** sequence `NN` within the standard |
| 84 | + section; slug is **kebab-case** and matches book + dslings + solutions. |
| 85 | +- Exercises split into `-0`, `-1`, … by sub-topic; a single-exercise chapter has |
| 86 | + no numeric suffix on the dslings target name but the file is still `NN-topic.cpp`. |
| 87 | +- The **`d2x checker <name>`** name is the slug (and `<slug>-1`, `<slug>-2` for |
| 88 | + later exercises) — it omits the `NN-` prefix. Keep checker names, file names, |
| 89 | + and book references mutually consistent. |
| 90 | + |
| 91 | +## Book chapter format |
| 92 | + |
| 93 | +Use `assets/chapter.zh.md` / `assets/chapter.en.md`. Required structure, in order: |
| 94 | + |
| 95 | +1. Language-switch header `<div align=right> 🌎 [中文] | [English]` + link defs. |
| 96 | + - zh links: `[中文]: ./NN-topic.html` and `[English]: ../en/<std>/NN-topic.html` |
| 97 | + - en links: `[中文]: ../../<std>/NN-topic.html` and `[English]: ./NN-topic.html` |
| 98 | +2. `# 标题 - english name` (zh) / `# English Title` (en), then a one-paragraph |
| 99 | + intro that states the feature **was introduced in C++NN** and what problem it solves. |
| 100 | +3. Resource table `| Book | Video | Code | X |` — cppreference link + markdown |
| 101 | + permalink + video link + first practice-code permalink. |
| 102 | +4. Bold motivation blocks: `**为什么引入?**`, `**和……的区别?**`. |
| 103 | +5. Numbered Chinese-numeral sections, in order: `## 一、基础用法和场景`, |
| 104 | + `## 二、真实案例 - STL 中的 <feature>`, `## 三、注意事项`, |
| 105 | + `## 四、练习代码`, `## 五、其他`. |
| 106 | +6. `## 二、真实案例` corroborates the feature with **real, verbatim STL code** |
| 107 | + quoted from the in-repo `msvc-stl/` basis — see "The 真实案例 section" below. |
| 108 | +7. `## 四、练习代码` lists **every** exercise topic of the chapter (`-0`, `-1`, …, |
| 109 | + matching the dslings/xmake count) with dslings links as an index, but the checker |
| 110 | + block shows only the **single entry** command `d2x checker <name>` — `d2x` auto- |
| 111 | + advances through the remaining exercises, so do NOT list one command per exercise. |
| 112 | + Then a `### 练习交流讨论` link to the chapter's forum thread. Each exercise's own |
| 113 | + `d2x checker <name>-K` name and a Tips line **specific to that exercise** belong in |
| 114 | + that exercise file's header, not in the book. |
| 115 | +8. `## 五、其他` is the fixed footer (forum / repo / video list / xlings links). |
| 116 | +9. If the feature evolved later, add a **`## 特性演进 / Feature Evolution`** |
| 117 | + block before `## 五、其他` — introduced standard + bullet list of later |
| 118 | + refinements + forward links to the later-standard chapters. |
| 119 | + |
| 120 | +Keep prose tone consistent with existing chapters: explanatory, example-driven, |
| 121 | +short code blocks with inline comments showing the failure and the fix. |
| 122 | + |
| 123 | +### The 真实案例 / Real-World Case section (msvc-stl basis) |
| 124 | + |
| 125 | +`## 二、真实案例` exists to prove the feature earns its place by showing **real |
| 126 | +production code, quoted verbatim** — never invented, never paraphrased. The single |
| 127 | +source of truth is the in-repo vendored MSVC STL basis at the top-level |
| 128 | +**`msvc-stl/`** (the complete upstream `stl/` subtree; `msvc-stl/SOURCE.md` records |
| 129 | +the pinned upstream commit and how to refresh it). Rules: |
| 130 | + |
| 131 | +- Quote from `msvc-stl/stl/inc/<header>` (or `src/`) **byte-for-byte**; mark any |
| 132 | + elision with `(有删节)` / `(abridged)`. Do not reconstruct from memory. |
| 133 | +- Keep internal macros (`_NODISCARD`, `_CONSTEXPR17`, `_STD`, …) as written and add |
| 134 | + one line telling the reader they are library-internal and ignorable. |
| 135 | +- Pick a usage that **echoes a syntax point from `## 一`** (e.g. `std::begin`'s |
| 136 | + `auto … -> decltype(...)` for the auto/decltype chapter), so the section reads as |
| 137 | + "you use it this way → the standard library does too". |
| 138 | +- **Scope-lock to the chapter's standard**: a `cpp11` chapter quotes C++11-era |
| 139 | + usage only; do not show later forms (e.g. `decltype(auto)`). |
| 140 | +- Link to the **local `msvc-stl/` path**, not the upstream GitHub repo, so the |
| 141 | + citation stays pinned to the vendored snapshot. |
| 142 | +- Every chapter should carry this section. If a feature genuinely has no |
| 143 | + representative usage in the STL implementation, omit it and state why in the PR. |
| 144 | + |
| 145 | +## dslings exercise format |
| 146 | + |
| 147 | +Use `assets/exercise.cpp`. Essentials: |
| 148 | + |
| 149 | +- Header comment block: `d2mcpp` URL, `license: Apache-2.0`, `file:` path, |
| 150 | + `Exercise/练习:` line (`<std> | NN - topic | 中文小标题`), `Tips/提示:`, |
| 151 | + `Docs/文档:` (cppreference), and the `Auto-Checker/自动检测命令:` with |
| 152 | + `d2x checker <name>`. |
| 153 | +- `#include <d2x/cpp/common.hpp>` then any std headers. |
| 154 | +- `main()` seeded with **intentional errors** the learner fixes, each flagged by |
| 155 | + a numbered inline comment (`// 1.…`, `// 2.…`) telling them what to do. |
| 156 | +- Checkpoint macros from `d2x/cpp/common.hpp`: |
| 157 | + - `d2x_assert(cond)` / `d2x_assert_eq(a, b)` — runtime checkpoints; learners |
| 158 | + must make them pass by fixing code, **not** by deleting the checkpoint. |
| 159 | + - `D2X_YOUR_ANSWER` — a fill-in placeholder the learner replaces. |
| 160 | + - `D2X_WAIT` — separates exercises; learner deletes/comments it to advance. |
| 161 | + Put exactly one at the end of each exercise's checkpoints. |
| 162 | + - `D2X_DONT_DELETE_THIS` — guards lines that must not be removed. |
| 163 | +- The **en exercise translates only the comment prose**; the code stays byte-for-byte |
| 164 | + identical to the zh exercise so checker behavior matches. |
| 165 | + |
| 166 | +## Reference solution format |
| 167 | + |
| 168 | +Use `assets/solution.cpp`. It is the corrected exercise with: |
| 169 | + |
| 170 | +- A solution header: `reference solution for: <exercise path>`, plus the note |
| 171 | + that it is **for CI/maintainers only, not a tutorial entry**, and a pointer |
| 172 | + back to the exercise file. |
| 173 | +- `D2X_WAIT` removed; all checkpoints passing; unused locals silenced with |
| 174 | + `(void)var;` rather than left to warn. |
| 175 | +- Same `#include`s and structure as the exercise. |
| 176 | + |
| 177 | +## Definition of done |
| 178 | + |
| 179 | +Before claiming a lesson complete, verify the whole set exists and is wired up, |
| 180 | +and that the exercise/solution actually build & check. See |
| 181 | +`references/anatomy.md` for the verification commands (`d2x checker <name>` and |
| 182 | +the xmake build) — run them; do not assert success without the output. |
0 commit comments