{"id":16690847,"url":"https://github.com/mpark/wg21","last_synced_at":"2025-09-08T08:43:56.013Z","repository":{"id":13339106,"uuid":"16026206","full_name":"mpark/wg21","owner":"mpark","description":"Framework for Writing C++ Committee Papers","archived":false,"fork":false,"pushed_at":"2025-01-13T07:22:04.000Z","size":12704,"stargazers_count":134,"open_issues_count":14,"forks_count":46,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-24T11:03:58.100Z","etag":null,"topics":["cpp","papers","proposals","tony-tables","wg21"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mpark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-01-18T13:41:48.000Z","updated_at":"2025-05-20T17:25:09.000Z","dependencies_parsed_at":"2024-10-27T11:49:26.314Z","dependency_job_id":"67e36176-92ad-4f77-98bb-44eda01f2a2c","html_url":"https://github.com/mpark/wg21","commit_stats":{"total_commits":432,"total_committers":16,"mean_commits":27.0,"dds":"0.15509259259259256","last_synced_commit":"0c965d0d7bb71b66401b324f655ad881063e16d3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mpark/wg21","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpark%2Fwg21","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpark%2Fwg21/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpark%2Fwg21/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpark%2Fwg21/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mpark","download_url":"https://codeload.github.com/mpark/wg21/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpark%2Fwg21/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274159386,"owners_count":25232633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","papers","proposals","tony-tables","wg21"],"created_at":"2024-10-12T16:05:43.779Z","updated_at":"2025-09-08T08:43:55.972Z","avatar_url":"https://github.com/mpark.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Framework for Writing C++ Committee Papers\n\n## Introduction\n\nThis is a paper-writing framework designed to ease the pain of authoring papers\nfor WG21, built on top of [Pandoc].\n\nIn short, you write your papers in Markdown and the framework produces the paper\neither in HTML or PDF.\n\n[Pandoc]: https://pandoc.org\n\n## Requirements\n\n  - `python3`\n  - `xelatex` (Only for PDF papers)\n\n### OS X\n\n```bash\nbrew install mactex # Only for PDF papers\n```\n\n### Ubuntu\n\n```bash\nsudo apt-get install texlive-xetex # Only for PDF papers\n```\n\n### Debian\n\nDebian installation may require these additional packages:\n\n  - `texlive-fonts-recommended`\n  - `texlive-latex-recommended`\n  - `texlive-latex-extra`\n\n## Integration\n\n```bash\ngit submodule add https://github.com/mpark/wg21.git\n\necho \"include wg21/Makefile\" \u003e Makefile\n\nmake \u003cpaper\u003e.pdf  # `\u003cpaper\u003e.md` -\u003e `generated/\u003cpaper\u003e.pdf`\nmake \u003cpaper\u003e.html # `\u003cpaper\u003e.md` -\u003e `generated/\u003cpaper\u003e.html`\n```\n\nSee [mpark/wg21-papers] for an example use of this project.\n\n[mpark/wg21-papers]: https://github.com/mpark/wg21-papers\n\n## Generation\n\n```bash\nmake \u003cpaper\u003e.pdf  # `\u003cpaper\u003e.md` -\u003e `generated/\u003cpaper\u003e.pdf`\nmake \u003cpaper\u003e.html # `\u003cpaper\u003e.md` -\u003e `generated/\u003cpaper\u003e.html`\n```\n\n## Formatting\n\nThis framework provides support for various common elements for C++ papers.\n\n- [Title](#title)\n- [Table of Contents](#table-of-contents)\n- [Markdown](#markdown)\n  - [Automatic Header Links](#automatic-header-links)\n  - [Embedded Markdown within Code](#embedded-markdown-within-code)\n- [Comparison Tables](#comparison-tables)\n- [Proposed Wording](#proposed-wording)\n  - [Paragraph Numbers](#paragraph-numbers)\n  - [Code Changes](#code-changes)\n  - [Wording Changes](#wording-changes)\n  - [Examples](#examples)\n  - [Notes](#notes)\n  - [Grammar Changes](#grammar-changes)\n- [Stable Names](#stable-names)\n- [Citations](#citations)\n- [References](#references)\n  - [Automatic References](#automatic-references)\n  - [Manual References](#manual-references)\n- [Unicode Considerations](#unicode-considerations)\n\n### Title\n\nThe title is specified in a YAML metadata block.\n\n![](img/title.png)\n\n\u003e `date: today` will generate today's date in `YYYY-MM-DD` (ISO 8601) format.\n\nYAML lists can be used to specify multiple audiences and authors:\n\n```yaml\n---\ntitle: Integration of chrono with text formatting\ndocument: P1361R0\ndate: 2018-10-16\naudience:\n  - Library Evolution Working Group\n  - Library Working Group\nauthor:\n  - name: Victor Zverovich\n    email: \u003cvictor.zverovich@gmail.com\u003e\n  - name: Daniela Engert\n    email: \u003cdani@ngrt.de\u003e\n  - name: Howard E. Hinnant\n    email: \u003choward.hinnant@gmail.com\u003e\n---\n```\n\n### Table of Contents\n\n![](img/toc-false.png)\n\n---\n\n![](img/toc-true.png)\n\n---\n\nThe default `toc-depth` is `3`, but it can be specified to go deeper:\n![](img/toc-depth.png)\n\n### Markdown\n\nRefer to the full [Pandoc Markdown] spec for useful extensions!\n\n[Pandoc Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown\n\n#### Automatic Header Links\n\nTo link to a header by its ID and have the header title automatically extracted\nas the link text, you may omit the link text like this: `[](#header-id)`.\n\nAssign an explicit ID to a header like this: `# Algorithm Return Type {#return-type}`.\nThen a link without a link text like `[](#return-type)` will automatically display\n\"Algorithm Return Type\" as the link text.\n\n```markdown\n# Algorithm Return Type {#return-type}\n\nText describing the return type...\n\n# Section\n\n- Except as mentioned above, the parallel range algorithms should return\n  the same type as the corresponding serial range algorithms. See [](#return-type).\n```\n\n![](img/automatic-header-link.png)\n\n#### Embedded Markdown within Code\n\nWithin default, `cpp`, `diff`, `nasm` and `rust` code elements, any text\nsurrounded by the `@` symbol is formatted as Markdown! This is useful for\nconventions such as _`see below`_, _`unspecified`_, and _exposition-only_\nvariable names.\n\n![](img/code-cpp.png)\n\nThis also works for inline code, e.g.,\n```markdown\nRecall the `static_cast`{.cpp} syntax: `static_cast \u003c @_type-id_@ \u003e ( @_expression_@ )`{.cpp}.\n```\n\n![](img/inline-code-cpp.png)\n\nIf you need to nest embedded Markdown, surround the outer context with `@@`.\nThis comes up sometimes if you want to produce inline diffs within a code block,\nand some of the inner code need to be marked up.\n\n``````markdown\n```\ntemplate \u003c@[`invocable`]{.rm}[`class`]{.add}@ F@[`, class`]{.add}@\u003e\nstruct @_as-receiver_@ {\n@[`private:`]{.rm}@\n  @[`using invocable_type = std::remove_cvref_t\u003cF\u003e;`]{.rm}@\n  @[`invocable_type`]{.rm}[`F`]{.add}@ f_;\n@[`public:`]{.rm}@\n  @@[`explicit @_as-receiver_@(invocable_type\u0026\u0026 f)`]{.rm}@@\n  @@[`@_as-receiver_@(@_as-receiver_@\u0026\u0026 other) = default;`]{.rm}@@\n  void set_value() @[`noexcept(is_nothrow_invocable_v\u003cF\u0026\u003e)`]{.add}@ {\n    invoke(f_);\n  }\n  @[`[[noreturn]]`]{.add}@ void set_error(std::exception_ptr) @[`noexcept`]{.add}@ {\n    terminate();\n  }\n  void set_done() noexcept {}\n};\n```\n``````\n\n![](img/nested-inline-code-cpp.png)\n\n### Comparison Tables\n\nComparison Tables are [fenced `Div` blocks][divspan] that open with `::: cmptable`\nand close with `:::`. [Fenced code blocks][code] are the only elements that\nactually get added to Comparison Tables, except that the last header (if any)\nbefore a [fenced code block][code] is attached to the cell above.\n\n``````md\n::: cmptable\n\n### Before\n```cpp\nswitch (x) {\n  case 0: std::cout \u003c\u003c \"got zero\"; break;\n  case 1: std::cout \u003c\u003c \"got one\"; break;\n  default: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n### After\n```cpp\ninspect (x) {\n  0: std::cout \u003c\u003c \"got zero\";\n  1: std::cout \u003c\u003c \"got one\";\n  _: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n:::\n``````\n\n[code]: https://pandoc.org/MANUAL.html#fenced-code-blocks\n[divspan]: https://pandoc.org/MANUAL.html#divs-and-spans\n\n![](img/cmptable-1.png)\n\nEach [fenced code block][code] is pushed onto the current row, and\nhorizontal rules (`---`) are used to move to the next row.\n\n``````md\n::: cmptable\n\n### Before\n```cpp\nswitch (x) {\n  case 0: std::cout \u003c\u003c \"got zero\"; break;\n  case 1: std::cout \u003c\u003c \"got one\"; break;\n  default: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n### After\n```cpp\ninspect (x) {\n  0: std::cout \u003c\u003c \"got zero\";\n  1: std::cout \u003c\u003c \"got one\";\n  _: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n---\n\n```cpp\nif (s == \"foo\") {\n  std::cout \u003c\u003c \"got foo\";\n} else if (s == \"bar\") {\n  std::cout \u003c\u003c \"got bar\";\n} else {\n  std::cout \u003c\u003c \"don't care\";\n}\n```\n\n```cpp\ninspect (s) {\n  \"foo\": std::cout \u003c\u003c \"got foo\";\n  \"bar\": std::cout \u003c\u003c \"got bar\";\n  _: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n:::\n``````\n\n![](img/cmptable-2.png)\n\nThe last block quote `\u003e caption` (if any) is used as the caption.\n\n``````md\n::: cmptable\n\n\u003e Put your caption here\n\n### Before\n```cpp\nswitch (x) {\n  case 0: std::cout \u003c\u003c \"got zero\"; break;\n  case 1: std::cout \u003c\u003c \"got one\"; break;\n  default: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n### After\n```cpp\ninspect (x) {\n  0: std::cout \u003c\u003c \"got zero\";\n  1: std::cout \u003c\u003c \"got one\";\n  _: std::cout \u003c\u003c \"don't care\";\n}\n```\n\n:::\n``````\n\n![](img/cmptable-3.png)\n\n### Proposed Wording\n\n#### Paragraph Numbers\n\nParagraph numbers are [bracketed `Span` elements][divspan] that look\nlike: `[2]{.pnum}` and `[2.1]{.pnum}`.\n\n```markdown\n[2]{.pnum} An expression is _potentially evaluated_ unless it is an unevaluated\noperand (7.2) or a subexpression thereof. The set of _potential results_ of\nan expression `e` is defined as follows:\n\n- [2.1]{.pnum} If `e` is an _id-expression_ (7.5.4), the set contains only `e`.\n- [2.2]{.pnum} If `e` is a subscripting operation (7.6.1.1) with an array operand,\nthe set contains the potential results of that operand.\n```\n\n![](img/pnum.png)\n\n#### Code Changes\n\n![](img/code-diff.png)\n\n#### Wording Changes\n\nLarge changes are [fenced `Div` blocks][divspan] with `::: add` for additions, `::: rm` for removals.\n\n![](img/wording-div.png)\n\nSmall, inline changes are [bracketed `Span` elements][divspan] that looks like\n`[new text]{.add}` or `[old text]{.rm}`.\n\n![](img/wording-span.png)\n\n#### Examples\n\nLarge examples are [fenced `Div` blocks][divspan] with `::: example`.\n\n``````markdown\n::: example\nA simple example of a class definition is\n\n```cpp\nstruct tnode {\n  char tword[20];\n  int count;\n  tnode* left;\n  tnode* right;\n};\n```\n:::\n``````\n\n![](img/example-div.png)\n\nSmaller, inline examples are [bracketed `Span` elements][divspan] that looks like `[example text]{.example}`.\n\n```markdown\n[`T x = T(T(T()));` value-initializes `x`.]{.example}\n```\n\n![](img/example-span.png)\n\n#### Notes\n\nLarge notes are [fenced `Div` blocks][divspan] with `::: note`.\n\n``````markdown\n::: note\nAn expression of type \"*cv1* `T`\" can initialize an object of type \"*cv2* `T`\"\nindependently of the cv-qualifiers *cv1* and *cv2*.\n\n```cpp\nint a;\nconst int b = a;\nint c = b;\n```\n:::\n``````\n\n![](img/note-div.png)\n\nSmaller, inline notes are [bracketed `Span` elements][divspan] that looks like `[note text]{.note}`.\n\n```markdown\n[Padding bits have unspecified value, but cannot cause traps.]{.note}\n```\n\n![](img/note-span.png)\n\nFor editorial notes, use `ednote`:\n\n```markdown\n::: ednote\nThroughout the wording, we say that a reflection (an object of type `std::meta::info`)\nrepresents some source construct, while splicing that reflection designates that source\nconstruct. For instance, `^^int` represents the type `int` and `[: ^^int :]` designates\nthe type `int`.\n:::\n```\n\n![](img/ednote-div.png)\n\n```markdown\n[This is a drive-by fix.]{.ednote}\n```\n\n![](img/ednote-span.png)\n\nFor drafting notes, use `draftnote`:\n\n```markdown\n::: draftnote\nWe don’t think we have to change anything here, since if `E` is a *splice-specifier*\nthat can be interpreted as a *splice-expression*, the requirements already fall out\nbased on how paragraphs 1 and 3 are already worded\n:::\n```\n\n![](img/draftnote-div.png)\n\n```markdown\n[An `audience` attribute addresses a specific audience]{.draftnote audience=\"the reader\"}\n```\n\n![](img/draftnote-span.png)\n\n\u003e To specify an audience for the [fenced `Div` block][divspan], you'll need `::: {.draftnote audience=\"the reader\"}`.\n\nFinally, in the relatively common situation where an example appears within a note, you can simply nest them:\n\n``````markdown\n::: note\nThe declaration of a class name takes effect immediately after the *identifier* is\nseen in the class definition or *elaborated-type-specifier*.\n\n::: example\n```cpp\nclass A * A;\n```\nfirst specifies `A` to be the name of a class and then redefines it as the name of a\npointer to an object of that class. This means that the elaborated form `class A` must be\nused to refer to the class. Such artistry with names can be confusing and is best avoided.\n:::\n:::\n``````\n\n![](img/note-example-nested.png)\n\n#### Grammar Changes\n\nUse [line blocks][lineblock] (`|`) in order to preserve the leading spaces.\n\n[lineblock]: https://pandoc.org/MANUAL.html#line-blocks\n\n```markdown\n\u003e | _selection-statement:_\n\u003e |     `if constexpr`_~opt~_ `(` _init-statement~opt~_ _condition_ `)` _statement_\n\u003e |     `if constexpr`_~opt~_ `(` _init-statement~opt~_ _condition_ `)` _statement_ `else` _statement_\n\u003e |     `switch (` _init-statement~opt~_ _condition_ `)` _statement_\n\u003e |     [`inspect` `constexpr`~_opt_~ `(` _init-statement~opt~_ _condition_ `)` `{`\n\u003e            _inspect-case-seq_\n\u003e        `}`]{.add}\n\u003e\n\u003e ::: add\n\u003e | _inspect-case-seq:_\n\u003e |     _inspect-case_\n\u003e |     _inspect-case-seq_ _inspect-case_\n\u003e\n\u003e | _inspect-case:_\n\u003e |     _attribute-specifier-seq~opt~_ _inspect-pattern_ _inspect-guard~opt~_ `:` _statement_\n\u003e\n\u003e | _inspect-pattern:_\n\u003e |     _wildcard-pattern_\n\u003e |     _identifier-pattern_\n\u003e |     _constant-pattern_\n\u003e |     _structured-binding-pattern_\n\u003e |     _alternative-pattern_\n\u003e |     _binding-pattern_\n\u003e |     _extractor-pattern_\n\u003e\n\u003e | _inspect-guard:_\n\u003e |     `if (` _expression_ `)`\n\u003e :::\n```\n\n![](img/grammar.png)\n\n### Stable Names\n\nStable names are [bracketed `Span` elements][divspan] that look like: `[stable.name]{.sref}`.\n\n```markdown\nIn [expr.sizeof]{.sref}/5:\n\nThe identifier in a `sizeof...` expression shall name a [parameter]{.rm} pack.\nThe `sizeof...` operator yields the number of [arguments provided for]{.rm}\n[elements in]{.add} the [parameter]{.rm} pack [identifier]{.rm} ([temp.variadic]{.sref}).\n```\n\n![](img/sref.png)\n\nYou can also add a class `-` or `.unnumbered` to omit the section number.\n\nFor example, `[expr.sizeof]{- .sref}` or `[expr.sizeof]{.unnumbered .sref}`\n\n\u003e Run `make update` to update the local cache of `annex-f`.\n\n### Citations\n\nIn-text citations look like this: `[@id]`\n\n![](img/citation.png)\n\nYou may also include the title of the paper like `[@P1240R2]{.title}` which generates:\n\n![](img/citetitle.png)\n\n### References\n\n#### Automatic References\n\nThe bibliography is automatically generated from \u003chttps://wg21.link/index.yaml\u003e\nfor citations of the following types.\n\n| Type              | Id                                                                            |\n| ----------------- | ----------------------------------------------------------------------------- |\n| Paper             | __N__*xxxx* / __P__*xxxx*__R__*n*                                             |\n| Issue             | __CWG__*xxxx* / __EWG__*xxxx* / __LWG__*xxxx* / __LEWG__*xxxx* / __FS__*xxxx* |\n| Editorial         | __EDIT__*xxx*                                                                 |\n| Standing Document | __SD__*x*                                                                     |\n\nThe `[@N3546]` example from [Citations](#citations) generates:\n\n![](img/automatic-reference.png)\n\n\u003e Run `make update` to update the local cache of `index.yaml`.\n\n#### Manual References\n\nManual references are specified in a YAML metadata block similar\nto [Title](#title), typically at the bottom of the document.\n\n```yaml\nThe `id` field is for in-text citations (e.g., [@PAT]),\nand `citation-label` is the label for the reference.\n\nTypically `id` and `citation-label` are kept the same.\n\n---\nreferences:\n  - id: PAT\n    citation-label: Patterns\n    title: \"Pattern Matching in C++\"\n    author:\n      - family: Park\n        given: Michael\n    URL: https://github.com/mpark/patterns\n---\n```\n\n![](img/manual-reference.png)\n\n### Unicode Considerations\n\nIf you build for LaTeX output and you have Unicode characters in any of\nyour paper's source code, you may have problems. First, the default PDF engine\nsimply does not support Unicode characters. You can add `--pdf-engine=xelatex`\nto the call to `pandoc` in the `Makefile` to use `xelatex` instead.\nThat gives you access to some font selections for different parts of your paper\n(see the [Fonts] section of the Pandoc manual). The option that controls your\nsource code fonts is `monofont`. You can add a line with your `monofont` choice\nto your YAML metadata block. Here, it's \"DejaVu Sans Mono\" which provides\nglyphs for a large amount of the Unicode characters:\n\n```yaml\n---\ntitle: Integration of chrono with text formatting\ndocument: P1361R0\ndate: 2018-10-16\naudience:\n  - Library Evolution Working Group\n  - Library Working Group\nauthor:\n  - name: Victor Zverovich\n    email: \u003cvictor.zverovich@gmail.com\u003e\n  - name: Daniela Engert\n    email: \u003cdani@ngrt.de\u003e\n  - name: Howard E. Hinnant\n    email: \u003choward.hinnant@gmail.com\u003e\nmonofont: \"DejaVu Sans Mono\"\n---\n```\n\nIf you want the list of available fonts on your system, most supported systems will produce a list via the command-line tool `fc-list`.\n\n[Fonts]: https://pandoc.org/MANUAL.html#fonts\n\n## Other Papers\n\n- [P1361]: Integration of chrono with text formatting\n- [P1390]: Suggested Reflection TS NB Resolutions\n\n[P1361]: https://wg21.link/p1361\n[P1390]: https://wg21.link/p1390\n\n## License\n\nDistributed under the [Boost Software License, Version 1.0](LICENSE.md).\n\n## Resources\n\n  - Blog Post: [How I format my C++ papers](https://mpark.github.io/programming/2018/11/16/how-i-format-my-cpp-papers)\n  - Lightning Talk @ C++Now 2019: [WG21 Paper in Markdown](https://www.youtube.com/watch?v=8yReHZOw6QY)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpark%2Fwg21","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmpark%2Fwg21","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpark%2Fwg21/lists"}