From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 24 Aug 2019 16:14:51 +0000 (+0100)
Subject: doc/...: Fix `\textbar' properly, and use plain `|'.
X-Git-Url: https://git.distorted.org.uk/~mdw/sod/commitdiff_plain/b04739d01153eb539fd6b05095368e60b0d32bf6

doc/...: Fix `\textbar' properly, and use plain `|'.

The `\grammar' command wasn't the right place to hack this, since
`\syntax' also needs fixing.  Instead, patch `\syn@shorts' to do the
right thing.

Once this is done, use `|' rather than `@|' in syntax displays (not the
Lisp ones!).  Also, use text rather than maths spacing consistently, by
replacing `$| \cdots |$' with `| $\cdots$ |' throughout.
---

diff --git a/doc/refintro.tex b/doc/refintro.tex
index 349f7b0..6f3938a 100644
--- a/doc/refintro.tex
+++ b/doc/refintro.tex
@@ -104,7 +104,7 @@ The letter $\epsilon$ denotes the empty nonterminal
 Parentheses are used for grouping of alternatives within the right-hand side
 of a production rule.  Specifically, a right-hand side
 \begin{quote}
-  \syntax{$\alpha$ @($\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$@) $\gamma$}
+  \syntax{$\alpha$ @($\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@) $\gamma$}
 \end{quote}
 where $\alpha$, $\beta_i$, and $\gamma$ are any sequence of nonterminal
 symbols or parenthesized groups, is equivalent to the right-hand side
@@ -113,13 +113,13 @@ symbols or parenthesized groups, is equivalent to the right-hand side
 \end{quote}
 together with the new production
 \begin{quote}
-  \syntax{$b$ ::= $\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$}
+  \syntax{$b$ ::= $\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$}
 \end{quote}
 where $b$ is a new nonterminal symbol.
 
 Given the indexed-nonterminal notation described below, one might consider a
-group \syntax{@($\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$@)} equivalent
-to \syntax{<group>@[$\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$@]}, where
+group \syntax{@($\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@)} equivalent to
+\syntax{<group>@[$\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@]}, where
 \begin{quote}
   \syntax{<group>@[$x$@] ::= $x$}
 \end{quote}
@@ -139,14 +139,14 @@ As a notational convenience, where an indexed nonterminal appears on the
 right-hand side of a production rule, each actual argument may be a sequence
 of alternative right-hand sides, separated by `$|$', rather than a a simple
 terminal or nonterminal symbol.  A complex indexing of this form, say
-\syntax{$x$@[$\alpha_1^1$ @! $\alpha_1^2$ $| \cdots |$ $\alpha_1^{m_1},
-\ldots,$ $\alpha_n^1$ @! $\alpha_n^2$ $| \cdots |$ $\alpha_n^{m_n}$@]}
-means exactly the same as \syntax{$x$@[$a_1, \ldots, a_n$@]} with the
-additional rules
+\syntax{$x$@[$\alpha_1^1$ | $\alpha_1^2$ | $\cdots$ | $\alpha_1^{m_1},
+\ldots,$ $\alpha_n^1$ | $\alpha_n^2$ | $\cdots$ | $\alpha_n^{m_n}$@]} means
+exactly the same as \syntax{$x$@[$a_1, \ldots, a_n$@]} with the additional
+rules
 \begin{quote}
-  \syntax{$a_1$ ::= $\alpha_1^1$ @! $\alpha_1^2$ $| \cdots |$ $\alpha_1^{m_1}$} \\*
+  \syntax{$a_1$ ::= $\alpha_1^1$ | $\alpha_1^2$ | $\cdots$ | $\alpha_1^{m_1}$} \\*
   \hbox{}\qquad $\vdots$ \\*
-  \syntax{$a_n$ ::= $\alpha_n^1$ @! $\alpha_n^2$ $| \cdots |$ $\alpha_1^{m_n}$}
+  \syntax{$a_n$ ::= $\alpha_n^1$ | $\alpha_n^2$ | $\cdots$ | $\alpha_1^{m_n}$}
 \end{quote}
 where $a_1$, \ldots, $a_n$ are new nonterminal symbols.
 
@@ -159,13 +159,13 @@ enough that they deserve special notation.
 \item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
   of $x$:
   \begin{quote}
-    \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$}
+    \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ | $x$}
   \end{quote}
 \item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
   more occurrences of $x$:
   \begin{quote}
     \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
-      $\epsilon$ @! <zero-or-more>$[x]$ $x$}
+      $\epsilon$ | <zero-or-more>$[x]$ $x$}
   \end{quote}
 \item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of one or
   more occurrences of $x$:
@@ -175,7 +175,7 @@ enough that they deserve special notation.
 \item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
   separated by commas:
   \begin{quote}
-    \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$}
+    \syntax{<list>$[x]$ ::= $x$ | <list>$[x]$ "," $x$}
   \end{quote}
 \end{itemize}
 
diff --git a/doc/sod.sty b/doc/sod.sty
index eacd977..9da7def 100644
--- a/doc/sod.sty
+++ b/doc/sod.sty
@@ -106,8 +106,8 @@
 
 %% Intercept grammar typesetting and replace the vertical bar with the
 %% maths-font version.
-\let\@@grammar\grammar
-\def\grammar{\def\textbar{\hbox{$|$}}\@@grammar}
+\let\@@syn@shorts\syn@shorts
+\def\syn@shorts{\def\textbar{\hbox{$|$}}\@@syn@shorts}
 
 %% Collect super- and subscripts.  (Note that underscores are active for the
 %% most part.)  When we're done, end maths mode if we entered it
diff --git a/doc/syntax.tex b/doc/syntax.tex
index 8c66487..dd6a5f5 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -51,15 +51,15 @@ could be a token.
 
 <id-start-char> ::= <alpha-char> | "_"
 
-<id-body-char> ::= <id-start-char> @! <digit-char>
+<id-body-char> ::= <id-start-char> | <digit-char>
 
-<alpha-char> ::= "A" | "B" $| \cdots |$ "Z"
-  | "a" | "b" $| \cdots |$ "z"
+<alpha-char> ::= "A" | "B" | $\cdots$ | "Z"
+  | "a" | "b" | $\cdots$ | "z"
   | <extended-alpha-char>
 
 <digit-char> ::= "0" | <nonzero-digit-char>
 
-<nonzero-digit-char> ::= "1" | "2" $| \cdots |$ "9"
+<nonzero-digit-char> ::= "1" | "2" | $\cdots$ | "9"
 \end{grammar}
 
 The precise definition of @<alpha-char> is left to the function
@@ -107,15 +107,15 @@ discouraged.
 
 <decimal-integer> ::= "0" | <nonzero-digit-char> @<digit-char>^*
 
-<binary-integer> ::= "0" @("b" @! "B"@) @<binary-digit-char>^+
+<binary-integer> ::= "0" @("b" | "B"@) @<binary-digit-char>^+
 
 <binary-digit-char> ::= "0" | "1"
 
-<octal-integer> ::= "0" @["o" @! "O"@] @<octal-digit-char>^+
+<octal-integer> ::= "0" @["o" | "O"@] @<octal-digit-char>^+
 
-<octal-digit-char> ::= "0" | "1" $| \cdots |$ "7"
+<octal-digit-char> ::= "0" | "1" | $\cdots$ | "7"
 
-<hex-integer> ::= "0" @("x" @! "X"@) @<hex-digit-char>^+
+<hex-integer> ::= "0" @("x" | "X"@) @<hex-digit-char>^+
 
 <hex-digit-char> ::= <digit-char>
   | "A" | "B" | "C" | "D" | "E" | "F"
@@ -324,7 +324,7 @@ defined in the built-in module.
 <abstract-declarator> ::= <declarator>$[\epsilon, \mbox{@<argument-list>}]$
 
 <argument-declarator> ::=
-  <declarator>$[\mbox{@<identifier> @! $\epsilon$}, \mbox{@<argument-list>}]$
+  <declarator>$[\mbox{@<identifier> | $\epsilon$}, \mbox{@<argument-list>}]$
 
 <simple-declarator> ::=
   <declarator>$[\mbox{@<identifier>}, \mbox{@<argument-list>}]$
@@ -352,7 +352,7 @@ keyword arguments.
   @[<list>$[\mbox{@<argument>}]$@]
   "?" @[<list>$[\mbox{@<keyword-argument>}]$@]
 
-<method-argument-list> ::= <argument-list> @! <keyword-argument-list>
+<method-argument-list> ::= <argument-list> | <keyword-argument-list>
 
 <dotted-name> ::= <identifier> "." <identifier>
 
@@ -681,7 +681,7 @@ declarations instead.
 
 <constraint> ::= @<item-name>^+
 
-<item-name> ::= <identifier> @! "(" @<identifier>^+ ")"
+<item-name> ::= <identifier> | "(" @<identifier>^+ ")"
 \end{grammar}
 
 The @<c-fragment> will be output unchanged to one of the output files.