WG21: C++ Standards Committee Papers
Introduction
The top-level of this repository contains the source code for various proposals
and the generated/
directory contains the generated proposals (HTML or PDF).
This repository also includes a paper-writing framework using Pandoc.
Status
- P1371: Pattern Matching
- P1469: Disallow
_
Usage in C++20 for Pattern Matching in C++23 - P1260: Pattern Matching - Requested to unify with P1308
- P0655:
visit<R>
: Explicit Return Type forvisit
- Accepted in C++20 - D0080: Tweaks to the Kona Variant - Encouraged to return with
P
-papers - P0080: Variant: Discriminated Union with Value Semantics - Not presented
- N3887: Consistent Metafunction Aliases - Accepted in C++14
Generation
make <paper>.pdf # `<paper>.md` -> `generated/<paper>.pdf`
make <paper>.html # `<paper>.md` -> `generated/<paper>.html`
Integration
git submodule add https://github.com/mpark/wg21.git
echo "include wg21/Makefile" > Makefile
make <paper>.pdf # `<paper>.md` -> `generated/<paper>.pdf`
make <paper>.html # `<paper>.md` -> `generated/<paper>.html`
Formatting
This framework provides support for various common elements for C++ papers.
- Title
- Table of Contents
- Markdown
- Tony Tables
- Proposed Wording
- Citations
- References
- Unicode Considerations
Title
The title is specified in a YAML metadata block.
date: today
will generate today's date inYYYY-MM-DD
(ISO 8601) format.
YAML lists can be used to specify multiple audiences and authors:
---
title: Integration of chrono with text formatting
document: P1361R0
date: 2018-10-16
audience:
- Library Evolution Working Group
- Library Working Group
author:
- name: Victor Zverovich
email: <victor.zverovich@gmail.com>
- name: Daniela Engert
email: <dani@ngrt.de>
- name: Howard E. Hinnant
email: <howard.hinnant@gmail.com>
---
Table of Contents
The default toc-depth
is 3
, but it can be specified to go deeper:
Markdown
Refer to the full Pandoc Markdown spec for useful extensions!
Within Code Blocks
Within ```
, ```cpp
, and ```diff
code blocks, any text
surrounded by the @
symbol is formatted as Markdown! This is useful for
conventions such as see below
, unspecified
, and exposition-only
variable names.
Tony Tables
Tony Tables are fenced Div
blocks that open with ::: tonytable
and close with :::
. Fenced code blocks are the only elements that
actually get added to Tony Tables, except that the last header (if any) before
a fenced code block is attached to the cell above. Each code block is
pushed onto the current row.
::: tonytable
### Before
```cpp
switch (x) {
case 0: std::cout << "got zero"; break;
case 1: std::cout << "got one"; break;
default: std::cout << "don't care";
}
```
### After
```cpp
inspect (x) {
0: std::cout << "got zero";
1: std::cout << "got one";
_: std::cout << "don't care";
}
```
:::
Each fenced code block is pushed onto the current row,
and horizontal rules (---
) are used to move to the next row.
::: tonytable
### Before
```cpp
switch (x) {
case 0: std::cout << "got zero"; break;
case 1: std::cout << "got one"; break;
default: std::cout << "don't care";
}
```
### After
```cpp
inspect (x) {
0: std::cout << "got zero";
1: std::cout << "got one";
_: std::cout << "don't care";
}
```
---
```cpp
if (s == "foo") {
std::cout << "got foo";
} else if (s == "bar") {
std::cout << "got bar";
} else {
std::cout << "don't care";
}
```
```cpp
inspect (s) {
"foo": std::cout << "got foo";
"bar": std::cout << "got bar";
_: std::cout << "don't care";
}
```
:::
Proposed Wording
Paragraph Numbers
Paragraph numbers are bracketed Span
elements that look
like: [2]{.pnum}
and [2.1]{.pnum}
.
[2]{.pnum} An expression is _potentially evaluated_ unless it is an unevaluated
operand (7.2) or a subexpression thereof. The set of _potential results_ of
an expression `e` is defined as follows:
- [2.1]{.pnum} If `e` is an _id-expression_ (7.5.4), the set contains only `e`.
- [2.2]{.pnum} If `e` is a subscripting operation (7.6.1.1) with an array operand,
the set contains the potential results of that operand.
Code Changes
Wording Changes
Large changes are fenced Div
blocks with ::: add
for additions, ::: rm
for removals.
Small, inline changes are bracketed Span
elements that looks like
[<new text>]{.add}
or [<old text>]{.rm}
.
Grammar Changes
Use line blocks (|
) in order to preserve the leading spaces.
> | _selection-statement:_
> | `if constexpr`_~opt~_ `(` _init-statement~opt~_ _condition_ `)` _statement_
> | `if constexpr`_~opt~_ `(` _init-statement~opt~_ _condition_ `)` _statement_ `else` _statement_
> | `switch (` _init-statement~opt~_ _condition_ `)` _statement_
> | [`inspect` `constexpr`~_opt_~ `(` _init-statement~opt~_ _condition_ `)` `{`
> _inspect-case-seq_
> `}`]{.add}
>
> ::: add
> | _inspect-case-seq:_
> | _inspect-case_
> | _inspect-case-seq_ _inspect-case_
>
> | _inspect-case:_
> | _attribute-specifier-seq~opt~_ _inspect-pattern_ _inspect-guard~opt~_ `:` _statement_
>
> | _inspect-pattern:_
> | _wildcard-pattern_
> | _identifier-pattern_
> | _constant-pattern_
> | _structured-binding-pattern_
> | _alternative-pattern_
> | _binding-pattern_
> | _extractor-pattern_
>
> | _inspect-guard:_
> | `if (` _expression_ `)`
> :::
Citations
In-text citations look like this: [@<id>]
References
Automatic References
The bibliography is automatically generated from https://wg21.link/index.yaml for citations of the following types.
Type | Id |
---|---|
Paper | Nxxxx / PxxxxRn |
Issue | CWGxxxx / EWGxxxx / LWGxxxx / LEWGxxxx / FSxxxx |
Editorial | EDITxxx |
Standing Document | SDx |
The [@N3546]
example from Citations generates:
Use
make update
to update the local cache of index.yaml.
Manual References
Manual references are specified in a YAML metadata block similar to Title, typically at the bottom of the document.
The `id` field is for in-text citations (e.g., [@PAT]),
and `citation-label` is the label for the reference.
Typically `id` and `citation-label` are kept the same.
---
references:
- id: PAT
citation-label: Patterns
title: "Pattern Matching in C++"
author:
- family: Park
given: Michael
URL: https://github.com/mpark/patterns
---
Unicode Considerations
If you build for LaTeX output, and you have Unicode characters in any of your paper's source code, you may have problems. First of all, the default pdf engine simply does not support Unicode characters at all. You can add --pdf-engine=xelatex
to the call to pandoc
in the Makefile to use xelatex as your engine instead. That gives you access to some font selections for different parts of your paper (see the Fonts section of the Pandoc manual at https://pandoc.org/MANUAL.html#fonts). The option that controls your source code fonts is monofont
. You can add a line with your monofont
choice to your YAML metadata block. Here, it's "DejaVu Sans Mono" which provides glyphs for a large amount of the Unicode characters:
---
title: Integration of chrono with text formatting
document: P1361R0
date: 2018-10-16
audience:
- Library Evolution Working Group
- Library Working Group
author:
- name: Victor Zverovich
email: <victor.zverovich@gmail.com>
- name: Daniela Engert
email: <dani@ngrt.de>
- name: Howard E. Hinnant
email: <howard.hinnant@gmail.com>
monofont: "DejaVu Sans Mono"
---
If you want the list of available fonts on your system, most supported systems will produce a list via the command-line tool fc-list
.
Other Papers
Requirements
pdflatex
pandoc
(>= 2.7.3)pandoc-citeproc
python3
panflute
OS X
brew cask install mactex
brew install pandoc pandoc-citeproc python
pip3 install panflute
Ubuntu
Manually install the latest pandoc release following their instructions.
sudo apt-get install texlive-latex-base
pip3 install panflute
Debian
Debian installation may require these additional packages:
texlive-fonts-recommended
texlive-latex-recommended
texlive-latex-extra
Resources
- Blog Post: How I format my C++ papers
- Lightning Talk @ C++Now 2019: WG21 Paper in Markdown