From: Mark Wooding <mdw@distorted.org.uk>
Date: Tue, 15 Dec 2015 19:15:23 +0000 (+0000)
Subject: doc/syntax.tex: Give the syntax chapter a little love.
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/commitdiff_plain/68a620ab55d7a8f5ba26a53ff2a0ba491cc2d25c

doc/syntax.tex: Give the syntax chapter a little love.
---

diff --git a/doc/syntax.tex b/doc/syntax.tex
index e084be2..aff02ab 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -26,6 +26,7 @@
 \chapter{Module syntax} \label{ch:syntax}
 
 %%%--------------------------------------------------------------------------
+\section{Notation} \label{sec:syntax.notation}
 
 Fortunately, Sod is syntactically quite simple.  The notation is slightly
 unusual in order to make the presentation shorter and easier to read.
@@ -69,8 +70,8 @@ enough that they deserve special notation.
   \end{quote}
 \end{itemize}
 
-\subsection{Lexical syntax}
-\label{sec:syntax.lex}
+%%%--------------------------------------------------------------------------
+\section{Lexical syntax} \label{sec:syntax.lex}
 
 Whitespace and comments are discarded.  The remaining characters are
 collected into tokens according to the following syntax.
@@ -87,7 +88,8 @@ This syntax is slightly ambiguous, and is disambiguated by the \emph{maximal
 munch} rule: at each stage we take the longest sequence of characters which
 could be a token.
 
-\subsubsection{Identifiers} \label{sec:syntax.lex.id}
+
+\subsection{Identifiers} \label{sec:syntax.lex.id}
 
 \begin{grammar}
 <identifier> ::= <id-start-char> @<id-body-char>^*
@@ -115,7 +117,8 @@ also an ambiguity (inherited from C) in the declaration syntax which is
 settled by distinguishing type names from other identifiers at a lexical
 level.
 
-\subsubsection{String and character literals} \label{sec:syntax.lex.string}
+
+\subsection{String and character literals} \label{sec:syntax.lex.string}
 
 \begin{grammar}
 <string-literal> ::= "\"" @<string-literal-char>^* "\""
@@ -167,13 +170,15 @@ Sod understands only integers, not floating-point numbers; its integer syntax
 goes slightly beyond C in allowing a @`0o' prefix for octal and @`0b' for
 binary.  However, length and signedness indicators are not permitted.
 
-\subsubsection{Punctuation} \label{sec:syntax.lex.punct}
+
+\subsection{Punctuation} \label{sec:syntax.lex.punct}
 
 \begin{grammar}
 <punctuation> ::= any nonalphanumeric character other than "_", "\"" or "'"
 \end{grammar}
 
-\subsubsection{Comments} \label{sec:lex-comment}
+
+\subsection{Comments} \label{sec:syntax.lex.comment}
 
 \begin{grammar}
 <comment> ::= <block-comment>
@@ -202,26 +207,24 @@ Comments are exactly as in C99: both traditional block comments `\texttt{/*}
 \dots\ \texttt{*/}' and \Cplusplus-style `\texttt{//} \dots' comments are
 permitted and ignored.
 
-\subsection{Special nonterminals}
-\label{sec:special-nonterminals}
+
+\subsection{Special nonterminals} \label{sec:syntax.lex.special}
 
 Aside from the lexical syntax presented above (\xref{sec:lexical-syntax}),
 two special nonterminals occur in the module syntax.
 
-\subsubsection{S-expressions} \label{sec:syntax-sexp}
-
+\subsubsection{S-expressions}
 \begin{grammar}
 <s-expression> ::= an S-expression, as parsed by the Lisp reader
 \end{grammar}
 
 When an S-expression is expected, the Sod parser simply calls the host Lisp
-system's \textsf{read} function.  Sod modules are permitted to modify the
-read table to extend the S-expression syntax.
+system's @|read| function.  Sod modules are permitted to modify the read
+table to extend the S-expression syntax.
 
 S-expressions are self-delimiting, so no end-marker is needed.
 
-\subsubsection{C fragments} \label{sec:syntax.lex.cfrag}
-
+\subsubsection{C fragments}
 \begin{grammar}
 <c-fragment> ::= a sequence of C tokens, with matching brackets
 \end{grammar}
@@ -235,7 +238,8 @@ determined by the immediately surrounding context -- usually a closing brace
 or bracket.  The first such delimiter character which is not enclosed in
 brackets, braces or parenthesis ends the fragment.
 
-\subsection{Module syntax} \label{sec:syntax-module}
+%%%--------------------------------------------------------------------------
+\section{Module syntax} \label{sec:syntax.module}
 
 \begin{grammar}
 <module> ::= @<definition>^*
@@ -248,13 +252,12 @@ brackets, braces or parenthesis ends the fragment.
 \alt <class-definition>
 \end{grammar}
 
-A module is the top-level syntactic item.  A module consists of a sequence of
-definitions.
+A @<module> is the top-level syntactic item.  A module consists of a sequence
+of definitions.
 
-\subsection{Simple definitions} \label{sec:syntax.defs}
-
-\subsubsection{Importing modules} \label{sec:syntax.defs.import}
+\subsection{Simple definitions} \label{sec:syntax.module.simple}
 
+\subsubsection{Importing modules}
 \begin{grammar}
 <import-definition> ::= "import" <string> ";"
 \end{grammar}
@@ -283,8 +286,7 @@ happens.\footnote{%
 
 Recursive imports, either direct or indirect, are an error.
 
-\subsubsection{Loading extensions} \label{sec:syntax.defs.load}
-
+\subsubsection{Loading extensions}
 \begin{grammar}
 <load-definition> ::= "load" <string> ";"
 \end{grammar}
@@ -318,8 +320,7 @@ which will arrange for the extension to be compiled if necessary.
 particular system definition facility.  It's bad enough already that it
 depends on Common Lisp.)
 
-\subsubsection{Lisp escapes} \label{sec:syntax.defs.lisp}
-
+\subsubsection{Lisp escapes}
 \begin{grammar}
 <lisp-definition> ::= "lisp" <s-expression> ";"
 \end{grammar}
@@ -334,8 +335,7 @@ The @<s-expression> is evaluated immediately.  It can do anything it likes.
     this isn't as unusually scary as it sounds.  But please be careful.} %
 \end{boxy}
 
-\subsubsection{Declaring type names} \label{sec:syntax.defs.typename}
-
+\subsubsection{Declaring type names}
 \begin{grammar}
 <typename-definition> ::=
   "typename" <list>$[\mbox{@<identifier>}]$ ";"
@@ -348,7 +348,8 @@ done by distinguishing type names from other identifiers.
 Don't declare class names using @"typename"; use @"class" forward
 declarations instead.
 
-\subsection{Literal code} \label{sec:syntax-code}
+
+\subsection{Literal code} \label{sec:syntax.module.literal}
 
 \begin{grammar}
 <code-definition> ::=
@@ -384,8 +385,8 @@ output files which is a suitable place for inserting @"\#include"
 preprocessor directives in order to declare types and functions for use
 elsewhere in the generated output files.
 
-\subsection{Property sets} \label{sec:syntax.propset}
 
+\subsection{Property sets} \label{sec:syntax.module.properties}
 \begin{grammar}
 <properties> ::= "[" <list>$[\mbox{@<property>}]$ "]"
 
@@ -401,8 +402,7 @@ A property has a name, given as an @<identifier>, and a value computed by
 evaluating an @<expression>.  The value can be one of a number of types,
 though the only operators currently defined act on integer values only.
 
-\subsubsection{The expression evaluator} \label{sec:syntax.propset.expr}
-
+\subsubsection{The expression evaluator}
 \begin{grammar}
 <expression> ::= <term> | <expression> "+" <term> | <expression> "-" <term>
 
@@ -429,7 +429,8 @@ causes the @<s-expression> to be evaluated using the Lisp \textsf{eval}
 function.
 %%% FIXME crossref to extension docs
 
-\subsection{C types} \label{sec:syntax.c-types}
+
+\subsection{C types} \label{sec:syntax.module.types}
 
 Sod's syntax for C types closely mirrors the standard C syntax.  A C type has
 two parts: a sequence of @<declaration-specifier>s and a @<declarator>.  In
@@ -437,8 +438,7 @@ Sod, a type must contain at least one @<declaration-specifier> (i.e.,
 `implicit @"int"' is forbidden), and storage-class specifiers are not
 recognized.
 
-\subsubsection{Declaration specifiers} \label{sec:syntax.c-types.declspec}
-
+\subsubsection{Declaration specifiers}
 \begin{grammar}
 <declaration-specifier> ::= <type-name>
 \alt "struct" <identifier> | "union" <identifier> | "enum" <identifier>
@@ -488,7 +488,7 @@ more @<qualifiers>, and one of the following, up to reordering.
 \end{itemize}
 All of these have their usual C meanings.
 
-\subsubsection{Declarators} \label{sec:syntax.c-types.declarator}
+\subsubsection{Declarators}
 \begin{grammar}
 <declarator>$[k]$ ::= @<pointer>^* <primary-declarator>$[k]$
 
@@ -525,14 +525,15 @@ The declarator syntax is taken from C, but with some differences.
 The remaining differences are (I hope) a matter of presentation rather than
 substance.
 
-\subsection{Defining classes} \label{sec:syntax.class}
+
+\subsection{Class definitions} \label{sec:syntax.module.class}
 
 \begin{grammar}
 <class-definition> ::= <class-forward-declaration>
 \alt <full-class-definition>
 \end{grammar}
 
-\subsubsection{Forward declarations} \label{sec:class.class.forward}
+\subsubsection{Forward declarations}
 \begin{grammar}
 <class-forward-declaration> ::= "class" <identifier> ";"
 \end{grammar}
@@ -552,8 +553,7 @@ class Sub : Super {
 };
 \end{listing}
 
-\subsubsection{Full class definitions} \label{sec:class.class.full}
-
+\subsubsection{Full class definitions}
 \begin{grammar}
 <full-class-definition> ::=
   @[<properties>@]
@@ -602,8 +602,7 @@ properties are as follows.
 The class body consists of a sequence of @<class-item>s enclosed in braces.
 These items are discussed on the following sections.
 
-\subsubsection{Slot items} \label{sec:sntax.class.slot}
-
+\subsubsection{Slot items}
 \begin{grammar}
 <slot-item> ::=
   @<declaration-specifier>^+ <list>$[\mbox{@<init-declarator>}]$ ";"
@@ -638,8 +637,7 @@ class Example : Super {
 };
 \end{listing}
 
-\subsubsection{Initializer items} \label{sec:syntax.class.init}
-
+\subsubsection{Initializer items}
 \begin{grammar}
 <initializer-item> ::= @["class"@] <list>$[\mbox{@<slot-initializer>}]$ ";"
 
@@ -666,8 +664,7 @@ The initializer has one of two forms.
   slots, such as pointers or integers, and strings.
 \end{itemize}
 
-\subsubsection{Message items} \label{sec:syntax.class.message}
-
+\subsubsection{Message items}
 \begin{grammar}
 <message-item> ::=
   @<declaration-specifier>^+
@@ -675,8 +672,7 @@ The initializer has one of two forms.
   @[<method-body>@]
 \end{grammar}
 
-\subsubsection{Method items} \label{sec:syntax.class.method}
-
+\subsubsection{Method items}
 \begin{grammar}
 <method-item> ::=
   @<declaration-specifier>^+