From c0a42fecabc7cb35173517fb182bbf4b03cb4799 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 19 Jun 2023 17:08:27 -0600 Subject: [PATCH 1/3] Specify our usage of ABNF for grammar --- meta/documentation_style.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 468b26753..0a8da2295 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](https://datatracker.ietf.org/doc/html/rfc5234) 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`). From 091b1758662ee535940d60f75fa27d2cd8beafdf Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 19 Jun 2023 17:09:19 -0600 Subject: [PATCH 2/3] Create 1582.clarification --- changelogs/internal/newsfragments/1582.clarification | 1 + 1 file changed, 1 insertion(+) 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 000000000..2f048a064 --- /dev/null +++ b/changelogs/internal/newsfragments/1582.clarification @@ -0,0 +1 @@ +Clarify usage of ABNF for grammar in the documentation style guide. From 1750a87192fd94b4bf4e906261cfd4e990cd86bd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 27 Jun 2023 16:35:22 -0600 Subject: [PATCH 3/3] Update meta/documentation_style.rst Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- meta/documentation_style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 0a8da2295..e7b714089 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -189,6 +189,6 @@ When a new subheading is added, it must be referenced and ordered in this docume Describing grammar ~~~~~~~~~~~~~~~~~~ -Use [RFC5234-style ABNF](https://datatracker.ietf.org/doc/html/rfc5234) when describing +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`).