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

diff --git a/doc/syntax.tex b/doc/syntax.tex
index e084be2421feff805cc9838201cd97e74cd2aa28..aff02abc23dc4060a1bff95270a872ad2d6a4558 100644 (file)
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -26,6 +26,7 @@
 \chapter{Module syntax} \label{ch:syntax}
 
 %%%--------------------------------------------------------------------------
 \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.
 
 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}
 
   \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.
 
 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.
 
 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>^*
 
 \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.
 
 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>^* "\""
 
 \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.
 
 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}
 
 
 \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>
 
 \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.
 
 \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.
 
 
 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
 \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.
 
 
 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}
 \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.
 
 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>^*
 
 \begin{grammar}
 <module> ::= @<definition>^*


@@ -248,13 +252,12 @@ brackets, braces or parenthesis ends the fragment.
 \alt <class-definition>
 \end{grammar}
 
 \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}
 \begin{grammar}
 <import-definition> ::= "import" <string> ";"
 \end{grammar}


@@ -283,8 +286,7 @@ happens.\footnote{%
 
 Recursive imports, either direct or indirect, are an error.
 
 
 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}
 \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.)
 
 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}
 \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}
 
     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>}]$ ";"
 \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.
 
 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> ::=
 
 \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.
 
 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>}]$ "]"
 
 \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.
 
 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>
 
 \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
 
 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
 
 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.
 
 `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>
 \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.
 
 \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]$
 
 \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.
 
 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}
 
 
 \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}
 \begin{grammar}
 <class-forward-declaration> ::= "class" <identifier> ";"
 \end{grammar}


@@ -552,8 +553,7 @@ class Sub : Super {
 };
 \end{listing}
 
 };
 \end{listing}
 

-\subsubsection{Full class definitions} \label{sec:class.class.full}
-
+\subsubsection{Full class definitions}

 \begin{grammar}
 <full-class-definition> ::=
   @[<properties>@]
 \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.
 
 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>}]$ ";"
 \begin{grammar}
 <slot-item> ::=
   @<declaration-specifier>^+ <list>$[\mbox{@<init-declarator>}]$ ";"


@@ -638,8 +637,7 @@ class Example : Super {
 };
 \end{listing}
 
 };
 \end{listing}
 

-\subsubsection{Initializer items} \label{sec:syntax.class.init}
-
+\subsubsection{Initializer items}

 \begin{grammar}
 <initializer-item> ::= @["class"@] <list>$[\mbox{@<slot-initializer>}]$ ";"
 
 \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}
 
   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>^+
 \begin{grammar}
 <message-item> ::=
   @<declaration-specifier>^+


@@ -675,8 +672,7 @@ The initializer has one of two forms.
   @[<method-body>@]
 \end{grammar}
 
   @[<method-body>@]
 \end{grammar}
 

-\subsubsection{Method items} \label{sec:syntax.class.method}
-
+\subsubsection{Method items}

 \begin{grammar}
 <method-item> ::=
   @<declaration-specifier>^+
 \begin{grammar}
 <method-item> ::=
   @<declaration-specifier>^+