From 903b206e3b37222d7de5ba19bce3f16c3f614f02 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Jun 2023 08:11:28 -0600 Subject: [PATCH] Specify our usage of ABNF for grammar (#1582) * Specify our usage of ABNF for grammar * Create 1582.clarification * Update meta/documentation_style.rst Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- changelogs/internal/newsfragments/1582.clarification | 1 + meta/documentation_style.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelogs/internal/newsfragments/1582.clarification diff --git a/changelogs/internal/newsfragments/1582.clarification b/changelogs/internal/newsfragments/1582.clarification new file mode 100644 index 00000000..2f048a06 --- /dev/null +++ b/changelogs/internal/newsfragments/1582.clarification @@ -0,0 +1 @@ +Clarify usage of ABNF for grammar in the documentation style guide. diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 468b2675..e7b71408 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -185,3 +185,10 @@ The subheadings which are always deemed as client-affecting are: * Redactions When a new subheading is added, it must be referenced and ordered in this document. + +Describing grammar +~~~~~~~~~~~~~~~~~~ + +Use `RFC5234-style ABNF `_ when describing +the grammar for something in the spec, such as user IDs or server names. Use lowercase +and underscore-deliminated element names (`user_id`, not `UserID` or `user-id`).