build: Use ACLTX_TEXMF_PATH for installation.

[mdwtools] / syntax.dtx

% \begin{meta-comment}
%
% syntax.dtx
%
% Syntax typesetting package for LaTeX 2e
%
% (c) 2003 Mark Wooding
%
% \end{meta-comment}
%
% \begin{meta-comment} <general public licence>
%%
%% syntax package -- typesetting syntax descriptions
%% Copyright (c) 2003 Mark Wooding
%%
%% This program is free software; you can redistribute it and/or modify
%% it under the terms of the GNU General Public License as published by
%% the Free Software Foundation; either version 2 of the License, or
%% (at your option) any later version.
%%
%% This program is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%% GNU General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%%
% \end{meta-comment}
%
% \begin{meta-comment} <Package preamble>
%<+package>\NeedsTeXFormat{LaTeX2e}
%<+package>\ProvidesPackage{syntax}
%<+package>                [2003/08/25 1.08 Syntax typesetting (MDW)]
% \end{meta-comment}
%
% \CheckSum{1616}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
% \begin{meta-comment} <driver>
%
%<*driver>
%
% This hacking will remember the old default underscore character.  Even if
% T1 fonts are being used, it will get the grotty version.  Why is it that
% all of the encoding handling ends up looking like this?
%
\expandafter\let\expandafter\oldus\csname?\string\textunderscore\endcsname
%
\input{mdwtools}
\describespackage{syntax}
\DeclareRobustCommand\syn{\package{syntax}}
\mdwdoc
%</driver>
%
% \end{meta-comment}
%
% \section{User guide}
%
% \subsection{Introduction}
%
% The \syn\ package provides a number of commands and environments which
% extend \LaTeX\ and allow you to typeset good expositions of syntax.
%
% The package provides several different types of features: probably not all
% of these will be required by every document which needs the package:
% \begin{itemize}
% \item A system of abbreviated forms for typesetting syntactic items.
% \item An environment for typesetting BNF-type grammars
% \item A collection of environments for building syntax diagrams.
% \end{itemize}
%
% The package also includes some other features which, while not necessarily
% syntax-related, will probably come in handy for similar types of document:
% \begin{itemize}
% \item An abbreviated notation for verbatim text, similar to the
%       \package{shortvrb} package.
% \item A slightly different underscore character, which works as expected
%       in text and maths modes.
% \end{itemize}
%
% \subsection{The abbreviated verbatim notation}
%
% In documents describing programming languages and libraries, it can become
% tedious to type "\verb|...|" every time.  Like Frank Mittelbach's
% \package{shortvrb} package, \syn\ provides a way of setting up single-^^A
% character abbreviations.  The only real difference between the two is that
% the declarations provided by \syn\ obey \LaTeX's normal scoping rules.
%
% \DescribeMacro\shortverb
% You can set up a character as a `verbatim shorthand' character using the
% |\shortverb| command.  This takes a single argument, which should be a
% single-character control sequence containing the character you want to use.
% So, for example, the command
% \begin{listing}
%\shortverb{\|}
% \end{listing}
% would set up the `"|"' character to act as a verbatim delimiter.  While a
% |\shortverb| declaration is in force, any text surrounded by (in this case)
% vertical bar characters will be typeset as if using the normal |\verb|
% command.
%
% \DescribeEnv{shortverb}
% Since \LaTeX\ allows any declaration to be used as an environment, you can
% use a \env{shortverb} environment to delimit the text over which your
% character is active:
% \begin{listing}
%Some text...
%\begin{shortverb}{\|}
%...
%\end{shortverb}
% \end{listing}
%
% \DescribeMacro\unverb
% If you want to disable a |\shortverb| character without ending the scope
% of other declarations, you can use the |\unverb| command, passing it
% a character as a control sequence, in the same way as above.
%
% The default \TeX/\LaTeX\ underscore character is rather too short for
% use in identifiers.  For example:
%
% \begingroup \let\_=\oldus
% \begin{demo}{Old-style underscores}
%Typing long underscore-filled
%names, like big\_function\_name,
%is normally tedious.  The normal
%positioning of the underscore
%is wrong, too.
% \end{demo}
% \endgroup
%
% The \syn\ package redefines the |\_| command to draw a more attractive
% underscore character.  It also allows you to use the |_|~character
% directly to produce an underscore outside of maths mode: |_|~behaves
% as a subscript character as usual inside maths mode.
%
% \begin{demo}{New \syn\ underscores}
%You can use underscore-filled
%names, like big_function_name,
%simply and naturally.  Of
%course, subscripts still work
%normally in maths mode, e.g.,
%$x_i$.
% \end{demo}
%
% \subsection{Typesetting syntactic items}
% \begin{synshorts}
%
% The \syn\ package provides some simple commands for typesetting syntactic
% items.
%
% \DescribeMacro\synt
% Typing "\\synt{"<text>"}" typesets <text> as a \lq non-terminal',
% in italics and surrounded by angle brackets.  If you use "\\synt" a lot,
% you can use the incantation
% \begin{listing}
%\def\<#1>{\synt{#1}}
% \end{listing}
% to allow you to type "\\<"<text>">" as an alternative to 
% "\\synt{"<text>"}".
%
% \DescribeMacro\lit
% You can also display literal text, which the reader should type directly,
% using the "\\lit" command.
%
% \begin{demo}{Use of \cmd\lit}
%Type \lit{ls} to display a
%list of files.
% \end{demo}
%
% Note that the literal text appears in quotes.  To suppress the quotes,
% use the `*' variant.
%
% The "\\lit" command produces slightly better output than "\\verb" for
% running text, since the spaces are somewhat narrower.  However, "\\verb"
% allows you to type arbitrary characters, which are treated literally,
% whereas you must use commands such as "\\{" to use special characters
% within the argument to "\\lit".  Of course, you can use "\\lit" anywhere
% in the document: "\\verb" mustn't be used inside a command argument.
% \end{synshorts}
%
% \subsection{Abbreviated forms for syntactic items}
%
% It would be very tedious to require the use of commands like |\synt|
% when building syntax descriptions like BNF grammars.  It would also make
% your \LaTeX\ source hard to read.  Therefore, \syn\ provides some
% abbreviated forms which make typesetting syntax quicker and easier.
%
% Since the abbreviated forms use several characters which you may want to
% use in normal text, they aren't enabled by default.  They only work
% with special commands and environments provided by the \syn\ package.
%
% The abbreviated forms are shown in the table below:
%
% \begin{tab}[\synshorts]{ll}                                       \hline
% \bf Input        & \bf Output                                  \\ \hline
% "<some text>"    & <some text>                                 \\
% "`some text'"    & `some text'                                 \\
% "\"some text\""  & "some text"                                 \\ \hline
% \end{tab}
%
% Within one of these abbreviated forms, text is treated more-or-less
% verbatim:
% \begin{itemize}
%
% \item Any |$|, |%|, |^|, |&|, |{|, |}|, |~| or |#| characters are treated
%       literally: their normal special meanings are ignored.
%
% \item Other special characters, with the exception of |\|, are also treated
%       literally: this includes any characters made special by |\shortverb|.
%
% \end{itemize}
%
% However, the |\| character retains its meaning.  Since the brace
% characters are not recognised, most commands can't be used within
% abbreviated forms.  However, you can use special commands to type some
% of the remaining special characters:
%
% \begin{tab}[\synshorts]{ll}                                       \hline
% \bf Command   & \bf Result                                     \\ \hline
% "\\\\"        & A `\\' character                               \\
% "\\>"         & A `>' character                                \\
% "\\'"         & A `\'' character                               \\
% "\\\""        & A `"' character                                \\
% "\\\ "        & A `\ ' character (not a space)                 \\ \hline
% \end{tab}
%
% Note that |\\|, |\>|, |\"| and \verb*|\ | are only useful in a |\tt| font,
% i.e., inside |`...'| and |"..."| forms, since the characters don't exist
% in normal fonts.  The |\>|, |\"| and |\'| commands are only provided so
% you can use these characters within |<...>|, |"..."| and |`...'| forms
% respectively: in the other forms, there is no need to use the special
% command.
%
% In addition, when the above abbreviations are enabled, the character "|"
% is set to typeset a \syntax{|} symbol, which is conventionally used to
% separate alternatives in syntax descriptions.
%
% \DescribeMacro\syntax
% Normally, these abbreviated forms are enabled only within special
% environments, such as \env{grammar} and \env{syntdiag}.  To use them
% in running text, use the |\syntax| command.  The abbreviations are made
% active within the argument of the |\syntax| command.\footnote{^^A
%   The argument of the \cmd\syntax\ command may contain commands such
%   as \cmd\verb, which are normally not allowed within arguments.
% }  Note that you cannot use the |\syntax| command within the argument
% of another command.
%
% \DescribeMacro\synshorts
% \DescribeEnv{synshorts}
% You can also enable the syntax shortcuts using the |\synshorts| declaration
% or the \env{synshorts} environment.  This enables the syntax shortcuts
% until the scope of the declaration ends.
%
% \DescribeMacro\synshortsoff
% If syntax shortcuts are enabled, you can disable them using the
% |\synshortsoff| declaration.
%
% \subsection{The \env{grammar} environment}
%
% \DescribeEnv{grammar}
% For typesetting formal grammars, for example, of programming languages,
% the \syn\ package provides a \env{grammar} environment.  Within this
% environment, the abbreviated forms described above are enabled.
%
% Within the environment, separate production rules should be separated by
% blank lines.  You can use the normal |\\| command to perform line-breaking
% of a production rule.  Note that a production rule must begin with a
% nonterminal name enclosed in angle brackets (|<| \dots |>|), followed by
% whitespace, then some kind of production operator (usually `::=') and then
% some more whitespace.  You can control how this text is actually typeset,
% however.
%
% \DescribeMacro{\[[}
% \DescribeMacro{\]]}
% You can use syntax diagrams (see below) instead of a straight piece of BNF
% by enclosing it in a |\[[| \dots |\]]| pair.  Note that you can't mix 
% syntax diagrams and BNF in a production rule, and you will get something
% which looks very strange if you try.
%
% \DescribeMacro\alt
% In addition, a command |\alt| is provided for splitting long production
% rules over several lines: the |\alt| command starts a new line and places
% a \syntax{|} character slightly in the left margin.  This is useful when
% a symbol has many alternative productions.
%
% \begin{demo}[w]{The \env{grammar} environment}
%\begin{grammar}
%<statement> ::= <ident> `=' <expr>
%  \alt `for' <ident> `=' <expr> `to' <expr> `do' <statement>
%  \alt `{' <stat-list> `}'
%  \alt <empty>
%
%<stat-list> ::= <statement> `;' <stat-list> | <statement>
%\end{grammar}
% \end{demo}
%
% You can modify the appearance of grammars using three length parameters:
%
% \begin{description} \def\makelabel{\hskip\labelsep\cmd}
%
% \item [\grammarparsep] is the amount of space inserted between production
%       rules.  It is a rubber length whose default value is 8\,pt, with
%       1\,pt of stretch and shrink.
%
% \item [\grammarindent] is the amount by which the right hand side of a
%       production rule is indented from the left margin.  It is a rigid
%       length.  Its default value is 2\,em.
%
% \end{description}
%
% \DescribeMacro\grammarlabel
% You can also control how the `label' is typeset by redefining the
% |\grammarlabel| command.  The command is given two arguments: the name of
% the nonterminal (which was enclosed in angle brackets), and the `production
% operator'.  The command is expected to produce the label.  By default, it
% typesets the nonterminal name using |\synt| and the operator at opposite
% ends of the label, separated by an |\hfill|.
%
% \subsection{Syntax diagrams}
%
% A full formal BNF grammar can be somewhat overwhelming for less technical
% readers.  Documents aimed at such readers tend to display grammatical
% structures as \emph{syntax diagrams}.
%
% \DescribeEnv{syntdiag}
% A syntax diagram is always enclosed in a \env{syntdiag} environment.  You
% should think of the environment as enclosing a new sort of \LaTeX\ mode:
% trying to type normal text into a syntax diagram will result in very ugly
% output.  \LaTeX\ ignores spaces and return characters while in syntax
% diagram mode.
%
% The syntax of the environment is very simple:
%
% \begin{grammar}
% <synt-diag-env> ::= \[[
%   "\\begin{syntdiag}"
%   \begin{stack} \\ "[" <decls> "]" \end{stack}
%   <text>
%   "\\end{syntdiag}"
% \]]
% \end{grammar}
%
% The \<decls> contain any declarations you want to insert, to control
% the environment.  The parameters to tweak are described below.
%
% Within a syntax diagram, you can include syntactic items using the
% abbreviated forms described elsewhere.  The output from these forms is
% modified slightly in syntax diagram mode so that the diagram looks
% right.
%
% I probably ought to point out now that the syntax diagram typesetting
% commands produce beautiful-looking diagrams with all the rules and curves
% accurately positioned.  Some device drivers don't position these objects
% correctly in their output.  I've had particular trouble with |dvips|.  I'll
% say it again: it's not my fault!
%
% \DescribeEnv{syntdiag*}
% The \env{syntdiag} environment only works in paragraph mode, and it acts
% rather like a paragraph, splitting over several lines when appropriate.
% If you just want to typeset a snippet of a syntax diagram, you can
% use the starred environment \env{syntdiag$*$}.
%
% \begin{grammar}
% <synt-diag-star-env> ::= \[[
%   "\\begin{syntdiag*}"
%   \begin{stack} \\ "[" <decls> "]" \end{stack}
%   \begin{stack} \\ "[" <width> "]" \end{stack}
%   <text>
%   "\\end{syntdiag*}"
% \]]
% \end{grammar}
%
% When typesetting little demos like this, it's not normal to fully adorn
% the syntax diagram with the full double arrows
% (`\begin{syntdiag*}[\left{>>-}\right{-><}]\tok{$\cdots$}\end{syntdiag*}').
% The two declarations \syntax{"\\left{"<arrow>"}" and "\\right{"<arrow>"}"}
% allow you to choose the arrows on each side of the syntax diagram snippet.
% The possible values of \<arrow> are shown in the table-ette below:
%
% ^^A Time to remember what I learned about tables while writing mdwtab.
% ^^A Just for the embarassment factor, here's the number of attempts I
% ^^A took to get the table below to look right: __6.  Hmm... not as bad
% ^^A as I expected.  Most of them were fine-tuning things.
%
% \medskip					^^A Leave a vertical gap
% \hbox to\columnwidth{\hfil\vbox{\tabskip=0pt	^^A Centre it horizontally
% \sdsize \csname sd@setsize\endcsname		^^A Position syntdiag arrows
% \halign to .5\columnwidth{			^^A Set the table width
%   &\ttfamily\ignorespaces#\unskip\hfil\tabskip=0pt ^^A Typeset the name
%   &\quad\csname sd@arr@#\endcsname\hfil	^^A Typeset the arrow
%   &\setbox0=\hbox{#}\tabskip=0pt plus 1fil\cr	^^A Stretch between columns
%   >>-&>>-&   &>-&>-&   &->&->\cr
%   -><&-><&   &...&...& &-&-\cr
% }}\hfil}					^^A Close the boxing
% \medskip					^^A And leave another gap
%
% These declarations should be used only in the optional argument to the
% \env{syntdiag$*$} command.  The second optional argument to the
% environment, if specified, fixes the width of the syntax diagram snippet;
% if you omit this argument, the diagram is made just wide enough to
% fit everything in.
%
% \begin{figure}
% \begin{demo}[w]{Example of \env{syntdiag$*$}}
%\newcommand{\bs}[2]{%
%  \begin{minipage}{1.6in}%
%  \begin{syntdiag*}[\left{#1}\right{#2}][1.6in]%
%}
%\newcommand{\es}{\end{syntdiag*}\end{minipage}}
%
%\begin{center}
%\begin{tabular}{cl}                                      \\ \hline
%\bf Construction    & \bf Meaning                        \\ \hline
%\bs {>>-} {...} \es & Start of syntax diagram            \\
%\bs {...} {-><} \es & End of syntax diagram              \\
%\bs {>-}  {...} \es & Continued on next line             \\
%\bs {...} {->}  \es & Continued from previous line       \\ \hline
%\bs {...} {...}
%  \begin{stack} <option-a> \\ <option-b> \\ <option-c> \end{stack}
%\es                 & Alternatives: choose any one       \\
%\bs {...} {...}
%  \begin{rep} <repeat-me> \\ <separator> \end{rep}
%\es                 & One or more items, with separators \\ \hline
%\end{tabular}
%\end{center}
% \end{demo}
% \end{figure}
%
% \DescribeMacro\tok
% You can also include text using the |\tok| command.  The argument of this
% command is typeset in \LaTeX's LR~mode and inserted into the diagram. 
% Syntax abbreviations are allowed within the argument, so you can, for
% example, include textual descriptions like
% \begin{listing}
%\tok{any <char> except `"'}
% \end{listing}
%
% \DescribeEnv{stack}
% Within a syntax diagram, a choice between several different items is
% shown by stacking the alternatives vertically.  In \LaTeX, this is done
% by enclosing the items in a \env{stack} environment.  Each individual item
% is separated by |\\| commands, as in the \env{array} and \env{tabular}
% environments.  Each row may contain any syntax diagram material, including
% |\tok| commands and other \env{stack} environments.
%
% Note if you end a \env{stack} environment with a |\\| command, a blank
% row is added to the bottom of the stack, indicating that none of the items
% need be specified.
%
% \DescribeEnv{rep}
% Text which can be repeated is enclosed in a \env{rep} environment: the
% text is displayed with a backwards pointing arrow drawn over it, showing
% that it may be repeated.  Optionally, you can specify text to be
% displayed in the arrow, separating it from the main text with a |\\|
% command.
%
% Note that items on the backwards arrow of a \env{rep} construction should
% be displayed \emph{backwards}.  You must put the individual items in
% reverse order when building this part of your diagrams.  \syn\ will 
% correctly reverse the arrows on \env{rep} structures, but apart from
% this, you must cope on your own.  You are recommended to keep these parts
% of your diagrams as simple as possible to avoid confusing readers.
%
% \begin{demo}[w]{A syntax diagram}
%\begin{syntdiag}
%<ident> `('
%  \begin{rep} \begin{stack} \\
%    <type> \begin{stack} \\ <ident> \end{stack}
%  \end{stack} \\ `,' \end{rep}
%\begin{stack} \\ `...' \end{stack} `)'
%\end{syntdiag}
% \end{demo}
%
% \DescribeMacro\(
% \DescribeMacro\)
% \DescribeMacro\<
% \DescribeMacro\>
% \DescribeMacro\[
% \DescribeMacro\]
% The environments \env{stack} and \env{rep} are rather cumbersome to use.
% As an alternative, the commands |\(| and |\)| are equivalent to
% |\begin{stack}| and |\end{stack}| respectively, and |\<| and |\>| are
% equivalent to |\begin{rep}| and |\end{rep}|.  Also, |\[| and |\]| are
% like |\begin{stack}| and |\end{stack}| except that an empty initial row is
% implicitly added.
%
% \subsubsection{Line breaking in syntax diagrams}
%
% Syntax diagrams are automatically broken over lines and across pages.
% Lines are only broken between items on the outermost level of the diagram:
% i.e., not within \env{stack} or \env{rep} environments.
%
% You can force a line break at a particular place by using the |\\| command
% as usual.  This supports all the usual \LaTeX\ features: a `|*|' variant
% which prohibits page breaking, and an optional argument specifying the
% extra vertical space between lines.
%
% \subsubsection{Customising syntax diagrams}
%
% There are two basic styles of syntax diagrams supported:
%
% \begin{description}
%
% \item [square] Lines in the syntax diagram join at squared-off corners.
%       This appears to be the standard way of displaying syntax diagrams
%       in IBM manuals, and most other documents I've seen.
%
% \item [rounded] Lines curve around corners.  Also, no arrows are drawn
%       around repeating loops: the curving of the lines provides this
%       information instead.  This style is used in various texts on
%       Pascal, and appears to be more popular in academic circles.
%
% \end{description}
%
% You can specify the style you want to use for syntax diagrams by giving
% the style name as an option on the |\usepackage| command.  For example,
% to force rounded edges to be used, you could say
%
% \begin{listing}
%\usepackage[rounded]{syntax}
% \end{listing}
%
% \DescribeMacro\sdsize
% \DescribeMacro\sdlengths
% The \env{syntdiag} environment takes an option argument, which should
% contain declarations which are obeyed while the environment is set up.
% The default value of this argument is `|\sdsize\sdlengths|'.  The
% |\sdsize| command sets the default type size for the environment: this is
% normally |\small|.  |\sdlengths| sets the values of the length parameters
% used by the environment based on the current text size.  These parameters
% are described below.
%
% For example, if you wanted to reduce the type size of the diagrams still
% further, you could use the command
% \begin{listing}
%\begin{syntdiag}[\tiny\sdlengths]
% \end{listing}
%
% The following length parameters may be altered:
%
% \begin{description} \def\makelabel{\hskip\labelsep\cmd}
%
% \item [\sdstartspace] The length of the rule between the arrows which
%       begin each line of the syntax diagram and the first item on the line.
%       Note that most objects have some space on either side of them as
%       well.  This is a rubber length.  Its default value is 1\,em, although
%       it can shrink by up to 10\,pt.
%
% \item [\sdendspace] The length of the rule between the last item on a
%       line and the arrow at the very end.  Note that the final line also
%       has extra rubber space on the end.  This is a rubber length.  Its
%       default value is 1\,em, although it will shrink by up to 10\,pt.
%
% \item [\sdmidskip] The length of the rule on either side of a large
%       construction (either a \env{stack} or a \env{rep}).  It is a rubber
%       length.  Its default value is \smallf 1/2\,em, with a very small
%       amount of infinite stretch.
%
% \item [\sdtokskip] The length of the rule on either side of a |\tok|
%       item or syntax abbreviation.  It is a rubber length.  Its default
%       value is \smallf 1/4\,em, with a very small amount of inifnite
%       stretch.
%
% \item [\sdfinalskip] The length of the rule which finishes the last line
%       of a syntax diagram.  It is a rubber length.  Its default value is
%       \smallf 1/2\,em, with 10000\,fil of stretch, which will left-align
%       the items on the line.\footnote{^^A
%         This is a little \TeX nical.  The idea is that if a stray 1\,fil
%         of stretch is added to the end of the line, it won't be noticed.
%         However, the alignment of the text on the line can still be
%         modified using \cmd{\sd@rule}\cmd{\hfill}, if you're feeling
%         brave.
%       }
%
% \item [\sdrulewidth] Half the width of the rules used in the diagram.
%       It is a rigid length.  Its default value is 0.2\,pt.
%
% \item [\sdcirclediam] The diameter of the circle from which the quadrants
%       used in rounded-style diagrams are taken.  This must be a multiple
%       of 4\,pt, or else the lines on the diagram won't match up.
%
% \end{description}
%
% In addition, you should call |\sdsetstrut| passing it the total height
% (\({\rm height}+{\rm depth}\)) of a normal line of text at the current
% size.  Normally, the value of |\baselineskip| will be appropriate.
%
% You can also alter the appearance of \env{stack}s and \env{rep}s by using
% their optional positioning arguments.  By default, \env{stack}s descend
% below the main line of the diagram, and \env{rep}s extend above it.  
% Specifying an optional argument of |[b]| for either environment reverses
% this, putting \env{stack}s above and \env{rep}s below the line.
%
% \subsection{Changing the presentation styles}
%
% You can change the way in which the syntax items are typeset by altering
% some simple commands (using |\renewcommand|).  Each item (nonterminals,
% as typeset by |\synt|, and quoted and unquoted terminals, as typeset by
% |\lit| and |\lit*|) has two style commands associated with it, as shown
% in the table below.
%
% \begin{tab}{lll}						   \hline
% \bf Syntax item	& \bf Left command & \bf Right command	\\ \hline
% Nonterminals		& |\syntleft|	   & |\syntright|	\\
% Quoted terminals	& |\litleft|	   & |\litright|	\\
% Unquoted terminals	& |\ulitleft|	   & |\ulitright|	\\ \hline
% \end{tab}
%
% It's not too hard to see how this works.  For example, if you look at
% the implementation for |\syntleft| and |\syntright| in the implementation
% section, you'll notice that they're defined like this:
% \begin{listing}
%\newcommand{\syntleft}{$\langle$\normalfont\itshape}
%\newcommand{\syntright}{$\rangle$}
% \end{listing}
% I think this is fairly simple, if you understand things like font changing.
%
% Note that changing these style commands alters the appearance of all syntax
% objects of the appropriate types, as created by the |\synt| and |\lit|
% commands, in \env{grammar} environments, and in syntax diagrams.
%
%
% \implementation
%
% \section{Implementation of \syn}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \subsection{Options handling}
%
% We define all the options we know about, and then see what's been put
% on the usepackage line.
%
% The options we provide currently are as follows:
%
% \begin{description}
% \item [rounded] draws neatly rounded edges on the diagram.
% \item [square] draws squared-off edges on the diagram.  This is the
%       default.
% \item [nounderscore] disables the undescore active character,  The |\_|
%       command still produces the nice version created here.
% \end{description}
%
%    \begin{macrocode}
\DeclareOption{rounded}{\sd@roundtrue}
\DeclareOption{square}{\sd@roundfalse}
\DeclareOption{nounderscore}{\@uscorefalse}
%    \end{macrocode}
%
% Now process the options:
%
%    \begin{macrocode}
\newif\ifsd@round
\newif\if@uscore\@uscoretrue
\newif\ifsd@left\newif\ifsd@right
\ExecuteOptions{square}
\ProcessOptions
%    \end{macrocode}
%
% \subsection{Special character handling}
%
% A lot of the \syn\ package requires the use special active characters.
% These must be added to two lists: |\dospecials|, which is used by |\verb|
% and friends, and |\@sanitize|, which is used by |\index|.  The two macros
% here, |\addspecial| and |\remspecial|, provide these registration
% facilities.
%
% Two similar macros are found in Frank Mittelbach's \package{doc} package:
% these have the disadvantage of global operation.  My macros here are based
% on Frank's, which in turn appear to be based on Donald Knuth's list
% handling code presented in Appendix~D of \textit{The \TeX book}.
%
% Both these macros take a single argument: a single-character control
% sequence containing the special character to be added to or removed from
% the lists.
%
% \begin{macro}{\addspecial}
%
% This is reasonably straightforward.  We remove the sequence from the lists,
% in case it's already there, and add it in in the obvious way.  This
% requires a little bit of fun with |\expandafter|.
%
%    \begin{macrocode}
\def\addspecial#1{%
  \remspecial{#1}%
  \expandafter\def\expandafter\dospecials\expandafter{\dospecials\do#1}%
  \expandafter\def\expandafter\@santize\expandafter{%
    \@sanitize\@makeother#1}%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\remspecial}
%
% This is the difficult bit.  Since |\dospecials| and |\@sanitize| have the
% form of list macros, we can redefine |\do| and |\@makeother| to do the
% job for us.  We must be careful to put the old meaning of |\@makeother|
% back.  The current implementation assumes it knows what |\@makeother| does.
%
%    \begin{macrocode}
\def\remspecial#1{%
  \def\do##1{\ifnum`#1=`##1 \else\noexpand\do\noexpand##1\fi}%
  \edef\dospecials{\dospecials}%
  \def\@makeother##1{\ifnum`#1=`##1 \else%
    \noexpand\@makeother\noexpand##1\fi}%
  \edef\@sanitize{\@sanitize}%
  \def\@makeother##1{\catcode`##112}%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsection{Underscore handling}
%
% When typing a lot of identifiers, it can be irksome to have to escape
% all `|_|' characters in the manuscript.  We make the underscore character
% active, so that it typesets an underscore in horizontal mode, and does
% its usual job as a subscript operator in maths mode.  Underscore must
% already be in the special character lists, because of its use as a
% subscript character, so this doesn't cause us a problem.
%
% \begin{macro}{\underscore}
%
% The |\underscore| macro typesets an underline character, using a horizontal
% rule.  This is positioned slightly below the baseline, and is also slightly
% wider than the default \TeX\ underscore.  This code is based on a similar
% implementation found in the \package{lgrind} package.
%
%    \begin{macrocode}
\def\underscore{%
  \leavevmode%
  \kern.06em%
  \vbox{%
    \hrule\@width.6em\@depth.4ex\@height-.34ex%
  }%
  \ifdim\fontdimen\@ne\font=\z@%
    \kern.06em%
  \fi%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\@foundunderscore}
%
% This macro is called by the `|_|' active character to sort out what to do.
%
% If this is maths mode, we use the |\sb| macro, which is already defined
% to do subscripting.  Otherwise, we call |\textunderscore|, which picks the
% nicest underscore it can find.
%
% There's some extra cunningness here, because I'd like to be able to
% hyphenate after underscores usually, but not when there's another one
% following.  And then, because \env{tabbing} redefines |\_|, there's some
% more yukkiness to handle that: the usual |\@tabacckludge| mechanism doesn't
% cope with this particular case.
%
%    \begin{macrocode}
\let\usc@builtindischyphen\-
\def\@uscore.{%
  \ifmmode%
    \expandafter\@firstoftwo%
  \else%
    \expandafter\@secondoftwo%
  \fi%
  \sb%
  {\textunderscore\@ifnextchar_{}{\usc@builtindischyphen}}%
}
%    \end{macrocode}
%
% \end{macro}
%
% Now we set up the active character.  Note the |\protect|, which makes
% underscores work reasonably well in moving arguments.  Note also the way
% we end with a some funny stuff to prevent spaces being lost if this is
% written to a file.
%
%    \begin{macrocode}
\if@uscore
  \AtBeginDocument{%
    \catcode`\_\active%
    \begingroup%
    \lccode`\~`\_%
    \lowercase{\endgroup\def~{\protect\@uscore.}}%
  }
\fi
%    \end{macrocode}
%
% Finally, we redefine the |\_| macro to use our own |\underscore|, because
% it's prettier.  Actually, we don't: we just redefine the
% |\?\textunderscore| command (funny name, isn't it?).
%
%    \begin{macrocode}
\expandafter\let\csname?\string\textunderscore\endcsname\underscore
%    \end{macrocode}
%
% \subsection{Abbreviated verbatim notation}
%
%  In similar style to the \package{doc} package, we allow the user to set up
% characters which delimit verbatim text.  Unlike \package{doc}, we make
% such changes local to the current group.  This is performed through the
% |\shortverb| and |\unverb| commands.
%
% The implementations of these commands are based upon the |\MakeShortVerb|
% and |\DeleteShortVerb| commands of the \package{doc} package, although
% these versions have effect local to the current grouping level.  This
% prevents their redefinition of |\dospecials| from interfering with the
% grammar shortcuts, which require local changes only.
%
% The command |\shortverb| takes a single argument: a single-character
% control sequence defining which character to make into the verbatim text
% delimiter.  We store the old meaning of the active character in a control
% sequence called |\mn@\|\<char>.  Note that this control sequence
% contains a backslash character, which is a little odd.  We also define a
% command |\cc@\|\<char> which will return everything to normal.  This
% is used by the |\unverb| command.
%
% \begin{macro}{\shortverb}
%
% Here we build the control sequences we need to make everything work nicely.
% The active character is defined via |\lowercase|, using the |~| character:
% this is already made active by \TeX\@.
%
% The actual code requires lots of fiddling with |\expandafter| and friends.
%
%    \begin{macrocode}
\def\shortverb#1{%
%    \end{macrocode}
%
% First, we check to see if the command |\cc@\|\<char> has been defined.
%
%    \begin{macrocode}
  \@ifundefined{cc@\string#1}{%
%    \end{macrocode}
%
% If it hasn't been defined, we add the character to the specials list.
%
%    \begin{macrocode}
    \addspecial#1%
%    \end{macrocode}
%
% Now we set our character to be the lowercase version of |~|, which allows
% us to use it, even though we don't know what it is.
%
%    \begin{macrocode}
    \begingroup%
    \lccode`\~`#1%
%    \end{macrocode}
%
% Finally, we reach the tricky bit.  All of this is lowercased, so any
% occurrences of |~| are replaced by the user's special character.
%
%    \begin{macrocode}
    \lowercase{%
      \endgroup%
%    \end{macrocode}
%
% We remember the current meaning of the character, in case it has one.  We
% have to use |\csname| to build the rather strange name we use for this.
%
%    \begin{macrocode}
      \expandafter\let\csname mn@\string#1\endcsname~%
%    \end{macrocode}
%
% Now we build |\cc@\|\<char>.  This is done with |\edef|, since more
% of this needs to be expanded now than not.  In this way, the actual macros
% we create end up being very short.
%
%    \begin{macrocode}
      \expandafter\edef\csname cc@\string#1\endcsname{%
%    \end{macrocode}
%
% First, add a command to restore the character's old catcode.
%
%    \begin{macrocode}
        \catcode`\noexpand#1\the\catcode`#1%
%    \end{macrocode}
%
% Now we restore the character's old meaning, using the version we saved
% earlier.
%
%    \begin{macrocode}
        \let\noexpand~\expandafter\noexpand%
          \csname mn@\string#1\endcsname%
%    \end{macrocode}
%
% Now we remove the character from the specials lists.
%
%    \begin{macrocode}
        \noexpand\remspecial\noexpand#1%
%    \end{macrocode}
%
% Finally, we delete this macro, so that |\unverb| will generate a warning
% if the character is |\unverb|ed again.
%
%    \begin{macrocode}
        \let\csname cc@\string#1\endcsname\relax%
      }%
%    \end{macrocode}
%
% All of that's over now.  We set up the new definition of the character,
% in terms of |\verb|, and make the character active.  The nasty |\syn@ttspace|
% is there to make the spacing come out right.  It's all right really.  Honest.
%
%    \begin{macrocode}
      \def~{\verb~\syn@ttspace}%
    }%
    \catcode`#1\active%
%    \end{macrocode}
%
% If our magic control sequence already existed, we can assume that the
% character is already a verbatim delimiter, and raise a warning.
%
%    \begin{macrocode}
  }{%
    \PackageWarning{syntax}{Character `\expandafter\@gobble\string#1'
                            is already a verbatim\MessageBreak
                            delimiter}%
  }%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\unverb}
%
% This is actually terribly easy: we just use the |\cc@\|\<char> command
% we definied earlier, after making sure that it's been defined.
%
%    \begin{macrocode}
\def\unverb#1{%
  \@ifundefined{cc@\string#1}{%
    \PackageWarning{syntax}{Character `\expandafter\@gobble\string#1'
                            is not a verbatim\MessageBreak
                            delimiter}%
  }{%
    \csname cc@\string#1\endcsname%
  }%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsection{Style hooks for syntax forms}
%
% To allow the appearance of syntax things to be configured, we provide some
% redefinable bits.
%
% The three types of objects (nonterminal symbols, and quoted and unquoted
% terminals) each have two macros associated with them: one which does the
% `left' bit of the typesetting, and one which does the `right' bit.  The
% items are typeset as LR~boxes.  I'll be extra good while defining these
% hooks, so that it's obvious what's going on; macho \TeX\ hacker things
% resume after this section.
%
% \begin{macro}{\syntleft}
% \begin{macro}{\syntright}
%
% I can't see why anyone would want to change the typesetting of
% nonterminals, although I'll provide the hooks for symmetry's sake.
%
%     \begin{macrocode}
\newcommand{\syntleft}{$\langle$\normalfont\itshape}
\newcommand{\syntright}{$\rangle$}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ulitleft}
% \begin{macro}{\ulitright}
% \begin{macro}{\litleft}
% \begin{macro}{\litright}
%
% Now we can define the left and right parts of quoted and unquoted
% terminals.  US~readers may want to put double quotes around the quoted
% terminals, for example.
%
%    \begin{macrocode}
\newcommand{\ulitleft}{\normalfont\ttfamily\syn@ttspace\frenchspacing}
\newcommand{\ulitright}{}
\newcommand{\litleft}{`\bgroup\ulitleft}
\newcommand{\litright}{\ulitright\egroup'}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Simple syntax typesetting}
%
% In general text, we allow access to our typesetting conventions through
% standard \LaTeX\ commands.
%
% \begin{macro}{\synt}
%
% The |\synt| macro typesets its argument as a syntactic quantity.  It puts
% the text of the argument in italics, and sets angle brackets around it.
% Breaking of a |\synt| object across lines is forbidden.
%
%    \begin{macrocode}
\def\synt#1{\mbox{\syntleft{#1\/}\syntright}}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\lit}
%
% The |\lit| macro typesets its argument as literal text, to be typed in.
% Normally, this means setting the text in |\tt| font, and putting quotes
% around it, although the quotes can be suppressed by using the $*$-variant.
%
% The |\syn@ttspace| macro sets up the spacing for the text nicely: |\tt|
% spaces tend to be a little wide.
%
%    \begin{macrocode}
\def\lit{\@ifstar{\lit@i\ulitleft\ulitright}{\lit@i\litleft\litright}}
\def\lit@i#1#2#3{\mbox{#1{#3\/}#2}}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\syn@ttspace}
%
% This sets up the |\spaceskip| value for |\tt| text.
%
%    \begin{macrocode}
\def\syn@ttspace@{\spaceskip.35em\@plus.2em\@minus.15em\relax}
%    \end{macrocode}
%
% However, this isn't always the right thing to do.
%
%    \begin{macrocode}
\def\ttthinspace{\let\syn@ttspace\syn@ttspace@}
\def\ttthickspace{\let\syn@ttspace\@empty}
%    \end{macrocode}
%
% I know what I like thoough.
%
%    \begin{macrocode}
\ttthinspace
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{The shortcuts}
%
% The easy part is over now.  The next job is to set up the `grammar
% shortcuts' which allow easy changing of styles.
%
% We support four shortcuts:
% \begin{itemize}
% \item |`literal text'| typesets \syntax{`literal text'}
% \item |<non-terminal>| typesets \syntax{<non-terminal>}
% \item |"unquoted text"| typesets \syntax{"unquoted text"}
% \item \verb"|" typesets a \syntax{|} character
% \end{itemize}
% These are all implemented through active characters, which are enabled
% using the |\syntaxShortcuts| macro, described below.
%
% \begin{macro}{\readupto}
%
% \syntax{"\\readupto{"<char>"}{"<decls>"}{"<command>"}"} will read all
% characters up until the next occurrence of \<char>.  Normally, all
% special characters will be deactivated.  However, you can reactivate some
% characters, using the \<decls> argument, which is processed before the
% text is read.
%
% The code is borrowed fairly obviously from the \LaTeXe\ source for the
% |\verb| command.
%
%    \begin{macrocode}
\def\readupto#1#2#3{%
  \bgroup%
  \verb@eol@error%
  \let\do\@makeother\dospecials%
  #2%
  \catcode`#1\active%
  \lccode`\~`#1%
  \gdef\verb@balance@group{\verb@egroup%
     \@latex@error{\noexpand\verb illegal in command argument}\@ehc}%
  \def\@vhook{\verb@egroup#3}%
  \aftergroup\verb@balance@group%
  \lowercase{\let~\@vhook}%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\syn@assist}
%
% The |\syn@assist| macro is used for defining three of the shortcuts.  It
% is called as
%
% \begin{quote}
% \syntax{"\\syn@assist{"<left-decls>"}{"<actives>"}{"<delimeter>"}" \\
% \null \quad "{"<right-decls>"}{"<end-cmd>"}"}
% \end{quote}
%
% It creates an hbox, sets up the escape sequences for quoting our magic
% characters, and then typesets a box containing
%
% \begin{quote}
% \syntax{<left-decls>"{"<delimited-text>"\\/}"<right-decls>}
% \end{quote}
%
% The \<left-decls> and \<right-decls> can be |\relax| if they're not
% required.
%
% The \<actives> argument is passed to |\readupto|, to allow some special
% characters through.  By default, we re-enable |\|, and make `\verb*" "'
% typeset some space glue, rather than a space character.  A macro
% `\verb*"\ "' is defined to actually print a space character, which yield
% `\verb*" "' in the `|\tt|' font. 
%
% Finally, it defines a |\ch| command, which, given a single-character
% control sequence as its argument, typesets the character.  This is useful,
% since |`| has been made active when we set up these calls, so the
% direct |\char`\|\<char> doesn't work.
%
%    \begin{macrocode}
\def\syn@assist#1#2#3#4#5{%
%    \end{macrocode}
%
% First, we start the box, and open a group.  We use |\mbox| because it
% does all the messing with |\leavevmode| which is needed.
%
%    \begin{macrocode}
  \leavevmode\hbox\bgroup%
%    \end{macrocode}
%
% Next job is to set up the escape sequences.
%
%    \begin{macrocode}
  \chardef\\`\\%
  \chardef\>`\>%
  \chardef\'`\'%
  \chardef\"`\"%
  \chardef\ `\ %
%    \end{macrocode}
%
% Now to define |\ch|.  This is done the obvious way.
%
%    \begin{macrocode}
  \def\ch##1{\char`##1}%
%    \end{macrocode}
%
% For active characters, we do some fiddling with |\lccode|s.
%
%    \begin{macrocode}
  \def\act##1{%
    \catcode`##1\active%
    \begingroup%
    \lccode`\~`##1%
    \lowercase{\endgroup\def~}%
  }%
%    \end{macrocode}
%
% Finally, we do the real work of setting the text.  We use |\readupto| to
% actually find the text we want.
%
%    \begin{macrocode}
  #1%
  \begingroup%
  \readupto#3{%
    \catcode`\\0%
    \catcode`\ 10%
    #2%
  }{%
    \/\endgroup#4\egroup#5%
  }%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\syn@shorts}
%
% This macro actually defines the expansions for the active characters.
% We have to do this separately because |`| must be active when we use it
% in the |\def|, but we can't do that and use |\catcode| at the same time.
% The arguments are commands to do before and after the actual command.
% These are passed up from |\syntaxShortcuts|.
%
% All of the characters use |\syn@assist| in the obvious way except for
% \verb"|", which drops into maths mode instead.
%
% Note that when changing the catcodes, we must save |`| until last.
%
%    \begin{macrocode}
\begingroup
\catcode`\<\active
\catcode`\|\active
\catcode`\"\active
\catcode`\`\active
%
\gdef\syn@shorts#1#2{%
%    \end{macrocode}
%
% The `|<|' character must typeset its argument in italics.  We make `|_|'
% do the same as the `|\_|' command.
%
%    \begin{macrocode}
  \def<{%
    #1%
    \syn@assist%
      \syntleft%
      {\act_{\@uscore.}}%
      >%
      \syntright%
      {#2}%
  }%
%    \end{macrocode}
%
% The `|`|' and `|"|' characters should print its argument in |\tt| font.
% We change the `|\tt|' space glue to provide nicer spacing on the line.
%
%    \begin{macrocode}
  \def`{%
    #1%
    \syn@assist%
      \litleft%
      \relax%
      '%
      \litright%
      {#2}%
  }%
  \def"{%
    #1%
    \syn@assist%
      \ulitleft%
      \relax%
      "%
      \ulitright%
      {#2}%
  }%
%    \end{macrocode}
%
% Finally, the `\verb"|"' character is typeset by using the mysterious
% |\textbar| command.
%
%    \begin{macrocode}
  \def|{\textbar}%
%    \end{macrocode}
%
% We're finished here now.
%
%    \begin{macrocode}
}
%
\endgroup
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\syntaxShortcuts}
%
% This is a user-level command which enables the use of our shortcuts in the
% current group.  It uses |\addspecial|, defined below, to register the
% active characters, sets up their definitions and activates them.
%
% The two arguments are commands to be performed before and after the
% handling of the abbreviation.  In this way, you can further process the
% output.
%
% This command is not intended to be used directly by users: it should be
% used by other macros and packages which wish to take advantage of the
% facilities offered by this package.  We provide a |\synshorts| declaration
% (which may be used as an environment, of course) which is more `user
% palatable'.
%
%    \begin{macrocode}
\def\syntaxShortcuts#1#2{%
  \syn@shorts{#1}{#2}%
  \addspecial\`%
  \addspecial\<%
  \addspecial\|%
  \addspecial\"%
  \catcode`\|\active%
  \catcode`\<\active% 
  \catcode`\"\active%
  \catcode`\`\active%
}
%
\def\synshorts{\syntaxShortcuts\relax\relax}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\synshortsoff}
%
% This macro can be useful occasionally: it disables the syntax shortcuts,
% so you can type normal text for a while.
%
%    \begin{macrocode}
\def\synshortsoff{%
  \catcode`\|12%
  \catcode`\<12%
  \catcode`\"12%
  \catcode`\`12%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\syntax}
%
% The |\syntax| macro typesets its argument, allowing the use of our
% shortcuts within the argument.
%
% Actually, we go to some trouble to ensure that the argument to |\syntax|
% \emph{isn't} a real argument so we can change catcodes as we go.  We
% use the |\let\@let@token=| trick from \PlainTeX\ to do this.
%
%    \begin{macrocode}
\def\syntax#{\bgroup\syntaxShortcuts\relax\relax\let\@let@token}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{environment}{grammar}
%
% The \env{grammar} environment is the final object we have to define.  It
% allows typesetting of beautiful BNF grammars.
%
% First, we define the length parameters we need:
%
%    \begin{macrocode}
\newskip\grammarparsep
  \grammarparsep8\p@\@plus\p@\@minus\p@
\newdimen\grammarindent
  \grammarindent2em
%    \end{macrocode}
%
% Now define the default label typesetting.  This macro is designed to be
% replaced by a user, so we'll be extra-well-behaved and use genuine \LaTeX\
% commands.  Well, almost \dots
%
%    \begin{macrocode}
\newcommand{\grammarlabel}[2]{%
  \synt{#1} \hfill#2%
}
%    \end{macrocode}
%
% Now for a bit of hacking to make the item stuff work properly.  This gets
% done for every new paragraph that's started without an |\item| command.
%
% First, store the left hand side of the production in a box.  Then I'll
% end the paragraph, and insert some nasty glue to take up all the space,
% so no-one will ever notice that there was a paragraph break there.  The
% strut just makes sure that I know exactly how high the line is.
%
%    \begin{macrocode}
\def\gr@implitem<#1> #2 {%
  \sbox\z@{\hskip\labelsep\grammarlabel{#1}{#2}}%
  \strut\@@par%
  \vskip-\parskip%
  \vskip-\baselineskip%
%    \end{macrocode}
%
% The |\item| command will notice that I've inserted these funny glues and
% try to remove them: I'll stymie its efforts by inserting an invisible
% rule.  Then I'll insert the label using |\item| in the normal way.
%
%    \begin{macrocode}
  \hrule\@height\z@\@depth\z@\relax%
  \item[\unhbox\z@]%
%    \end{macrocode}
%
% Just before I go, I'll make \lit{<} back into an active character.
%
%    \begin{macrocode}
  \catcode`\<\active%
}
%    \end{macrocode}
%
% Now for the environment proper.  Deep down, it's a list environment, with
% some nasty tricks to stop anyone from noticing.
%
% The first job is to set up the list from the parameters I'm given.
%
%    \begin{macrocode}
\newenvironment{grammar}{%
  \list{}{%
    \labelwidth\grammarindent%
    \leftmargin\grammarindent%
    \advance\grammarindent\labelsep
    \itemindent\z@%
    \listparindent\z@%
    \parsep\grammarparsep%
  }%
%    \end{macrocode}
%
% We have major problems in |\raggedright| layouts, which try to use |\par|
% to start new lines.  We go back to normal |\\| newlines to try and bodge
% our way around these problems.
%
%    \begin{macrocode}
  \let\\\@normalcr
%    \end{macrocode}
%
% Now to enable the shortcuts.
%
%    \begin{macrocode}
  \syntaxShortcuts\relax\relax%
%    \end{macrocode}
%
% Now a little bit of magic.  The |\alt| macro moves us to a new line, and
% typesets a vertical bar in the margin.  This allows typesetting of
% multiline alternative productions in a pretty way.
%
%    \begin{macrocode}
  \def\alt{\\\llap{\textbar\quad}}%
%    \end{macrocode}
%
% Now for another bit of magic.  We set up some |\par| cleverness to spot
% the start of each production rule and format it in some cunning and
% user-defined way.
%
%    \begin{macrocode}
  \def\gr@setpar{%
    \def\par{%
      \parshape\@ne\@totalleftmargin\linewidth%
      \@@par%
      \catcode`\<12%
      \everypar{%
        \everypar{}%
        \catcode`\<\active%
        \gr@implitem%
      }%
    }%
  }%
  \gr@setpar%
  \par%
%    \end{macrocode}
%
% Now set up the |\[[| and |\]]| commands to do the right thing.  We have
% to check the next character to see if it's correct, otherwise we'll
% open a maths display as usual.
%
%    \begin{macrocode}
  \let\gr@leftsq\[%
  \let\gr@rightsq\]%
  \def\gr@endsyntdiag]{\end{syntdiag}\gr@setpar\par}%
  \def\[{\@ifnextchar[{\begin{syntdiag}\@gobble}\gr@leftsq}%
  \def\]{\@ifnextchar]\gr@endsyntdiag\gr@rightsq}%
%    \end{macrocode}
%
% Well, that's it for this side of the environment.
%
%    \begin{macrocode}
}{%
%    \end{macrocode}
%
% Closing the environment is a simple matter of tidying away the list.
%
%    \begin{macrocode}
  \@newlistfalse%
  \everypar{}%
  \endlist%
}
%    \end{macrocode}
%
% \end{environment}
%
% \subsection{Syntax diagrams}
%
% Now we come to the final and most complicated part of the package.
%
% Syntax diagrams are drawn using arrow characters from \LaTeX's line font,
% used in the \env{picture} environment, and rules.  The horizontal rules
% of the diagram are drawn along the baselines of the lines in which they
% are placed.  The text items in the diagram are placed in boxes and lowered
% below the main baseline.  Struts are added throughout to keep the vertical
% spacing consistent.
%
% The vertical structures (stacks and loops) are all implemented with \TeX's
% primitive |\halign| command.
%
% \subsubsection{User-configurable parameters}
%
% First, we allocate the \<dimen> and \<skip> arguments needed.  Fixed
% lengths, as the \LaTeX book calls them, are allocated as \<dimen>s, to
% take some of the load off of all the \<skip> registers.
%
%    \begin{macrocode}
\newskip\sdstartspace
\newskip\sdendspace
\newskip\sdmidskip
\newskip\sdtokskip
\newskip\sdfinalskip
\newdimen\sdrulewidth
\newdimen\sdcirclediam
\newdimen\sdindent
%    \end{macrocode}
%
% We need some \TeX\ \<dimen>s for our own purposes, to get everything in
% the right places.  We use labels for the `temporary' \TeX\ parameters
% which we use, to avoid wasting registers.
%
%    \begin{macrocode}
\dimendef\sd@lower\z@
\dimendef\sd@upper\tw@
\dimendef\sd@mid4
\dimendef\sd@topcirc6
\dimendef\sd@botcirc8
\skipdef\sd@qskip2
%    \end{macrocode}
%
% \begin{macro}{\sd@setsize}
% When the text size for syntax diagrams changes, it's necessary to work out
% the height for various rules in the diagram.
%
%    \begin{macrocode}
\def\sd@setsize{%
  \sd@mid\ht\strutbox%
  \advance\sd@mid-\dp\strutbox%
  \sd@mid.5\sd@mid%
  \sd@upper\sdrulewidth%
    \advance\sd@upper\sd@mid%
  \sd@lower\sdrulewidth%
    \advance\sd@lower-\sd@mid%
  \sd@topcirc-.5\sdcirclediam%
    \advance\sd@topcirc\sd@mid%
  \sd@botcirc-.5\sdcirclediam%
    \advance\sd@botcirc-\sd@mid%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sdsize}
%
% You can set the default type size used by syntax diagrams by redefining
% the |\sdsize| command, using the |\renewcommand| command.
%
% By default, syntax diagrams are set slightly smaller than the main body
% text.\footnote{^^A
%   I've used pure \LaTeX\ commands for this and the \cmd\sdlengths\ macro,
%   to try and illustrate how these values might be changed by a user.  The
%   rest of the code is almost obfuscted in its use of raw \TeX\ features,
%   in an attempt to dissuade more na\"\i ve users from fiddling with it.
%   I suppose this is what you get when you let assembler hackers loose with
%   something like \LaTeX.
% }
%
%    \begin{macrocode}
\newcommand{\sdsize}{%
  \small%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sdlengths}
%
% Finally, the default length parameters are set in the |\sdlengths| command.
% You can redefine the command using |\renewcommand|.
%
% We set up the length parameters here.
%
%    \begin{macrocode}
\newcommand{\sdlengths}{%
  \setlength{\sdstartspace}{1em minus 10pt}%
  \setlength{\sdendspace}{1em minus 10pt}%
  \setlength{\sdmidskip}{0.5em plus 1em}%
  \setlength{\sdtokskip}{0.25em plus 1em}%
  \setlength{\sdfinalskip}{0.5em plus 10000fil}%
  \setlength{\sdrulewidth}{0.2pt}%
  \setlength{\sdcirclediam}{8pt}%
  \setlength{\sdindent}{0pt}%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{Other declarations}
%
% We define four switches.  The table shows what they're used for.
%
% \begin{table}
% \begin{tab}{lp{3in}}                                              \hline
%
% \bf Switch        & \bf Meaning                                \\ \hline
%
% |\ifsd@base|      & We are at `base level' in the diagram:
%                     i.e., not in any other sorts of
%                     constructions.  This is used to decide
%                     whether to allow line breaking.            \\[2pt]
%
% |\ifsd@top|       & The current loop construct is being
%                     typeset with the loop arrow above the
%                     baseline.                                  \\[2pt]
%
% |\ifsd@toplayer|  & We are typesetting the top layer of
%                     a stack.  This is used to ensure that
%                     the vertical rules on either side are
%                     typeset at the right height.               \\[2pt]
%
% |\ifsd@backwards| & We're typesetting backwards, because
%                     we're in the middle of a loop arrow.
%                     the only difference this makes is that
%                     any subloops have the arrow on the
%                     side.                                      \\ \hline
%
% \end{tab}
% \caption{Syntax diagram switches}
% \end{table}
%
%    \begin{macrocode}
\newif\ifsd@base
\newif\ifsd@top
\newif\ifsd@toplayer
\newif\ifsd@backwards
%    \end{macrocode}
%
% \begin{macro}{\sd@err}
%
% We output our errors through this macro, which saves a little typing.
%
%    \begin{macrocode}
\def\sd@err{\PackageError{syntax}}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{Arrow-drawing}
%
% We need to draw some arrows.  \LaTeX\ tries to make this as awkward as
% possible, so we have to start moving the arrows around in boxes quite a
% lot.
%
% The left and right pointing arrows are fairly simple: we just add some
% horizontal spacing to prevent the width of the arrow looking odd.
%
%    \begin{macrocode}
\def\sd@arrow{%
  \ht\tw@\z@%
  \dp\tw@\z@%
  \raise\sd@mid\box\tw@%
  \egroup%
}
\def\sd@rightarr{%
  \bgroup%
  \setbox\tw@\hbox{\kern-6\p@\@linefnt\char'55}%
  \sd@arrow%
}
\def\sd@leftarr{%
  \bgroup%
  \setbox\tw@\hbox{\@linefnt\char'33\kern-6\p@}%
  \sd@arrow%
}
%    \end{macrocode}
%
% The up arrow is very strange.  We need to bring the arrow down to base
% level, and smash its height.
%
%    \begin{macrocode}
\def\sd@uparr{%
  \bgroup%
  \setbox\tw@\hb@xt@\z@{\kern-\sdrulewidth\@linefnt\char'66\hss}%
  \setbox\tw@\hbox{\lower10\p@\box\tw@}%
  \sd@arrow%
}
%    \end{macrocode}
%
% The down arrow is similar, although it's already at the right height.
% Thus, we can just smash the box.
%
%    \begin{macrocode}
\def\sd@downarr{%
  \bgroup%
  \setbox\tw@\hb@xt@\z@{\kern-\sdrulewidth\@linefnt\char'77\hss}%
  \sd@arrow%
}
%    \end{macrocode}
%
% \subsubsection{Drawing curves}
%
% If the user has selected curved edges, we use the \LaTeX\ features provided
% to obtain the curves.  These are drawn slightly oddly to make it easier
% to fit them into the diagram.
%
% Some explanation about the \LaTeX\ circle font is probably called for
% before we go any further.  The font consists of sets of four quadrants
% of a particular size (and some other characters, which aren't important
% at the moment).  Each collection of quadrants fit together to form a
% perfect circle of a given diameter.  The individual quadrant characters
% have strange bounding boxes, as described in the files \textit{lcircle.mf}
% and \textit{ltpict.dtx}, and also in Appendix~D of \textit{The \TeX book}.
% Our job here is to make these quadrants useful in the context of
% drawing syntax diagrams.
%
% \begin{macro}{\sd@circ}
% First, we define |\sd@circ|, which performs the common parts of the four
% routines.  Since the characters in the circle font are grouped together,
% we can pick out a particular corner piece by specifying its index into
% the group for the required size.  The |\sd@circ| routine will pick out
% the required character, given this index as an argument, and put it in
% box~2, after fiddling with the sizes a little:
% \begin{itemize}
%
% \item We clear the width to zero.  The individual routines then add a kern
%       of the correct amount, so that the quadrant appears in the right
%       place.
%
% \item The piece is lowered by half the rule width.  This positions the
%       top and bottom pieces of the circle to be half way over the baseline,
%       which is the correct position for the rest of the diagram.
%
% \end{itemize}
%
% Finally, we make sure we're in horizontal mode: horrific results occur
% if this is not the case.  I'm sure I don't need to explain this any more
% graphically.
%
%    \begin{macrocode}
\def\sd@circ#1{%
  \@getcirc\sdcirclediam%
  \advance\@tempcnta#1%
  \setbox\tw@\hbox{\lower\sdrulewidth%
    \hbox{\@circlefnt\char\@tempcnta}}%
  \wd\tw@\z@%
  \leavevmode%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@tlcirc}
% \begin{macro}{\sd@trcirc}
% \begin{macro}{\sd@blcirc}
% \begin{macro}{\sd@brcirc}
%
% These are the macros which actually draw quadrants of circles.  They all
% call |\sd@circ|, passing an appropriate index, and then fiddle with the
% box sizes and apply kerning specific to the quadrant positioning.
%
% The exact requirements for positioning are as follows:
%
% \begin{itemize}
%
% \item The horizontal parts of the arcs must lie along the baseline (i.e.,
%       half the line must be above the baseline, and half must be below).
%       This is consistent with the horizontal rules used in the diagram.
%
% \item The vertical parts must overlap vertical rules on either side, so
%       that a |\vrule\sd@|\textit{xx}|circ| makes the arc appear to be
%       a real curve in the line.  The requirements are actually somewhat
%       inconsistent; for example, the \env{stack} environment uses curves
%       \emph{before} the |\vrule|s.  Special requirements like this are
%       handled as special cases later.
%
% \item The height and width of the arc are at least roughly correct.
%
% \end{itemize}
%
%    \begin{macrocode}
\def\sd@tlcirc{{%
  \sd@circ3%
  \ht\tw@\sdrulewidth%
  \dp\tw@.5\sdcirclediam%
  \kern-\tw@\sdrulewidth%
  \raise\sd@mid\box\tw@%
  \kern.5\sdcirclediam%
}}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\sd@trcirc{{%
  \sd@circ0%
  \ht\tw@\sdrulewidth%
  \dp\tw@.5\sdcirclediam%
  \kern.5\sdcirclediam%
  \raise\sd@mid\box\tw@%
}}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\sd@blcirc{{%
  \sd@circ2%
  \ht\tw@.5\sdcirclediam%
  \dp\tw@\sdrulewidth%
  \kern-\tw@\sdrulewidth%
  \raise\sd@mid\box\tw@%
  \kern.5\sdcirclediam%
}}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\sd@brcirc{{%
  \sd@circ1%
  \ht\tw@.5\sdcirclediam%
  \dp\tw@\sdrulewidth%
  \kern.5\sdcirclediam%
  \raise\sd@mid\box\tw@%
}}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\sd@nocirc{\sd@rule\hskip.5\sdcirclediam\relax}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\sd@llc}
% \begin{macro}{\sd@rlc}
%
% In the \env{rep} environment, we need to be able to draw arcs with
% horizontal lines running through them.  The two macros here do the job
% nicely.  |\sd@llc| (which is short for left overlapping circle) is
% analogous to |\llap|: it puts its argument in a box of zero width, sticking
% out to the left.  However, it also draws a rule along the baseline.  This
% is important, as it prevents text from overprinting the arc.  |\sd@rlc|
% is very similar, just the other way around.
%
%    \begin{macrocode}
\def\sd@llc#1{%
  \hb@xt@.5\sdcirclediam{%
    \sd@rule\hskip.5\sdcirclediam%
    \hss%
    #1%
  }%
}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\sd@rlc#1{%
  \hb@xt@.5\sdcirclediam{%
    #1%
    \hss%
    \sd@rule\hskip.5\sdcirclediam%
  }%
}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
%
% \subsubsection{Drawing rules}
%
% It's important to draw the rules \emph{along} the baseline, rather than
% above it: hence, the depth of the rule must be equal to the height.
%
% \begin{macro}{\sd@rule}
%
% We use rule leaders instead of glue through most of the syntax diagrams.
% The command \syntax{"\\sd@rule"<skip>} draws a rule of the correct
% dimensions, which has the behaviour of an \syntax{"\\hskip"<skip>}.
%
%    \begin{macrocode}
\def\sd@rule{\leaders\hrule\@height\sd@upper\@depth\sd@lower}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@gap}
%
% The gap between elements is added using this macro.  It will allow a
% line break if we're at the top level of the diagram, using a rather
% strange discretionary.
%
% This is called as \syntax{"\\sd@gap{"<skip-register>"}"}.
%
%    \begin{macrocode}
\def\sd@gap#1{%
%    \end{macrocode}
%
% First, we see if we're at the top level.  Within constructs, we avoid the
% overhead of a |\discretionary|.  We put half of the width of the skip on
% each side of the discretionary break.
%
%    \begin{macrocode}
  \ifsd@left%
    \ifsd@base%
      \skip@#1%
        \divide\skip\z@\tw@%
      \nobreak\sd@rule\hskip\skip@%
      \discretionary{%
        \sd@qarrow{->}%
      }{%
        \hbox{%
          \sd@qarrow{>-}%
          \sd@rule\hskip\sdstartspace%
          \sd@rule\hskip3.5\p@%
        }%
      }{%
      }%
      \nobreak\sd@rule\hskip\skip@%
%    \end{macrocode}
%
% If we're not at the base level, we just put in a rule of the correct
% width.
%
%    \begin{macrocode}
    \else%
      \sd@rule\hskip#1%
    \fi%
  \fi%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@qgap}
% \begin{macro}{\sd@dequeue}
%
% This is the high-level interface to spacing in syntax diagrams.  Stuff only
% gets printed if the diagram's actually started yet, and hasn't finished.
%
%    \begin{macrocode}
\def\sd@qgap#1{%
  \ifsd@left%
    \ifsd@right\advance\sd@qskip#1\relax%
    \else\sd@gap#1\fi%
  \fi%
}
\def\sd@dequeue{\ifsd@left\sd@gap\sd@qskip\sd@qskip\z@\fi}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
%
% \begin{macro}{\sd@abbrev}
%
% Sets up syntax diagram abbreviations.
%
%    \begin{macrocode}
\def\sd@abbrev{%
  \def\({\begin{stack}}%
  \def\){\end{stack}}%
  \def\<{\begin{rep}}%
  \def\>{\end{rep}}%
  \expandafter\def%
    \csname\ifx\gr@leftsq\@@undefined[\else gr@leftsq\fi\endcsname%
    {\begin{stack}\\}%
  \expandafter\let%
    \csname\ifx\gr@rightsq\@@undefined]\else gr@rightsq\fi\endcsname%
    \)%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{The \protect\env{syntdiag} environment}
%
% All syntax diagrams are contained within a \env{syntdiag} environment.
%
% \begin{environment}{syntdiag}
%
% The only argument is a collection of declarations, which by
% default is
%
% \begin{listing}
%\sdsize\sdlengths
% \end{listing}
%
% However, if the optional argument is not specified, \TeX\ reads the first
% character of the environment, which may not be catcoded correctly.  We set
% up the catcodes first, using the |\syntaxShortcuts| command, and then read
% the argument.  We don't use |\newcommand|, because that would involve
% creating yet \emph{another} macro.  Time to fiddle with |\@ifnextchar|
% \dots
%
%    \begin{macrocode}
\def\syntdiag{%
  \syntaxShortcuts\sd@tok@i\sd@tok@ii%
  \sd@abbrev%
  \@ifnextchar[\syntdiag@i{\syntdiag@i[]}%
}
\def\syntdiag@i[#1]{\@ifnextchar[{\syntdiag@ii{#1}}{\syntdiag@ii{#1}[b]}}
%    \end{macrocode}
%
% Now we actually do the job we're meant to.
%
%    \begin{macrocode}
\def\syntdiag@ii#1[#2]{%
%    \end{macrocode}
%
% The first thing to do is execute the user's declarations.  We then set
% up things for the font size.
%
%    \begin{macrocode}
  \sdsize\sdlengths%
  #1%
  \sd@setsize%
%    \end{macrocode}
%
% Sort out the omission of left or right sides.
%
%    \begin{macrocode}
  \sd@lefttrue\sd@righttrue%
  \if#2l\sd@rightfalse\fi%
  \if#2r\sd@leftfalse\fi%
%    \end{macrocode}
%
% Next, we start a list, to change the text layout.
%
%    \begin{macrocode}
  \list{}{%
    \leftmargin\sdindent%
    \rightmargin\leftmargin%
    \labelsep\z@%
    \labelwidth\z@%
  }%
  \item[]%
%    \end{macrocode}
%
% We reconfigure the paragraph format quite a lot now.  We clear
% |\parfillskip| to avoid any justification at the end of the paragraph.
% We also turn off paragraph indentation.
%
%    \begin{macrocode}
  \parfillskip\z@%
  \noindent%
%    \end{macrocode}
%
% Next, we add in the arrows on the beginning of the line, and a bit of
% glue.
%
%    \begin{macrocode}
  \ifsd@left%
    \sd@qarrow{>>-}%
    \nobreak\sd@rule\hskip\sdstartspace%
   \fi%
%    \end{macrocode}
%
% This is the base level of the diagram, so we enable line breaking.
%
%    \begin{macrocode}
  \sd@basetrue%
%    \end{macrocode}
%
% Since the objects being broken are rather large, we enable sloppy line
% breaking.  We also try to avoid page breaks in mid-diagram, by upping the
% |\interlinepenalty|.
%
%    \begin{macrocode}
  \sloppy%
  \interlinepenalty100%
  \hyphenpenalty0%
%    \end{macrocode}
%
% We handle all the spacing within the environment, so we make \TeX\ ignore
% spaces and newlines.
%
%    \begin{macrocode}
  \catcode`\ 9%
  \catcode`\^^M9%
%    \end{macrocode}
%
% We now have to change the behaviour of |\\| to line-break syntax diagrams.
%
%    \begin{macrocode}
  \let\\\sd@newline%
  \ignorespaces%
}
%    \end{macrocode}
%
% When we end the diagram, we just have to add in the final fillskip, and
% double arrow.
%
%    \begin{macrocode}
\def\endsyntdiag{%
  \unskip%
  \ifsd@right%
    \nobreak\sd@rule\hskip\sdmidskip%
    \sd@rule\hskip\sdfinalskip%
    \sd@qarrow{-><}%
  \else%
    \hskip\sdfinalskip%
    \vadjust{}%
  \fi%
  \endlist%
}
%    \end{macrocode}
%
% \end{environment}
%
% \begin{environment}{syntdiag*}
%
% The starred form of \env{syntdiag} typesets a syntax diagram in LR-mode;
% this is useful if you're describing parts of syntax diagrams, for example.
%
% This is in fact really easy.  The first bit which checks for an optional
% argument is almost identical to the non-$*$ version.
%
%    \begin{macrocode}
\@namedef{syntdiag*}{%
  \syntaxShortcuts\sd@tok@i\sd@tok@ii%
  \sd@abbrev%
  \@tempswatrue%
  \@ifnextchar[\syntdiag@s@i{\syntdiag@s@i[]}%
}
%    \end{macrocode}
%
% Handle another optional argument giving the width of the box to fill.
%
%    \begin{macrocode}
\def\syntdiag@s@i[#1]{%
  \@ifnextchar[{\syntdiag@s@ii{#1}}{\syntdiag@s@iii{#1}{\hbox}}%
}
\def\syntdiag@s@ii#1[#2]{%
  \def\@tempa{#2}\def\@tempb{*}%
  \ifx\@tempa\@tempb%
    \@tempswafalse%
    \syntdiag@s@iii{#1}{}%
  \else%
    \syntdiag@s@iii{#1}{\hb@xt@#2}%
  \fi%
}
%    \end{macrocode}
%
% Now to actually start the display.  This is mostly simple.  Just to make
% sure about the LR-ness of the typesetting, I'll put everything in an hbox.
%
%    \begin{macrocode}
\def\syntdiag@s@iii#1#2{%
  \leavevmode%
  #2\bgroup%
%    \end{macrocode}
%
% Now configure the typesetting according to the user's wishes.
%
%    \begin{macrocode}
  \let\@@left\left%
  \let\@@right\right%
  \def\left##1{\def\sd@startarr{##1}}%
  \def\right##1{\def\sd@endarr{##1}}%
  \left{>-}\right{->}%
  \sdsize\sdlengths%
  #1%
  \sd@setsize%
  \let\left\@@left%
  \let\right\@@right%
  \sd@lefttrue\sd@righttrue%
  \ifx\sd@startarr\@empty\sd@leftfalse\fi%
  \ifx\sd@endarr\@empty\sd@rightfalse\fi%
%    \end{macrocode}
%
% Put in the initial double-arrow.
%
%    \begin{macrocode}
  \ifsd@left%
    \sd@qarrow\sd@startarr%
    \sd@rule\hskip\sdmidskip%
  \fi%
%    \end{macrocode}
%
% We're in horizontal mode, so don't bother with linebreaking.
%
%    \begin{macrocode}
  \if@tempswa\sd@basefalse\else\sd@basetrue\fi%
%    \end{macrocode}
%
% Finally, disable spaces and things.
%
%    \begin{macrocode}
  \catcode`\ 9%
  \catcode`\^^M9%
  \ignorespaces%
}
%    \end{macrocode}
%
% Ending the environment is very similar.
%
%    \begin{macrocode}
\@namedef{endsyntdiag*}{%
  \unskip%
  \ifsd@right%
    \sd@rule\hskip\sdmidskip%
    \ifsd@base\else\sd@rule\hskip\sdfinalskip\fi%
    \sd@qarrow\sd@endarr%
  \else%
    \hskip\sdmidskip%
    \ifsd@base\else\hskip\sdfinalskip\fi%
  \fi%
  \egroup%
}
%    \end{macrocode}
%
% \end{environment}
%
% \begin{macro}{\sd@qarrow}
%
% This typesets the various left and right arrows required in syntax
% diagrams.  The argument is one of \syntax{`>>-', `->', `>-' or `-><'}.
%
%    \begin{macrocode}
\def\sd@qarrow#1{%
  \begingroup%
  \lccode`\~=`\<\lowercase{\def~{<}}%
  \hbox{\csname sd@arr@#1\endcsname}%
  \endgroup%
}
\@namedef{sd@arr@>>-}{\sd@rightarr\kern-.5\p@\sd@rightarr\kern-\p@}
\@namedef{sd@arr@>-}{\sd@rightarr\kern-\p@}
\@namedef{sd@arr@->}{\sd@rightarr}
\@namedef{sd@arr@-><}{\sd@rightarr\kern-\p@\sd@leftarr}
\@namedef{sd@arr@...}{$\cdots$}
\@namedef{sd@arr@-}{}
\@namedef{sd@arr@}{}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@newline}
%
% The line breaking within a syntax diagram is controlled by the
% |\sd@newline| command, to which |\\| is assigned.
%
% We support all the standard \LaTeX\ features here.  The line breaking
% involves adding a fill skip and arrow, moving to the next line, adding
% an arrow and a rule, and continuing.
%
%    \begin{macrocode}
\def\sd@newline{\@ifstar{\vadjust{\penalty\@M}\sd@nl@i}\sd@nl@i}
\def\sd@nl@i{\@ifnextchar[\sd@nl@ii\sd@nl@iii}
\def\sd@nl@ii[#1]{\vspace{#1}\sd@nl@iii}
\def\sd@nl@iii{%
  \nobreak\sd@rule\hskip\sdmidskip%
  \sd@rule\hskip\sdfinalskip%
  \kern-3\p@%
  \sd@rightarr%
  \newline%
  \sd@rightarr%
  \nobreak\sd@rule\hskip\sdstartspace%
  \sd@rule\hskip3.5\p@%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{Putting things in the right place}
%
% Syntax diagrams have fairly stiff requirements on the positioning of text
% relative to the diagram's rules.  To help people (and me) to write
% extensions to the syntax diagram typesetting which automatically put things
% in the right place, I provide some simple macros.
%
% \begin{environment}{sdbox}
%
% By placing some text in the \env{sdbox} environment, it will be read into a
% box and then output at the correct height for the syntax diagram.  Note
% that stuff in the box is set in horizontal (LR) mode, so you'll have to use
% a \env{minipage} if you want formatted text.  The macro also supplies rules
% on either side of the box, with a length given in the environment's
% argument.
%
% Macro writers are given explicit permission to use this environment through
% the |\sdbox| and |\endsdbox| commands if this makes life easier.
%
% The calculation in the |\endsdbox| macro works out how to centre the box
% vertically over the baseline.  If the box's height is~$h$, and its depth
% is~$d$, then its centre-line is $(h+d)/2$ from the bottom of the box.
% Since the baseline is already $d$ from the bottom, we need to lower the box
% by $(h+d)/2 - d$, or $h/2-d/2$.
%
%    \begin{macrocode}
\def\sdbox#1{%
  \@tempskipa#1\relax%
  \sd@gap\@tempskipa%
  \setbox\z@\hbox\bgroup%
    \begingroup%
    \catcode`\ 10%
    \catcode`\^^M5%
    \synshortsoff%
}
\def\endsdbox{%
    \endgroup%
  \egroup%
  \@tempdima\ht\z@%
  \advance\@tempdima-\dp\z@%
  \advance\@tempdima-\tw@\sd@mid%
  \lower.5\@tempdima\box\z@%
  \sd@lefttrue%
  \sd@gap\@tempskipa%
}
%    \end{macrocode}
%
% \end{environment}
%
% \subsubsection{Typesetting syntactic items}
%
% Using the hooks built into the syntax abbreviations above, we typeset
% the text into a box, and write it out, centred over the baseline.  A strut
% helps to keep the actual text baselines level for short pieces of text.
%
% \begin{macro}{\sd@tok@i}
%
% The preamble for a syntax abbreviation.  We start a box, and set the
% space and return characters to work again.  A strut is added to the box to
% ensure correct vertical spacing for normal text.
%
%    \begin{macrocode}
\def\sd@tok@i{%
  \sdbox\sdtokskip%
  \strut%
  \space%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@tok@ii}
%
%    \begin{macrocode}
\def\sd@tok@ii{%
  \space%
  \endsdbox%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{Inserting other pieces of text}
%
% Arbitrary text may be put into a syntax diagram through the use of the
% |\tok| macro.  Its `argument' is typeset in the same way as a syntactic
% item (centred over the baseline).  The implementation goes to some effort
% to ensure that the text is not actually an argument, to allow category
% codes to change while the text is being typeset.
%
% \begin{macro}{\tok}
%
% We start a box, and make space and return do their normal jobs.  We use
% |\aftergroup| to regain control once the box is finished.  |\doafter| is
% used to get control after the group finishes.
%
%    \begin{macrocode}
\def\tok#{%
  \sdbox\sdtokskip%
  \strut%
  \enspace%
  \syntaxShortcuts\relax\relax%
  \doafter\sd@tok%
}
%    \end{macrocode}
%
% The |\sd@tok| macro is similar to |\sd@tok@ii| above.
%
%    \begin{macrocode}
\def\sd@tok{%
  \enspace%
  \endsdbox%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{The \protect\env{stack} environment}
%
% The \env{stack} environment is used to present alternatives in a syntax
% diagram.  The alternatives are separated by |\\| commands.
%
% \begin{macro}{\stack}
%
% Handle the optional arguments.
%
%    \begin{macrocode}
\def\stack{\@ifnextchar[\stack@i{\stack@i[t]}}
\def\stack@i[#1]{\@ifnextchar[{\stack@ii{#1}}{\stack@ii{#1}[b]}}
\def\stack@ii#1[#2]{%
%    \end{macrocode}
%
% First, we add some horizontal space.
%
%    \begin{macrocode}
  \sd@gap\sdmidskip%
%    \end{macrocode}
%
% We're within a complex construction, so we need to clear the |\ifsd@base|
% flag.
%
%    \begin{macrocode}
  \begingroup\sd@basefalse%
%    \end{macrocode}
%
% The top and bottom rows of the stack are different to the others, since
% the vertical rules mustn't extend all the way up the side of the item.
% The bottom row is handled separately by |\endstack| below.  The top row
% must be handled via a flag, |\ifsd@toplayer|.
%
% Initially, the flag must be set true.
%
%    \begin{macrocode}
  \sd@toplayertrue%
%    \end{macrocode}
%
% We set the |\\| command to separate the items in the |\halign|.
%
%    \begin{macrocode}
  \let\\\sd@stackcr%
%    \end{macrocode}
%
% Sort out which sides of the construction are actually emitted.
%
%    \begin{macrocode}
  \sd@righttrue\if#2l\sd@rightfalse\fi%
%    \end{macrocode}
%
% The actual structure must be set in vertical mode, so we must place it
% in a box.  The position argument determines whether this must be a
% |\vbox| or a |\vtop|.  We also insert a bit of rounding if the options say
% we must.
%
%    \begin{macrocode}
  \if#1t%
    \let\@tempa\vtop%
    \sd@toptrue%
    \ifsd@left\ifsd@round\llap{\sd@trcirc\kern\tw@\sdrulewidth}\fi\fi%
  \else\if#1b%
    \let\@tempa\vbox%
    \sd@topfalse%
    \ifsd@left\ifsd@round\llap{\sd@brcirc\kern\tw@\sdrulewidth}\fi\fi%
  \else%
    \sd@err{Bad position argument passed to stack}%
           {The positioning argument must be one of `t' or `b'.  I%
            have^^Jassumed you meant to type `t'.}%
    \let\@tempa\vtop%
  \fi\fi%
%    \end{macrocode}
%
% Now we start the box, which we will complete at the end of the environment.
%
%    \begin{macrocode}
  \@tempa\bgroup%
%    \end{macrocode}
%
% We must remove any extra space between rows of the table, since the rules
% will not join up correctly.  We can use |\offinterlineskip| safely, since
% each individual row contains a strut.
%
%    \begin{macrocode}
  \offinterlineskip%
%    \end{macrocode}
%
% Now we can start the alignment.  We actually use \PlainTeX's |\ialign|
% macro, which also clears |\tabskip| for us.
%
%    \begin{macrocode}
  \ialign\bgroup%
%    \end{macrocode}
%
% The preamble is trivial, since we must do all of the work ourselves
%
%    \begin{macrocode}
    ##\cr%
%    \end{macrocode}
%
% We can now start putting the text into a box ready for typesetting later.
% The strut makes the vertical spacing correct.
%
%    \begin{macrocode}
  \setbox\z@\hbox\bgroup%
    \strut%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\endstack}
%
% The first part of this is similar to the |\sd@stackcr| macro below, except
% that the vertical rules are different.  We don't support rounded edges
% on single-row stacks, although this isn't a great loss to humanity.
%
%    \begin{macrocode}
\def\endstack{%
  \ifsd@right\else\unskip\fi%
  \egroup%
  \ifsd@toplayer%
    \sd@dostack\sd@upper\sd@lower\sd@nocirc\sd@nocirc%
  \else%
    \ifsd@round%
      \ifsd@top%
        \sd@dostack{\ht\z@}\sd@botcirc\sd@blcirc\sd@brcirc%
      \else%
        \sd@dostack{\ht\z@}\sd@botcirc\sd@nocirc\sd@nocirc%
      \fi%
    \else%
      \sd@dostack{\ht\z@}\sd@lower\relax\relax%
    \fi%
  \fi%
%    \end{macrocode}
%
% We now close the |\halign| and the vbox we created.
%
%    \begin{macrocode}
  \egroup%
  \egroup%
%    \end{macrocode}
%
% Deal with any rounding we started off.
%
%    \begin{macrocode}
  \ifsd@right\ifsd@round%
    \ifsd@top
      \rlap{\kern\tw@\sdrulewidth\sd@tlcirc}%
    \else%
      \rlap{\kern\tw@\sdrulewidth\sd@blcirc}%
    \fi%
  \fi\fi%
%    \end{macrocode}
%
% Finally, we add some horizontal glue to space the diagram out.
%
%    \begin{macrocode}
  \endgroup\sd@lefttrue\ifsd@right\sd@gap\sdmidskip\fi%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@stackcr}
%
% The |\\| command is set to this macro during a \env{stack} environment.
%
%    \begin{macrocode}
\def\sd@stackcr{%
%    \end{macrocode}
%
% The first job is to close the box containing the previous item.
%
%    \begin{macrocode}
  \ifsd@right\else\unskip\fi%
  \egroup%
%    \end{macrocode}
%
% Now we typeset the vertical rules differently depending on whether this is
% the first item in the stack.  This looks quite terrifying initially, but
% it's just an enumeration of the possible cases for the different values
% of |\ifsd@toplayer|, |\ifsd@top| and |\ifsd@round|, putting in appropriate
% rules and arcs in the right places.
%
%    \begin{macrocode}
  \ifsd@toplayer%
    \ifsd@round%
      \ifsd@top%
        \sd@dostack\sd@topcirc{\dp\z@}\sd@nocirc\sd@nocirc%
      \else%
        \sd@dostack\sd@topcirc{\dp\z@}\sd@tlcirc\sd@trcirc%
      \fi%
    \else%
      \sd@dostack\sd@upper{\dp\z@}\relax\relax%
    \fi%
  \else%
    \ifsd@round%
      \ifsd@top%
        \sd@dostack{\ht\z@}{\dp\z@}\sd@blcirc\sd@brcirc%
      \else%
        \sd@dostack{\ht\z@}{\dp\z@}\sd@tlcirc\sd@trcirc%
      \fi%
    \else%
      \sd@dostack{\ht\z@}{\dp\z@}\relax\relax%
    \fi%
  \fi%
%    \end{macrocode}
%
% The next item won't be the first, so we clear the flag.
%
%    \begin{macrocode}
  \sd@toplayerfalse%
%    \end{macrocode}
%
% Now we have to set up the next cell.  We put the text into a box again.
%
%    \begin{macrocode}
  \setbox\z@\hbox\bgroup%
    \strut%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@dostack}
%
% Actually typesetting the text in a cell is performed here.  The macro is
% called as
% \begin{quote}\synshorts
% "\\sd@dostack{"<height>"}{"<depth>"}{"<left-arc>"}{"<right-arc>"}"
% \end{quote}
% where \<height> and \<depth> are the height and depth of the vertical
% rules to put around the item, and \<left-arc> and \<right-arc> are
% commands to draw rounded edges on the left and right hand sides of the
% item.
%
% The values for the height and depth are quite often going to be the height
% and depth of box~0.  Since we empty box~0 in the course of typesetting the
% row, we need to cache the sizes on entry.
%
%    \begin{macrocode}
\def\sd@dostack#1#2#3#4{%
  \@tempdima#1%
  \@tempdimb#2%
  \ifsd@left%
    \kern-\tw@\sdrulewidth%
    \vrule\@height\@tempdima\@depth\@tempdimb\@width\tw@\sdrulewidth%
    #3%
    \sd@rule\hfil%
    \sd@gap\sdtokskip%
  \else%
    \hfill%
  \fi%
  \unhbox\z@%
  \ifsd@right%
    \sd@gap\sdtokskip%
    \sd@rule\hfil%
    #4%
    \vrule\@height\@tempdima\@depth\@tempdimb\@width\tw@\sdrulewidth%
    \kern-\tw@\sdrulewidth%
  \else%
    \hfill%
  \fi%
  \cr%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsubsection{The \protect\env{rep} environment}
%
% The \env{rep} environment is used for typesetting loops in the diagram.
% Again, we use |\halign| for the typesetting.  Loops are simpler than
% stacks, however, since there are always two rows.  We store both rows in
% box registers, and build the loop at the end.
%
% \begin{macro}{\rep}
%
% Again, we use |\newcommand| to process the optional argument.
%
%    \begin{macrocode}
\newcommand\rep[1][t]{%
%    \end{macrocode}
%
% First, leave a gap on the left side.
%
%    \begin{macrocode}
  \sd@gap\sdmidskip%
%    \end{macrocode}
%
% We're not at base level any more, so disable linebreaking.
%
%    \begin{macrocode}
  \begingroup\sd@basefalse%
%    \end{macrocode}
%
% Remember we're going backwards now.
%
%    \begin{macrocode}
  \ifsd@backwards\sd@backwardsfalse\else\sd@backwardstrue\fi%
%    \end{macrocode}
%
% Define |\\| to separate the two parts of the loop.
%
%    \begin{macrocode}
   \let\\\sd@loop%
%    \end{macrocode}
%
% Now check the argument, and use the appropriate type of box.  In addition
% to changing the typesetting, we must remember which way up to typeset the
% loop, since the end code must always put the first argument on the
% baseline, with the loop either above or below.
%
%    \begin{macrocode}
  \if#1t%
    \let\@tempa\vbox%
    \sd@toptrue%
  \else\if#1b%
    \let\@tempa\vtop%
    \sd@topfalse%
  \else%
    \sd@err{Bad position argument passed to loop}%
           {The positioning argument must be `t' or `b'.  I have^^J%
            assumed you meant to type `t'.}%
    \let\@tempa\vbox%
    \sd@toptrue%
  \fi\fi%
%    \end{macrocode}
%
% Now we start the box.
%
%    \begin{macrocode}
  \@tempa\bgroup%
%    \end{macrocode}
%
% The loop is by default empty, apart from a strut.  This is put into box~1.
%
%    \begin{macrocode}
  \setbox\tw@\copy\strutbox%
%    \end{macrocode}
%
% Now start typesetting the main text in box~0.
%
%    \begin{macrocode}
  \setbox\z@\hbox\bgroup\strut%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\endrep}
%
% The final code must first close whatever box was open.
%
%    \begin{macrocode}
\def\endrep{%
  \egroup%
%    \end{macrocode}
%
% Now we typeset the loop, depending on which way up it was meant to be.
% Again, this terrifying piece of code is a simple list of possibile values
% of our various flags.
%
%    \begin{macrocode}
  \ifsd@top%
    \ifsd@round%
      \sd@doloop\tw@\z@\relax\relax%
        \sd@tlcirc\sd@trcirc{\sd@rlc\sd@blcirc}{\sd@llc\sd@brcirc}%
    \else%
      \sd@doloop\tw@\z@\relax\sd@downarr\relax\relax\relax\relax%
    \fi%
  \else%
    \ifsd@round%
      \sd@doloop\z@\tw@\relax\relax%
        {\sd@rlc\sd@tlcirc}{\sd@llc\sd@trcirc}\sd@blcirc\sd@brcirc%
    \else%
      \sd@doloop\z@\tw@\sd@uparr\relax\relax\relax\relax\relax%
    \fi%
  \fi%
%    \end{macrocode}
%
% Close the vbox we opened.
%
%    \begin{macrocode}
  \egroup%
%    \end{macrocode}
%
% Finally, we leave a gap before the next structure.
%
%    \begin{macrocode}
  \endgroup\sd@gap\sdmidskip%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@loop}
%
% This macro handles the |\\| command within a loop environment.  We close
% the current box, and start filling in box~1.  We also redefine |\\| to
% raise an error when the |\\| command is used again.
%
%    \begin{macrocode}
\def\sd@loop{%
  \egroup%
  \def\\{\sd@err{Too many \string\\\space commands in loop}\@ehc}%
  \setbox\tw@\hbox\bgroup\strut%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@doloop}
%
% This is the macro which actually creates the |\halign| for the loop.  It
% is called with four arguments, as:
% \begin{quote}\synshorts
% "\\sd@doloop{"<top-box>"}{"<bottom-box>"}"^^A
%                "{"<top-arrow>"}{"<btm-arrow>"}" \\
% \hbox{}\quad "{"<top-left-arc>"}{"<top-right-arc>"}"^^A
%                "{"<bottom-left-arc>"}{"<btm-right-arc>"}"^^A
% \kern-1in ^^A It may be overfull, but it looks OK to me ;-)
% \end{quote}
%
% The two \<box> arguments give the numbers of boxes to extract in the top
% and bottom rows of the alignment.  The \<arrow> arguments specify
% characters to typeset at the end of the top and bottom rows for arrows.
% The various \<arc> arguments are commands which typeset arcs around the
% various parts of the items.
%
% We calculate the height and depth of the two boxes, and store them in
% \<dimen> registers, because the boxes are emptied before the right-hand
% rules are typeset.
%
% Actually, the two rows of the alignment are typeset in a different macro:
% we just pass the correct information on.
%
%    \begin{macrocode}
\def\sd@doloop#1#2#3#4#5#6#7#8{%
  \@tempdima\dp#1\relax%
  \@tempdimb\ht#2\relax%
  \offinterlineskip%
  \ialign{%
    ##\cr%
    \ifsd@round%
      \sd@doloop@i#1#3\sd@topcirc\@tempdima{#5}{#6}%
      \sd@doloop@i#2#4\@tempdimb\sd@botcirc{#7}{#8}%
    \else%
      \sd@doloop@i#1#3\sd@upper\@tempdima{#5}{#6}%
      \sd@doloop@i#2#4\@tempdimb\sd@lower{#7}{#8}%
    \fi%
  }%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sd@doloop@i}
%
% Here we do the actual job of typesetting the rows of a loop alignment.
% The four arguments are:
% \begin{quote}\synshorts
% "\\sd@doloop@i{"<box>"}{"<arrow>"}"^^A
%              "{"<rule-height>"}{"<rule-depth>"}" \\
% \hbox{}\quad "{"<left-arc>"}{"<right-arc>"}"^^A
% \end{quote}
%
% The arrow position is determined by the |\ifsd@backwards| flag.  The rest
% is fairly simple.
%
%    \begin{macrocode}
\def\sd@doloop@i#1#2#3#4#5#6{%
  \ifsd@backwards#2\fi%
  \kern-\tw@\sdrulewidth%
  \vrule\@height#3\@depth#4\@width\tw@\sdrulewidth%
  #5%
  \sd@rule\hfill%
  \sd@gap\sdtokskip%
  \unhbox#1%
  \sd@gap\sdtokskip%
  \sd@rule\hfill%
  #6%
  \vrule\@height#3\@depth#4\@width\tw@\sdrulewidth%
  \ifsd@backwards\else#2\fi%
  \kern-\tw@\sdrulewidth%
  \cr%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsection{The end}
%
% Phew!  That's all of it completed.  I hope this collection of commands
% and environments is of some help to someone.
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \hfill Mark Wooding, \today
%
% \Finale
%
\endinput