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 <[email protected]> --------- Co-authored-by: Richard van der Hoff <[email protected]>
matrix-org · Jun 28, 2023 · 903b206 · 903b206
1 parent b2ab339
commit 903b206
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 0 deletions.
diff --git a/changelogs/internal/newsfragments/1582.clarification 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
@@ -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`).