@@ -17,13 +17,23 @@ Rules for all work on WG21 papers in this repository.
1717 not read, write, or modify any file in that folder
18187 . Padded tables with aligned pipe characters in every table on every rewrite
19198 . WG21-appropriate style
20- 9 . ` [P####R#](https://wg21.link/p####r#) ` link convention for all paper references
20+ 9 . Paper reference links must be versioned
21+ (e.g. ` [P4003R0] ` not ` [P4003] ` ). Use
22+ ` [P####R#](https://wg21.link/p####r#) ` when the wg21.link
23+ URL resolves. If wg21.link gives a 404 for a specific
24+ version (e.g. pre-mailing papers), use the isocpp.org URL
25+ instead (e.g. ` https://isocpp.org/files/papers/P4007R1.pdf ` ).
26+ All paper links must be verified to return a non-404 response
27+ before the paper is considered complete
212810 . Paper titles on first mention
222911 . Backticks for code identifiers in headings
30+ 12 . All hyperlinks in the document must resolve to a non-404
31+ response before the paper is considered complete. This
32+ applies to all URLs, not only WG21 paper references
2333
2434## Front Matter
2535
26- 12 . Every paper begins with a valid YAML front matter block
36+ 13 . Every paper begins with a valid YAML front matter block
2737 delimited by ` --- ` . Required and optional fields:
2838
2939 ``` yaml
@@ -45,58 +55,64 @@ Rules for all work on WG21 papers in this repository.
4555 strings in the form `"Name <email>"`
4656 - ` audience` - required, unquoted comma-separated
4757 target audience (e.g. SG1, LEWG)
48- 13 . Do not add front matter fields that the Pandoc template
58+ 14 . Do not add front matter fields that the Pandoc template
4959 (`tools/wg21.html5`) does not consume
5060
5161# # Language and Grammar
5262
53- 14. American English unless otherwise specified
54- 15. Follow the Chicago Manual of Style unless otherwise specified
55- 16. Use the Oxford comma
56- 17. Avoid dangling "This" - every sentence beginning with "This" must
63+ 15. American English by default. If a paper already uses
64+ British/Irish English consistently (e.g. "organisation",
65+ " behaviour" , "generalise"), preserve that convention -
66+ do not convert to American English. When in doubt, check
67+ the existing spelling in the file before editing.
68+ Papers where Mungo Gill is the sole author use Irish
69+ English
70+ 16. Follow the Chicago Manual of Style unless otherwise specified
71+ 17. Use the Oxford comma
72+ 18. Avoid dangling "This" - every sentence beginning with "This" must
5773 have a clear, unambiguous antecedent. If "This" could refer to
5874 more than one thing, replace it with a specific noun phrase
59- 18 . Do not end sentences with a preposition in formal papers -
75+ 19 . Do not end sentences with a preposition in formal papers -
6076 e.g. "worth building upon" not "worth building on"
61- 19 . "bound" = attached/tied to; "bounded" = limited -
77+ 20 . "bound" = attached/tied to; "bounded" = limited -
6278 e.g. "an allocator bound to that tenant's quota"
63- 20 . Possessive before a gerund -
79+ 21 . Possessive before a gerund -
6480 e.g. "coroutines' interacting" not "coroutines interacting"
65- 21 . "may" = permitted/possible; "might" = hypothetical/enabled but
81+ 22 . "may" = permitted/possible; "might" = hypothetical/enabled but
6682 not currently supported. Use precisely
67- 22 . Prefer "deeper" or "more thorough" over "full" for appendix
83+ 23 . Prefer "deeper" or "more thorough" over "full" for appendix
6884 cross-references. Understatement is better than hyperbole
69- 23 . Headings must not contain a dangling "This" - replace with a
85+ 24 . Headings must not contain a dangling "This" - replace with a
7086 specific noun phrase. e.g. "ABI Lock-In Makes the Architectural
7187 Gap Permanent" not "ABI Lock-In Makes This Permanent"
72- 24 . Transitive verbs must not leave their object implicit when the
88+ 25 . Transitive verbs must not leave their object implicit when the
7389 referent is not immediately obvious. Supply the object explicitly.
7490 e.g. "forgetting to forward the allocator" not "forgetting to
7591 forward"
76- 25 . Avoid ambiguous prepositional attachment. When a prepositional
92+ 26 . Avoid ambiguous prepositional attachment. When a prepositional
7793 phrase could modify either a nearby noun or the main verb,
7894 restructure to make the attachment clear.
7995 e.g. "The allocator - along with its state - must be
8096 discoverable" not "The allocator - with its state - must be
8197 discoverable" (where "with its state" could attach to
8298 " discoverable" )
83- 26 . Place "only" immediately before the word, phrase, or clause it
99+ 27 . Place "only" immediately before the word, phrase, or clause it
84100 modifies to avoid ambiguity.
85101 e.g. "provides only one mechanism" not "only provides one
86102 mechanism"
87- 27 . Do not use contractions (it's, they're, don't, etc.) in formal
103+ 28 . Do not use contractions (it's, they're, don't, etc.) in formal
88104 papers. Use the expanded form
89105
90106# # Code Examples
91107
92- 28 . Consistent comment style within a code block - either all
108+ 29 . Consistent comment style within a code block - either all
93109 comments are sentences (capitalized, with terminating punctuation)
94110 or all are fragments (lowercase, no period). Do not mix
95- 29 . Consistent capitalization in groups of code comments that
111+ 30 . Consistent capitalization in groups of code comments that
96112 summarize arithmetic or data
97- 30 . Align trailing comment columns when consecutive lines have
113+ 31 . Align trailing comment columns when consecutive lines have
98114 trailing comments
99- 31 . Fenced code blocks must not exceed 90 characters per
115+ 32 . Fenced code blocks must not exceed 90 characters per
100116 line. This rule does not apply to mermaid blocks -
101117 never reformat mermaid source. When wrapping is
102118 needed, follow the conventions for the block's
@@ -113,7 +129,7 @@ Rules for all work on WG21 papers in this repository.
113129 before the operator, align operators vertically
114130 - Trailing comments : shorten the gap between code and
115131 comment rather than wrapping the code, but keep
116- grouped comments aligned with each other (rule 30 )
132+ grouped comments aligned with each other (rule 31 )
117133 - If a trailing comment still exceeds 90 characters
118134 after tightening the gap, wrap the comment text to
119135 a second line. The continuation `//` must align
@@ -126,22 +142,22 @@ Rules for all work on WG21 papers in this repository.
126142
127143# # Lists
128144
129- 32 . Always insert a blank line before a bullet or numbered list.
145+ 33 . Always insert a blank line before a bullet or numbered list.
130146 Pandoc does not recognise a list that immediately follows a
131147 prose line without a separating blank line - the items render
132148 as inline text in both HTML and PDF
133149
134150# # Structure
135151
136- 33 . Sections with subsections should have at least one introductory
152+ 34 . Sections with subsections should have at least one introductory
137153 sentence between the section heading and the first subsection
138154 heading - do not leave an empty section heading
139- 34 . Every paper must contain a `## Revision History` section,
155+ 35 . Every paper must contain a `## Revision History` section,
140156 placed immediately after the Abstract's trailing `---` and
141157 before Section 1. Each revision is an H3 subheading in the
142158 form `### R<n>: <Month> <Year> (<pre-Meeting mailing>)`
143159 followed by a bullet list of changes
144- 35 . References and citations - for readers of printed copies :
160+ 36 . References and citations - for readers of printed copies :
145161 - Every hyperlink in the document body must also appear
146162 in the References section
147163 - Every hyperlink in the document body must have a
@@ -154,7 +170,7 @@ Rules for all work on WG21 papers in this repository.
154170 ` eel.is/c++draft/` sections, one entry for the NB
155171 ballot repository covering individual issue links
156172 - Use `wg21.link` short URLs for WG21 papers - do not
157- use `open-std.org` long-form URLs (see rule 9 )
173+ use `open-std.org` long-form URLs (see rules 9 and 12 )
158174 - Links inside markdown tables are exempt from citation
159175 markers (tables are dense reference lists where
160176 superscripts would harm readability)
@@ -167,7 +183,7 @@ Rules for all work on WG21 papers in this repository.
167183
168184# # Proposed Wording Sections
169185
170- 36 . Proposed wording uses Pandoc fenced divs and HTML
186+ 37 . Proposed wording uses Pandoc fenced divs and HTML
171187 ` <ins>` /`<del>` elements styled by `tools/paperstyle.css`.
172188 Three div classes are available :
173189
@@ -189,7 +205,7 @@ Rules for all work on WG21 papers in this repository.
189205 code blocks for code changes. Always use the inline
190206 ` <ins>` /`<del>` convention described here instead
191207
192- 37 . Fenced div formatting rules :
208+ 38 . Fenced div formatting rules :
193209
194210 - No space between `:::` and the class name :
195211 `:::wording` not `:: : wording`
@@ -201,7 +217,7 @@ Rules for all work on WG21 papers in this repository.
201217 - Markdown formatting (`*italic*`, `` `code` ``)
202218 works normally inside wording divs
203219
204- 38 . Code diffs in wording sections use raw HTML
220+ 39 . Code diffs in wording sections use raw HTML
205221 ` <pre><code>` blocks (not fenced `` ``` `` blocks)
206222 inside a `:::wording` div, with `<ins>` and `<del>`
207223 for inline changes. Angle brackets in code must be
@@ -223,18 +239,18 @@ Rules for all work on WG21 papers in this repository.
223239
224240## Tone
225241
226- 39 . Do not present options as predetermined conclusions. When
242+ 40 . Do not present options as predetermined conclusions. When
227243 recommending alternatives to a committee, present them as options
228244 to contemplate, not dictated outcomes
229- 40 . Avoid politically charged comparisons - do not invoke other
245+ 41 . Avoid politically charged comparisons - do not invoke other
230246 contentious features as analogies unless the comparison is
231247 structurally precise. If the structures being compared are
232248 fundamentally different, the analogy will be perceived as
233249 political
234250
235251## Abstract
236252
237- 41 . Every abstract opens with a single sentence on its own line -
253+ 42 . Every abstract opens with a single sentence on its own line -
238254 the brutal summary. No citations, no paper numbers, no
239255 hedging. The sentence must be true, complete, and
240256 unsentimental. It is the sentence a reader remembers after
0 commit comments