From 62286c1d8e105c07e5cf1903d92e000da5efbb72 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 4 Sep 2025 12:05:36 -0500 Subject: [PATCH 1/4] Link out to the notation from grammar summary As a reference, users are likely to jump in at random points and it can then be hard to know where to look for information on grammars. While it would likely be overkill to link to the notation wherever there is a grammar, the grammary summary page seems like a reasonable place to at least include a link. --- src/grammar.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/grammar.md b/src/grammar.md index fa7ca7819..aacc77bee 100644 --- a/src/grammar.md +++ b/src/grammar.md @@ -1,5 +1,7 @@ # Grammar summary -The following is a summary of the grammar production rules. +The following is a summary of the [grammar production rules]. {{ grammar-summary }} + +[grammar production rules]: notation.md From fd704094f4052c1f0b0bc5659473ec095ca182f0 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 4 Sep 2025 21:49:56 +0000 Subject: [PATCH 2/4] Add rule identifiers to notation chapter We originally hadn't added rule identifiers to the notation chapter as in some sense these aren't language rules. However, as it turns out, it's still useful to have these so as to be able to refer by name to particular sections. And anyway, since the language rules are defined in terms of this notation, the notation rules are in a sense normative at a meta level. In doing this, we'll nest certain sections under the grammar section that should be so nested. --- src/notation.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/notation.md b/src/notation.md index de262423c..4374bf490 100644 --- a/src/notation.md +++ b/src/notation.md @@ -1,7 +1,11 @@ +r[notation] # Notation +r[notation.grammar] ## Grammar +r[notation.grammar.syntax] + The following notations are used by the *Lexer* and *Syntax* grammar snippets: | Notation | Examples | Meaning | @@ -26,7 +30,8 @@ The following notations are used by the *Lexer* and *Syntax* grammar snippets: Sequences have a higher precedence than `|` alternation. -## String table productions +r[notation.grammar.string-tables] +### String table productions Some rules in the grammar — notably [unary operators], [binary operators], and [keywords] — are given in a simplified form: as a listing @@ -40,13 +45,15 @@ When such a string in `monospace` font occurs inside the grammar, it is an implicit reference to a single member of such a string table production. See [tokens] for more information. -## Grammar visualizations +r[notation.grammar.visualizations] +### Grammar visualizations Below each grammar block is a button to toggle the display of a [syntax diagram]. A square element is a non-terminal rule, and a rounded rectangle is a terminal. [syntax diagram]: https://en.wikipedia.org/wiki/Syntax_diagram -## Common productions +r[notation.grammar.common] +### Common productions The following are common definitions used in the grammar. From 25a4588f2d62f020d87bea1298472e7463d2684a Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 5 Sep 2025 19:40:20 +0000 Subject: [PATCH 3/4] Move `input.syntax` to the corresponding chapter We had a set of grammar rules we had placed in the notation chapter under the label of "common productions". There's a certain sense to that, particularly if we had more of them. As it is, though, all of the productions seem related enough to the "input format" chapter, and in fact we had already labeled these productions with the identifier `input.syntax`, so let's go ahead and move these productions to the "input format" chapter. This looks more orderly, especially as we now have rule labels in the notation chapter. --- src/input-format.md | 13 +++++++++++++ src/notation.md | 21 +-------------------- 2 files changed, 14 insertions(+), 20 deletions(-) diff --git a/src/input-format.md b/src/input-format.md index afdf8ac37..5d2a69275 100644 --- a/src/input-format.md +++ b/src/input-format.md @@ -1,6 +1,19 @@ r[input] # Input format +r[input.syntax] +```grammar,lexer +@root CHAR -> + +NUL -> U+0000 + +TAB -> U+0009 + +LF -> U+000A + +CR -> U+000D +``` + r[input.intro] This chapter describes how a source file is interpreted as a sequence of tokens. diff --git a/src/notation.md b/src/notation.md index 4374bf490..b4954d42c 100644 --- a/src/notation.md +++ b/src/notation.md @@ -50,27 +50,8 @@ r[notation.grammar.visualizations] Below each grammar block is a button to toggle the display of a [syntax diagram]. A square element is a non-terminal rule, and a rounded rectangle is a terminal. -[syntax diagram]: https://en.wikipedia.org/wiki/Syntax_diagram - -r[notation.grammar.common] -### Common productions - -The following are common definitions used in the grammar. - -r[input.syntax] -```grammar,lexer -@root CHAR -> - -NUL -> U+0000 - -TAB -> U+0009 - -LF -> U+000A - -CR -> U+000D -``` - [binary operators]: expressions/operator-expr.md#arithmetic-and-logical-binary-operators [keywords]: keywords.md +[syntax diagram]: https://en.wikipedia.org/wiki/Syntax_diagram [tokens]: tokens.md [unary operators]: expressions/operator-expr.md#borrow-operators From 7da73b22796258bd70991344851f3455d507c9e4 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 5 Sep 2025 19:49:05 +0000 Subject: [PATCH 4/4] Revise link to grammar syntax in grammar summary The notation itself is not the "grammar production rules", so we don't want to use that as the link text. Let's instead point people to the rule identifier by name. --- src/grammar.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/grammar.md b/src/grammar.md index aacc77bee..e27d73936 100644 --- a/src/grammar.md +++ b/src/grammar.md @@ -1,7 +1,5 @@ # Grammar summary -The following is a summary of the [grammar production rules]. +The following is a summary of the grammar production rules. For details on the syntax of this grammar, see *[notation.grammar.syntax]*. {{ grammar-summary }} - -[grammar production rules]: notation.md