doc/parsing.tex: Reorganize the parsing-syntax section.

Add some substructure and labels.  Promote `with-parser-context' to
first position.

I'm not sure this is completely right, but the previous situation was a
total mess.

diff --git a/doc/parsing.tex b/doc/parsing.tex
index cd0e12f4903f8be68682bebbb50b5470f8f82e47..c694ef88400a3f6276912e34a828c72d46a7a995 100644 (file)
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -542,7 +542,18 @@ file-location protocols.
 \end{describe}
 
 %%%--------------------------------------------------------------------------
 \end{describe}
 
 %%%--------------------------------------------------------------------------

-\section{Parsing syntax}
+\section{Parser contexts and parser syntax} \label{sec:parsing.syntax}
+
+
+\subsection{Parser contexts} \label{sec:parsing.syntax.contexts}
+
+\begin{describe}{mac}
+    {with-parser-context
+        (@<context-class> @{ @<init-keyword> @<value> @}^*)     \\ \ind
+      @<declaration>^*                                          \\
+      @<form>^*
+     \-\nlret @<value>^*}
+\end{describe}

 
 \begin{describe}{gf}{expand-parser-spec @<context> @<spec> @> @<form>}
 \end{describe}
 
 \begin{describe}{gf}{expand-parser-spec @<context> @<spec> @> @<form>}
 \end{describe}


@@ -562,14 +573,6 @@ file-location protocols.
      \-\nlret @<name>}
 \end{describe}
 
      \-\nlret @<name>}
 \end{describe}
 

-\begin{describe}{mac}
-    {with-parser-context
-        (@<context-class> @{ @<init-keyword> @<value> @}^*)     \\ \ind
-      @<declaration>^*                                          \\
-      @<form>^*
-     \-\nlret @<value>^*}
-\end{describe}
-

 \begin{describe}{lmac}
     {parse @<parser> @> @<result> @<success-flag> @<consumed-flag>}
 \end{describe}
 \begin{describe}{lmac}
     {parse @<parser> @> @<result> @<success-flag> @<consumed-flag>}
 \end{describe}


@@ -611,6 +614,9 @@ file-location protocols.
      \-\nlret @<value>^*}
 \end{describe}
 
      \-\nlret @<value>^*}
 \end{describe}
 

+
+\subsection{Basic parser syntax} \label{sec:parsing.syntax.basic}
+

 \begin{describe}{parse}{:eof}
 \end{describe}
 
 \begin{describe}{parse}{:eof}
 \end{describe}
 


@@ -686,6 +692,9 @@ file-location protocols.
       @<form>^*}
 \end{describe}
 
       @<form>^*}
 \end{describe}
 

+
+\subsection{Place-capture protocol} \label{sec:parsing.syntax.place}
+

 \begin{describe}{gf}{parser-capture-place @<context> @> @<form>}
 \end{describe}
 
 \begin{describe}{gf}{parser-capture-place @<context> @> @<form>}
 \end{describe}
 


@@ -711,6 +720,9 @@ file-location protocols.
 \begin{describe}{parseform}{commit}
 \end{describe}
 
 \begin{describe}{parseform}{commit}
 \end{describe}
 

+
+\subsection{Character parsers} \label{sec:parsing.syntax.character}
+

 \begin{describe}{cls}{character-parser-context () \&key}
 \end{describe}
 
 \begin{describe}{cls}{character-parser-context () \&key}
 \end{describe}
 


@@ -760,6 +772,9 @@ file-location protocols.
 \begin{describe}{parse}[atom]{@<atom>}
 \end{describe}
 
 \begin{describe}{parse}[atom]{@<atom>}
 \end{describe}
 

+
+\subsection{Scanner contexts} \label{sec:parsing.syntax.scanner}
+

 \begin{describe}{cls}{scanner-context () \&key :scanner}
 \end{describe}
 
 \begin{describe}{cls}{scanner-context () \&key :scanner}
 \end{describe}
 


@@ -776,6 +791,9 @@ file-location protocols.
       \&key :scanner}
 \end{describe}
 
       \&key :scanner}
 \end{describe}
 

+
+\subsection{Expression parsing} \label{sec:parsing.syntax.expression}
+

 \begin{describe}{gf}{push-operator @<operator> @<state>}
 \end{describe}
 
 \begin{describe}{gf}{push-operator @<operator> @<state>}
 \end{describe}
 


@@ -850,7 +868,7 @@ file-location protocols.
 \end{describe*}
 
 %%%-------------------------------------------------------------------------
 \end{describe*}
 
 %%%-------------------------------------------------------------------------

-\section{Lexical analyser}
+\section{Lexical analyser} \label{sec:parsing.lexical}

 
 \begin{describe}{cls}
     {sod-token-scanner (token-scanner)
 
 \begin{describe}{cls}
     {sod-token-scanner (token-scanner)