alx-0014 - Refactor syntax of preprocessing directives
Open
Nobody has claimed this yet.
cwg
- Dominant language
- TeX
- Stars
- 221
- Forks
- 813
- Avg merge
- 16h 4m
- Merged PRs (30d)
- 36
Description
Hi!
This is an editorial refactor I'm proposing to the C Committee. The C Committee wanted to make sure that the C++ Committee didn't have any objections before accepting it, so here I am.
The proposal below applies to the C2y working draft, but it almost applies to the C++ working draft, just changing the section numbers in the obvious way.
Would you mind applying this change editorially?
Cheers,
Alex
Name
alx-0014r6 - Refactor syntax of preprocessing directives
Category
Cosmetic refactor; readability; editorial;
Authors
Alejandro Colomar <alx@kernel.org>
History
<https://www.alejandro-colomar.es/src/alx/alx/wg14/alx-0014.git/>
r4 (2025-08-29):
- Split from alx-0014.
r5 (2025-08-31):
- Move alx-0014 to a separate proposal: alx-0065.
r6 (2025-08-31):
- Merge the split proposals into a single on with subsections.
Principles
- Keep the language small and simple
- Facilitate interoperability
- Codify existing practice to address evident deficiencies
Rationale
Editorial change. This moves text around for better
organization and readability. No semantic changes. This makes
it so that any future proposals to the preprocessor will be
easier to apply.
The proposal is split in subsections, separated by '---', for
better readability.
This proposal applies as is to the C++ latest draft, N5014, only
changing section numbers and their titles.
This change has prior art in C++, as they've done the same exact
thing with their pp-import directive. I guess they haven't done
it with the other directives for compatibility with us, so let's
help them and do it everywhere.
Interaction with other proposals
This blocks alx-0003 ("Add directives #def and #enddef")
This blocks alx-0013 ("Prohibit non-directives (other than ID directives)").
---
Name
alx-0014A - Refactor syntax of include directives
Proposed wording
Based on C N3550.
6.10.1 Preprocessing directives :: General (C++: 15.1 :: Preamble)
@@ Syntax, p1 (C++: no 'Syntax' subtitle)
control-line:
- <b># include</b> pp-tokens new-line
+ include-directive
pp-import (C++ only)
<b># embed</b> pp-tokens new-line
<b># define</b> identifier replacement-list new-line
<b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
<b># define</b> identifier lparen <b>... )</b> replacement-list new-line
<b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
<b># undef</b> identifier new-line
<b># line</b> pp-tokens new-line
<b># error</b> pp-tokens(opt) new-line
<b># warning</b> pp-tokens(opt) new-line
<b># pragma</b> pp-tokens(opt) new-line
<b>#</b> new-line
6.10.3 Source file inclusion (C++: 15.3)
## Add 'Syntax' before 'Constraints' (C++: No subtitles)
@@ Syntax, new p after title
+include-directive:
+ <b># include</b> pp-tokens new-line
---
Name
alx-0014B - Refactor syntax of embed directives
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
control-line:
<b># include</b> pp-tokens new-line
pp-import (C++ only)
- <b># embed</b> pp-tokens new-line
+ embed-directive
<b># define</b> identifier replacement-list new-line
<b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
<b># define</b> identifier lparen <b>... )</b> replacement-list new-line
<b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
<b># undef</b> identifier new-line
<b># line</b> pp-tokens new-line
<b># error</b> pp-tokens(opt) new-line
<b># warning</b> pp-tokens(opt) new-line
<b># pragma</b> pp-tokens(opt) new-line
<b>#</b> new-line
...
-pp-parameter:
- pp-parameter-name pp-parameter-clause(opt)
-
-pp-parameter-name:
- pp-standard-parameter
- pp-prefixed-parameter
-
-pp-standard-parameter:
- identifier
-
-pp-prefixed-parameter
- identifier <b>::</b> identifier
-
-pp-parameter-clause:
- <b>(</b> pp-balanced-token-sequence(opt) <b>)</b>
-
-pp-balanced-token-sequence:
- pp-balanced-token
- pp-balanced-token-sequence pp-balanced-token
-
-pp-balanced-token:
- <b>(</b> pp-balanced-token-sequence(opt) <b>)</b>
- <b>[</b> pp-balanced-token-sequence(opt) <b>]</b>
- <b>{</b> pp-balanced-token-sequence(opt) <b>}</b>
- <r>any pp-token other than a parenthesis, a bracket, or a brace</r>
-
-embed-parameter-sequence:
- pp-parameter
- embed-parameter-sequence pp-parameter
6.10.4.1 Binary resource inclusion :: #embed preprocessing directive
## Add 'Syntax' before 'Description'
@@ Syntax, new p after title
+embed-directive:
+ <b># embed</b> pp-tokens new-line
+
+pp-parameter:
+ pp-parameter-name pp-parameter-clause(opt)
+
+pp-parameter-name:
+ pp-standard-parameter
+ pp-prefixed-parameter
+
+pp-standard-parameter:
+ identifier
+
+pp-prefixed-parameter
+ identifier <b>::</b> identifier
+
+pp-parameter-clause:
+ <b>(</b> pp-balanced-token-sequence(opt) <b>)</b>
+
+pp-balanced-token-sequence:
+ pp-balanced-token
+ pp-balanced-token-sequence pp-balanced-token
+
+pp-balanced-token:
+ <b>(</b> pp-balanced-token-sequence(opt) <b>)</b>
+ <b>[</b> pp-balanced-token-sequence(opt) <b>]</b>
+ <b>{</b> pp-balanced-token-sequence(opt) <b>}</b>
+ <r>any pp-token other than a parenthesis, a bracket, or a brace</r>
+
+embed-parameter-sequence:
+ pp-parameter
+ embed-parameter-sequence pp-parameter
---
Name
alx-0014C - Refactor syntax of macros
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
control-line:
<b># include</b> pp-tokens new-line
<b># embed</b> pp-tokens new-line
- <b># define</b> identifier replacement-list new-line
- <b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
- <b># define</b> identifier lparen <b>... )</b> replacement-list new-line
- <b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
+ define-directive
- <b># undef</b> identifier new-line
+ undef-directive
<b># line</b> pp-tokens new-line
<b># error</b> pp-tokens(opt) new-line
<b># warning</b> pp-tokens(opt) new-line
<b># pragma</b> pp-tokens(opt) new-line
<b>#</b> new-line
...
-lparen:
- a <b>(</b> character not immediately preceded by white space
-
-replacement-list:
- pp-tokens(opt)
...
-identifier-list:
- identifier
- identifier-list <b>,</b> identifier
6.10.5.1 Macro replacement :: General
## Add 'Syntax' before 'Constraints'
@@ Syntax, new p after title
+define-directive:
+ <b># define</b> identifier replacement-list new-line
+ <b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
+ <b># define</b> identifier lparen <b>... )</b> replacement-list new-line
+ <b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
+
+undef-directive:
+ <b># undef</b> identifier new-line
+
+lparen:
+ a <b>(</b> character not immediately preceded by white space
+
+replacement-list:
+ pp-tokens(opt)
+
+identifier-list:
+ identifier
+ identifier-list <b>,</b> identifier
---
Name
alx-0014D - Refactor syntax of conditional directives
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
-if-section:
- if-group elif-groups(opt) else-group(opt) endif-line
-
-if-group:
- <b># if</b> constant-expression newline group(opt)
- <b># ifdef</b> identifier new-line group(opt)
- <b># ifndef</b> identifier new-line group(opt)
-
-elif-groups:
- elif-group
- elif-groups elif-group
-
-elif-group:
- <b># elif</b> constant-expression new-line group(opt)
- <b># elifdef</b> identifier new-line group(opt)
- <b># elifndef</b> identifier new-line group(opt)
-
-else-group:
- <b># else</b> new-line group(opt)
-
-endif-line:
- <b># endif</b> new-line
6.10.2 Conditional inclusion
@@ Syntax, p1
+if-section:
+ if-group elif-groups(opt) else-group(opt) endif-line
+
+if-group:
+ <b># if</b> constant-expression newline group(opt)
+ <b># ifdef</b> identifier new-line group(opt)
+ <b># ifndef</b> identifier new-line group(opt)
+
+elif-groups:
+ elif-group
+ elif-groups elif-group
+
+elif-group:
+ <b># elif</b> constant-expression new-line group(opt)
+ <b># elifdef</b> identifier new-line group(opt)
+ <b># elifndef</b> identifier new-line group(opt)
+
+else-group:
+ <b># else</b> new-line group(opt)
+
+endif-line:
+ <b># endif</b> new-line
+
...
---
Name
alx-0014E - Refactor syntax of line directives
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
control-line:
<b># include</b> pp-tokens new-line
<b># embed</b> pp-tokens new-line
<b># define</b> identifier replacement-list new-line
<b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
<b># define</b> identifier lparen <b>... )</b> replacement-list new-line
<b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
<b># undef</b> identifier new-line
- <b># line</b> pp-tokens new-line
+ line-directive
<b># error</b> pp-tokens(opt) new-line
<b># warning</b> pp-tokens(opt) new-line
<b># pragma</b> pp-tokens(opt) new-line
<b>#</b> new-line
6.10.6 Line control
## Add 'Syntax' before 'Constraints'
@@ Syntax, new p after title
+line-directive:
+ <b># line</b> pp-tokens new-line
---
Name
alx-0014F - Refactor syntax of diagnostic directives
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
control-line:
<b># include</b> pp-tokens new-line
<b># embed</b> pp-tokens new-line
<b># define</b> identifier replacement-list new-line
<b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
<b># define</b> identifier lparen <b>... )</b> replacement-list new-line
<b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
<b># undef</b> identifier new-line
<b># line</b> pp-tokens new-line
- <b># error</b> pp-tokens(opt) new-line
- <b># warning</b> pp-tokens(opt) new-line
+ diagnostic-directive
<b># pragma</b> pp-tokens(opt) new-line
<b>#</b> new-line
6.10.7 Diagnostic directives
## Add 'Syntax' before 'Constraints'
@@ Syntax, new p after title
+diagnostic-directive:
+ <b># error</b> pp-tokens(opt) new-line
+ <b># warning</b> pp-tokens(opt) new-line
---
Name
alx-0014G - Refactor syntax of pragma directives
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
control-line:
<b># include</b> pp-tokens new-line
<b># embed</b> pp-tokens new-line
<b># define</b> identifier replacement-list new-line
<b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
<b># define</b> identifier lparen <b>... )</b> replacement-list new-line
<b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
<b># undef</b> identifier new-line
<b># line</b> pp-tokens new-line
<b># error</b> pp-tokens(opt) new-line
<b># warning</b> pp-tokens(opt) new-line
- <b># pragma</b> pp-tokens(opt) new-line
+ pragma-directive
<b>#</b> new-line
6.10.8 Pragma directive
## Add 'Syntax' before 'Constraints'
@@ Syntax, new p after title
+pragma-directive:
+ <b># pragma</b> pp-tokens(opt) new-line
---
Name
alx-0014H - Refactor syntax of null directives
Proposed wording
Based on N3550.
6.10.1 Preprocessing directives :: General
@@ Syntax, p1
control-line:
<b># include</b> pp-tokens new-line
<b># embed</b> pp-tokens new-line
<b># define</b> identifier replacement-list new-line
<b># define</b> identifier lparen identifier-list(opt) <b>)</b> replacement-list new-line
<b># define</b> identifier lparen <b>... )</b> replacement-list new-line
<b># define</b> identifier lparen identifier-list <b>, ... )</b> replacement-list new-line
<b># undef</b> identifier new-line
<b># line</b> pp-tokens new-line
<b># error</b> pp-tokens(opt) new-line
<b># warning</b> pp-tokens(opt) new-line
<b># pragma</b> pp-tokens(opt) new-line
- <b>#</b> new-line
+ null-directive
6.10.9 Null directive
## Add 'Syntax' before 'Constraints'
@@ Syntax, new p after title
+null-directive:
+ <b>#</b> new-line
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the current C++ draft's preprocessing sections 6.10.1–6.10.8 with the proposed wording in this issue. Apply the listed editorial reorganization across the include, embed, macro, conditional, line, diagnostic, pragma, and null directive sections, preserving semantics; done means the draft reflects all requested changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, tex
- Domain
- documentation
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100