forth.tex

\documentclass[10pt,letterpaper]{book}
%\setlength\overfullrule{5pt}	% Draft
%\usepackage{a4wide}
%\includeonly{titlepage,foreword,foreword-ans,process,members-2x}
%\includeonly{intro,notation,usage,doc,label}
%\includeonly{core}%,block,double,exception,facility,file,float}
%\includeonly{locals,memory,tools,search,string,xchar}
%\includeonly{rationale,bib,history,diff,port,implement,testsuite}
%\includeonly{process2018}

% ========== Page Size ==========
% (taken from a4wide.sty, but now applied to US Letter Paper)

    \oddsidemargin		0.15 in 	% Left margin on odd-numbered pages.
    \evensidemargin	0.35 in 	% Left margin on even-numbered pages.
    \marginparwidth	1 in		% Width of marginal notes.
    \oddsidemargin		0.25 in 	% Note that \oddsidemargin = \evensidemargin
    \evensidemargin	0.25 in
    \marginparwidth	0.75 in
    \textwidth			5.875 in	% Width of text line.

% ========== Document Organisation Flags ==========

\newif\ifinline			% Inline Rationale glossary matter
\newif\ifshowref		% Display Cross Reference labels
\newif\ifrelease		% Draft/Release version
\input{config}

% =================================================

% Tell LaTeX to record a list of all the files
%\listfiles

% To Do
%
% Get rid of labels
% code environment
% auto xref ambiguous conditions
% add \log to History / Change Log

%\usepackage{supertabular}
\usepackage{graphicx}
\usepackage{randtext}	% Randamize text (for email addresses)


% ========== Subtables ==========
%\usepackage{float}
%\floatstyle{plaintop}
%\newfloat{subtable}{hbtp}{lot}[table]
%\floatname{subtable}{Table}
%\renewcommand{\thesubtable}{\thetable \alph{subtable}}
% ====================


% ========== Remember Include Filename  ==========

% Patch the \include command to remember the current include
% filename.

\makeatletter

% Define a blank file name to start with
\def\includefile{}

% Make a note of the original version of \include
\let\forth@include=\include

% Define a our new version
\renewcommand{\include}[1]{%
	\IfFileExists{#1.tex}{%
		\gdef\includefile{#1}%	Remember the filename
		\forth@include{#1}%		Include it
	}{%
		\@latex@error{File "#1.tex" Not Found!}\@ehc
	}
}

% ========== Page Header / Footer ==========

\usepackage{fancyhdr}
\pagestyle{fancy}

\makeatletter
\newcommand{\docversion}{%
	\revision
	\ifinline
		\textit{r}%		word Rationale only
	\fi%
	\ifshowref
		\textit{x}
	\fi
}

\makeatother

\ifrelease
	\lhead[\leftmark]{Forth \snapshot{} \release}
	\rhead[Forth \snapshot{} \release]{\leftmark}
\else
	\lhead[\leftmark]{Forth 200\emph{x} / \docversion}
	\rhead[Forth 200\emph{x} / \docversion]{\leftmark}
\fi
\ifrelease
	\lfoot[\rm\thepage]{}
	\rfoot[]{\rm\thepage}
\else
	\lfoot[\rm\thepage]{\sf\small\includefile}
	\rfoot[\sf\small\includefile]{\rm\thepage}
\fi
\cfoot{}
\renewcommand{\footrulewidth}{0.4pt}
\newcommand{\collate}{%
	! `` \# \$ \% \& ' ( ) * + , - . / digits : ; $<$ = $>$
	? @ ALPHA [ \bs{} ] \^{} \_ ` alpha \{ | \} \tilde}

% ==========================================


% ========== Deferred Placement ==========


\usepackage{answers}

% The answerfile switch controls the use of deferred text.
% Turning it on will allow text to be exported to a "solution"
% file, while turning it off will simply place the text in line.

\ifinline
	\answerfilesfalse
\else
	\answerfilestrue
\fi

% =======================================


% ========== Change Log / History =========

\usepackage{history}
%\openhistory

% =========================================


% ========== PostScript Fonts ==========

\usepackage[T1]{fontenc}
\usepackage[safe,warn]{textcomp}

\usepackage{mathptmx}			% Times for roman and formula
%\usepackage{avant}				% Avant Guard for sans-serif
\usepackage[scaled=.88]{helvet}	% Helvetica for sans-serif
\usepackage{courier}			% Courier for teletype

% ======================================
\usepackage{xcolor}
\usepackage[colorlinks,
	linkcolor = red,
	urlcolor  = red,
	citecolor = blue,
	anchorcolor = blue,
%	linkbordercolor=blue,
%	pdfborderstyle={/S/U/W 1},
	pageanchor=false,
	pdfpagelabels=false,
	breaklinks=true]{hyperref}


% ========== Block Paragraphs ==========

\usepackage{parskip}

% ======================================

\makeatletter

% ========== Word Glossary ==========

% .wrd	the list of raw (unsorted) word entries
% .wds	the sorted list of word entries.
%
% Note that this requires an external program (sort.pl) to sort
% the entries.

\newwrite\wordfile
\immediate\openout\wordfile=\jobname.wrd

% Note the "core" wordlist chapter so we can handle this as a
% special case. Of particular interest to worddef and wref.

\newcounter{word@core}
\setcounter{word@core}{6}

% "Normal" or "Extended" wordset
\newif\if@ext

\newcommand{\extended}{%
	\@exttrue
	\label{wordlist:\word@list-ext}
}

\newcommand{\setwordlist}[1]{%
	\gdef\word@list{#1}
}
\setwordlist{core}

\newcommand{\wordlist}[1]{%
	\gdef\word@list{#1}		% Set the current wordlist
	\@extfalse				% Core wordset, non-extended wordlist
	\label{wordlist:#1}		% Label the wordlist, just in case
	\chaptermark{\MakeUppercase{#1} Word Set}	% Set the page heading
	%
	% Set up a file ready for the deferred text
	%
	\ifanswerfiles
		\Closesolutionfile{rationale}
		\Closesolutionfile{testing}
		\Closesolutionfile{implementation}

		\Opensolutionfile{rationale}[r-#1]
		\Opensolutionfile{testing}[t-#1]
		\Opensolutionfile{implementation}[i-#1]
	\fi
}

% ===================================

% The following environment define a glossary entry of a word.
% It has two mandatory arguments and three optional ones.
%
% \begin{worddef*}[<label>]{<number>}[<sub-number>]{<name>}[<english>][<proposal>]
%
% <label>	Is the LaTeX label given to the word. It is used when
%			processing links, and should not include any non alphanumeric
%			characters. This is the label by which the word in known to the
%			LaTeX system, and the name which should should be used in
%			the \word{<label>} and \wref{<label>} commands.
%			Default: <name> is assumed to be the label.
%
% <number>	The word's number in the alphabetical listing of words.
%			This should be the full four digit number.
%
% <sub-number>
%			The Forth200x standard requires we add new words between
%			existing words. I.e., a new word between 0124 and 0125,
%			we can only archive this by further dividing the number
%			with a two digit sub-number.
%			Default: None.
%
% <name>	This is the display name of the word. It is typeset in
%			standard LaTeX.
%
% <english>	Is the english pronunciation of the word.
%			Default: None.
%
% <proposal>
%			The name of the proposal which introduced this word. All
%			words introduced by Forth 200x should have a proposal.
%			Default: None.
%
% The stared version of worddef, adds change bars to the output. This
% is used to introduce a new word into the standard for the first time.
%
% The worddef environment will automatically generate an index entry
% for the word.
%
% The following commands are provided to aid the word definition:
%
% \compile			Compilation time semantics
% \execute[<type>]	Execution semantics, with a given <type>
% \init				Initiation
% \interpret		Interpretation semantics
% \note[<number>]	Note with an optional <number>
% \runtime[<type>]	Run-time semantics, with a given <type>
% \see				Reference to other words (See)
%
% \item[<name>]		None standard section "<name>:"
%
% \param{<stack item>}
%		Type set <stack item> according to the notation rule.
%		See the definition of \param for the rules.
%
% \stack[<stack>]{<before>}{<after>}
%		Type set a stack picture according to the same notation
%		rules as used form \param.
%
% All text which should appear in one of the appendices in the
% final document must appear within the associated environment.
% This allows the text to be shipped out to a separate .sub support
% file, when inlineing is disabled (\ifinline is false).
%
% \begin{rationale} ... \end{rationale}
% \begin{testing}   ... \end{testing}
%   \test[<format>]{<pre>}{<post>}	A test case
% \begin{implement} ... \end{implement}

% ==== worddef ====

% Unfortunately, LaTeX does not provide an easy way of identifying
% more than one optional arguments. The worddef environment, calls
% on a chain of intermediate macros (word@def@a, word@def@b, and
% so on) to extract each of the optional parameters, one at a time.
% They define a number of macros:
%
% \if@star		True if the change bar is required (worddef*)
% \word@label	LaTeX label for the word, for use in \word{} or \wref{}
% \word@num		the four digit number
% \word@sub		the two digit sub-division number
% \word@name	the name of the word being defined
% \word@read	the english pronunciation / reading of the word name
% \word@prop	Proposal which introduced the new definition
%
% In addition to these macros we also have two global macros:
%
% \word@list	name of the current word list
% \if@ext		true if in extended word list

% Before we start, we define a error reporting macro which identifies
% both the word and the word list in which the error was found

\newcommand{\word@error}[1]{%
	\@latex@error{%
		In \ifnum\value{word@core}=\value{chapter}\thesection\else\thesubsection\fi
		\ifx\word@num\empty .----\else.\word@num\fi
		\ifx\word@sub\empty\else .\word@sub\fi
		\space
		"\word@name" of wordset "\word@list" \MessageBreak
		#1}\@ehc
}

\newif\if@star
\newenvironment{worddef}{\@starfalse\word@def@a}{\word@def@end}
\newenvironment{worddef*}{\@startrue\word@def@a}{\word@def@end}

% So we must start by processing the first two parameters:
% <label> and <number>. Defines the macros:
% \word@label	\empty or the text label
% \word@num		\empty or the four digit number

\newcommand{\word@def@a}[2][\empty]{% [<label>]{<number>}...
	\ifx#1\empty\let\word@label=\empty\else\def\word@label{#1}\fi
	\def\word@num{#2}
	\word@def@b
}

% Now we process the second pair of parameters: <sub-number> and
% <name>.  So we define (or redefine) the macros:
% \word@label	if \word@label is \empty this is redefined to <name>
% \word@sub		the two digit sub-division number
% \word@name	the name of the word being defined

% For some reason I have yet to work out, this treats numbers with
% duplicate digits (such as 11, 22, 33, and so on) an empty.  Thus
% the use of a magic number (100) to signify an empty sub-number,
% as the maximum sub-number should only be 99, this should be sufficient.

\newcommand{\word@def@b}[2][100]{% ...[<sub-number>]{<name>}...
	\ifnum#1<100\def\word@sub{#1}\else\let\word@sub=\empty\fi
	\ifx\word@label\empty\def\word@label{#2}\fi
	\def\word@name{#2}
	\word@def@c
}

% Now we can process the next optional parameter: <english>
% Note that if the word has a <proposal> parameter, the
% <english> parameter is required.
% Rather surprisingly this defines a new macro:
% \word@read	the english pronunciation / reading of the word name

\newcommand{\word@def@c}[1][\empty]{% ...[<english>]...
	\ifx#1\empty\let\word@read=\empty\else\def\word@read{#1}\fi
	\word@def@d
}

% Finally we can process the final optional parameter: <proposal>
% Note that all additions to the ANS Forth standard require the
% <proposal> parameter. Thus a new word which has a <proposal> but
% not a separate english pronunciation, MUST provide an empty
% pronunciation parameter. This macro defines the new macro:
% \word@prop	Proposal which introduced the new definition

\newcommand{\word@def@d}[1][\empty]{% ...[<proposal>]
	\ifx#1\empty\let\word@prop=\empty\else\def\word@prop{#1}\fi
%	\word@def@test
	\word@def@begin
}

% Now we have collected all of the parameters we can start the word
% definition.  We break this into separate sections, first we generate
% the word index entry (\word@def@index) then the word's banner in the
% glossary (\word@def@head), and finally we set up the environment for
% the text of the definition itself (\word@def@body).
% However, before we do any of this, we ensure that all new words have
% a proposal attached. 

\newcommand{\word@def@begin}{%
	\typeout{%
		\ifx\empty\word@num----\else\word@num\fi
		\ifx\empty\word@sub\space\space\space\else.\word@sub\fi
		\space\includefile:\word@label}
	\ifx\empty\word@prop
		% No proposal - word must be from ANS Forth '94
		\if@star
			% We have a new word without a proposal?
			\word@error{New words MUST have a proposal}
		\fi
	\fi
	\word@def@index
	\word@def@head
	\word@def@body
}

% Write the index entry for the word, based on our collected macros

\newcommand{\word@def@index}{%
	\immediate\write\wordfile{\string\indexentry%
		\if@star*\fi%			* = Changebar
		\ifnum\value{word@core}=\value{chapter}{\thesection}\else{\thesubsection}\fi%	1: <section>
		{\word@num}%			2: <number>
		{\word@sub}%			3: <sub number>
		{\word@name}%			4: <name>
		{\word@list}%			5: <wordlist>
		{\if@ext\space EXT\fi}%	6: <ext>
		{\word@prop}%			7: <proposal>
		{\word@label}%			8: <label>
		{\word@read}%			9: <english>
	}
}

% Show the macros, used for debugging

\newcommand{\word@def@test}{%
	\begin{tabular}{rl}
		Change bar:	& \if@star On\else Off\fi \\
		Section:	& \ifnum\value{word@core}=\valign{chapter}\thesection\else\thesubsection\fi \\
		Number:		& \word@num \\
		Sub Number:	& \word@sub \\
		Name:		& \word@name \\
		Wordlist:	& \word@list~\if@ext EXT\fi \\
		Proposal:	& \word@prop \\
		Label:		& \word@label \\
		English:	& \word@read \\
	\end{tabular}\par
}

% ==== Word Header ====
%
% Generate the word header based on the macros collected

\newcommand{\word@def@head}{%
	\ifx\word@prop\empty\else
	\fi
	%
	% This is a good place to start a new page
	%
	\pagebreak[3]
	%
	% Define the hyper target before the glossary entry
	% So that a hyperlink will show the glossary line
	%
	\hyperdef{\word@list}{\word@label}{}
	%
	% Word number and name
	%
%\@tempswbfalse
%\ifrelease\else
%	\ifx\empty\word@prop\else
%		\cbstart\marginpar{\tiny{\color{white}c:b}}
%		\@tempswbtrue
%	\fi
%\fi
	\makebox[0.5\textwidth][l]{%
		\makebox[6.0em][l]{% <== Magic Number, width of section number
			% Switch to a bold font
			\bfseries\sffamily
			%
			% Current section or subsection
			%
			\ifnum\value{word@core}=\value{chapter}
				% In the core wordset
				\thesection
			\else
				% In all other word sets
				\thesubsection
			\fi
			%
			% Word number
			%
			\ifx\empty\word@num
				% No word number given
				.\rule[.8ex]{2em}{.5pt}
			\else%
%\if@tempswb%
%				\uline{.\word@num}%
%\else%
				.\word@num%
%\fi%
			\fi%
			%
			% Sub division
			%
			\ifx\word@sub\empty
				~% No sub division
			\else
%\if@tempswb
%				\uline{.\word@sub}
%\else
				.\word@sub
%\fi
			\fi
		}
		%
		% Word Name
		%
		%\mdseries	% Back to a medium weight (normal) font
		\texttt{\textbf{\word@name}}
	}
%\if@tempswb
%		\cbend
%\fi
	%
	% English pronunciation (if given)
	%
	\ifx\word@read\empty
		% No english pronunciation given
	\else
		``\word@read''
	\fi
	%
	% Wordlist
	%
	\hfill
	\MakeUppercase{\word@list}
	\if@ext EXT\fi
	%
	% Cross Reference
	%
	\ifshowref%
		\ifx\word@label\word@name
			% Word label is the word name
		\else
			% Label is different to name
			\hbox to 0pt{\textsf{\small ~~\word@label}}
		\fi
	\fi%
	%
	% Start change bar
	%
	\if@star%
		\cbstart\patch{\word@prop}%
	\fi%
	%
	% Proposal
	%
	\\*[-0.6ex]
	\ifx\word@prop\empty
		% No proposal - word must be from ANS Forth '94
	\else
		\ifrelease\else
			\mbox{} \hfill	% flush right (under the wordset name)
			\textsf{\small \word@prop}
		\fi
	\fi
	%
	% Define the label for this word
	%
	\def\@currentlabel{%
		\ifnum\value{word@core}=\value{chapter}\thesection\else\thesubsection\fi%
		\ifx\empty\word@num .0\else.\word@num\fi%
		\ifx\empty\word@sub\else .\word@sub\fi
	}%
	\edef\@currentlabelname{\word@name}%
	\def\@currentHref{\word@list.\word@label}%
	\label{\word@list:\word@label}%
	%
	% End the header
	%
	\if@star\else
		\ifx\word@prop\empty\else\cbend\fi % Draft
	\fi
	\\*[-1.5\baselineskip]
	%
	% This is a very bad place for a page break
	%
	\pagebreak[0]
}

% ==== Word Body ====
%
% Define the macro which will be used to format items within the word
% definition. We right align the text which is output with a trailing
% colon.

\newcommand{\word@item}[1]{%
	\hfil
	\ifx#1\else #1:\fi
}

% For the main body of the definition we use a "simple" list
% environment. We need only set up the margins for environment.

\newcommand{\word@def@body}{
	\begin{list}{}{
		\setlength{\labelwidth}{6.8em}		% <== Magic number, width of indent
		\setlength{\leftmargin}{\labelwidth}
		\addtolength{\leftmargin}{\labelsep}
		\renewcommand{\makelabel}{\word@item}
	}
}

% ==== Word Footer ====
%
% This cleans up after the header and body

\newcommand{\word@def@end}{%
	%
	% Extend the normal "missing \item" error message to
	% tell us which word is in error.
	%
	\def\@noitemerr{\word@error{Something wrong here --- perhaps a
		missing \string\item}}
	%
	% End the list started by \word@def@body
	%
	\end{list}
	%
	% End the change bar, if it was enabled
	%
	\if@star\cbend\fi%
	%
	% Leave some extra space after the list
	%
	\vspace{3ex}
	%
	% This would be a fairly good place for a page break
	%
	\par\pagebreak[3]
}

% ==== Word Sections ====

% Define the sections found within a glossary entry.

\newcommand{\compile}{\samepage\item[Compilation]}
\newcommand{\execute}[1][\empty]{%
	\pagebreak[3]
	\ifx#1\empty
		\item[Execution]
	\else
		\item[\emph{#1} Execution]
	\fi
}
\newcommand{\init}{\samepage\item[Initiation]}
\newcommand{\interpret}{\samepage\item[Interpretation]}
\newcommand{\note}[1][\empty]{\item[Note\ifx#1\empty\else\ #1\fi]}
\newcommand{\runtime}[1][]{\pagebreak[3]\item[#1 Run-time]}
\newcommand{\see}{\samepage\item[See]}


% ==== Stack Descriptions ====

% Okay, we are going for some very nasty low level TeX here.
% Check out the actionarg entry of the TeX FAQ for full details.
%
% First we define the functions which are going to be called by our
% special characters

\newcommand{\stack@sub}[1]{\raisebox{-0.4ex}{\scriptsize #1}}	% _
\newcommand{\stack@sup}[1]{\raisebox{0.8ex}{\scriptsize #1}}	% ^
%\newcommand{\stack@mul}{\ensuremath{\mathbin\times}}		% *
\newcommand{\stack@mul}{\,*\,}									% *
\newcommand{\stack@bar}{~\textbar~}								% |
\newcommand{\stack@opa}{\ensuremath{\langle}}					% <
\newcommand{\stack@cla}{\ensuremath{\rangle}}					% >

\newif\if@stack@quote\@stack@quotetrue
\newcommand{\stack@qot}{%										% "
	\if@stack@quote``\@stack@quotefalse\else''\@stack@quotetrue\fi}

% Now we have to activate the special characters we are going to
% define, so that we can define them! We do this inside a simple
% group so we don't screw up the rest of the system.

\begingroup
	\catcode`\_=\active  % Subscript:	_1 or _{12}
	\catcode`\*=\active  % Multiply:		1*2
	\catcode`\|=\active  % Alternative:	u|n
	\catcode`\<=\active  % Start text:	<ccc>
	\catcode`\>=\active  % End text:	<ccc>
	\catcode`\"=\active  % Syntax element: "name"

% Because we are inside a simple group, we have to use \gdef rather
% than \newcommand. The \stack@set command installs the new specials
% for the next function call.

\gdef\stack@set{%
	\catcode`\_=\active \let_=\stack@sub%
	\catcode`\*=\active \let*=\stack@mul%
	\catcode`\|=\active \let|=\stack@bar%
	\catcode`\<=\active \let<=\stack@opa%
	\catcode`\>=\active \let>=\stack@cla%
	\catcode`\"=\active \let"=\stack@qot%
}
\endgroup

% Now we can define the \stack command:
%
% \stack[<stack>}{<before>}{<after>}
%
% Where the <before> and <after> parameters are interpreted with the
% new specials. To do this we have to enable the new specials before
% processing the arguments with the support function \stack@sig. We
% do this inside a new group so we don't bugger up text outside of
% the parameter.
%
% The <before> and <after> parameters define a number of additional
% special characters as follows:
% _x or _{xx}	x or xx is a subscript
% x*y			becomes x multiplied by y ($x\times y$)
% x|y			becomes x or y ( x \textbar y )
% <xxx>		becomes an argument <xxx>
% "				becomes open or close double quote
%
% All other characters are typeset in italic.

\newcommand{\stack}[1][\empty]{% [<stack>]...
	(				% Mark the start of the signature
	\ifx#1\empty\else #1: \fi	% The stack name (if given)
	\begingroup	% Open a new restricted scope for new specials
	\itshape		% The signature is in italic
	\stack@set	% Enable the specials
	\stack@sig		% Parse the signature parameters
					% We have to do this in a separate macro as
					% the specials are not active when this macro
					% is executed
}

\newcommand{\stack@sig}[2]{% ...{<before>}{<after>}
	#1\ 			% Pre-condition (before)
	--{\,}--			% Mark the "execution point"
	\ #2			% Post-condition (after)
	\endgroup		% Close restricted scope
					% Disable new specials and \itshape
	)				% Close stack signature
}

% The \param{} command allows us to process its argument in exactly
% the same way as the <before> and <after> parameters. Thus we have
% to use the same trick of enabling the our specials inside of a new
% group before calling a helper word \param@arg which actually
% processes the argument.

\newcommand{\param}{% ...
	\begingroup		% Open a restricted scope for our specials
	\itshape			% A stack parameter is always given in italic
	\stack@set		% Enable the specials
	\param@arg		% Parse the parameter
}

\newcommand{\param@arg}[1]{% ...{<param>}
	#1%			% Parse the parameter with our specials enabled
	\endgroup		% Close restricted scope, we don't want our
					% specials buggering up anything else now do we,
					% this also cancels the \itshape command
}

% As part of the testing environment we also provide the \test
% macro to typeset the text of a test case.

% \test[<format>]{<pre>}{<post>}
\newcommand{\test}{\frenchspacing\obeyspaces\test@arg}
\newcommand{\test@arg}[3][]{%
	\texttt{T\{ #2 -> #3 #1\}T}%
	\nonfrenchspacing\catcode`\ =10}

% ==== Deferred Text ====
%
% \begin{rationale} ... \end{rationale}
% \begin{testing}   ... \end{testing}
%   \test{<pre>}{<post>}	A test case
% \begin{implement} ... \end{implement}
%
% Deferred text refers to those parts of a words definition that
% do not appear in the main normative definition.  Such informative
% text appears in a separate appendix.  Be in the Rationale, Test
% cases, or a reference implementation.
%
% Rather than defining sections as we have done for the different
% semantic descriptions, we have to define environments so that we
% can either include the text in with the normative definition as
% it is much easer to review the text in this way, or export the
% text to another file, which can then be included into the
% appropriate section of the appendix.
%
% We have to provide two separate versions of these environments.
% One is used when we are inlining (\inlinetrue) and the other when
% we are exporting (\inlinefalse).

\ifinline
	% We have to define the "inline" version of these environments.
	% These will simply show the text inline with the normative
	% description.
	
	% We define two helper macros.  The first of which will output
	% the section <title> and define a hyper target for the <title>
	% based on the current name <space>.
	\newcommand{\inline@section}[2]{% {<space>}{<title>}
		% In the review version of the document we change the font
		% for the informative text to help distinguish it from the normative
		% text.  In the final version it will appear in a separate appendix.
		\sffamily
		%
		% Output the section <title> and define an associated
		% hyper target in the given name <space>.
		\item[\hyperdef{#1.\word@list}{\word@label}{#2}]
	}

	% We need to fake a latex label for this section of the words
	% definition.  This macro will fake a label for the given
	% <annex> within a given name <space>.
	\newcommand{\inline@label}[2]{% {<space>}{<annex>}
		% We start by fakeing the current label value
		\def\@currentlabel{%
			#2.%
			\ifnum\value{word@core}=\value{chapter}\thesection\else\thesubsection\fi%
			\ifx\word@num\empty.0\else.\word@num\fi%
			\ifx\word@sub\empty\else.\word@sub\fi%
		}
		% The text of the label
		\edef\@currentlabelname{\word@name}
		% The hyper target for this label
		\def\@currentHref{#1.\word@list.\word@label}
		% Finally, the label itself
		\label{#1:\word@list:\word@label}
	}

	% \begin{rationale} ... \end{rationale}
	% The rationale environment must define a cross reference label
	% (and hyper link target) for use by \rref.

	\newenvironment{rationale}{%
		\inline@section{rat}{Rationale}
		\inline@label{rat}{\ref{annex:rationale}}
	}{
		% Switch back to the normal font
		\rmfamily
	}

	% \begin{testing} ... \end{testing}
	% Now we need to do something similar for the testing environment.
	\newenvironment{testing}{
		\inline@section{test}{Testing}
		\inline@label{test}{\ref{annex:test}}
	}{
		\rmfamily
	}

	% \begin{implment} ... \end{implment}
	% And the same again for the reference implementation.
	\newenvironment{implement}{%
		\inline@section{imp}{Implementation}
		\inline@label{imp}{\ref{annex:implement}}
		\ttfamily
	}{%
		\rmfamily
	}

	% Sometime we want "normal" text in the implementation and
	% testing sections.  We define a "Deferred Font" to hide the
	% sf/rm font switch.
	\newcommand{\textdf}[1]{\textsf{#1}}
	\newcommand{\dffamily}{\sffamily}
\else
	% We are not "inline," so we have to ship the informative text
	% out to their respective appendices.
	%
	% For this some knowledge of the answers package is required.
	% This package allows us to define an association between two
	% environments and a "solution" file:
	%
	% \Newassociation{defertext}{deferredtext}{deferred}
	%
	% When a <defertext> environment is encountered the text will
	% be written out to the associated solution file (<deferred> in
	% this case).  The text is placed in the <deferredtext>
	% environment, so that it may be processed correctly.
	%
	% The <deferredtext> environment is executed with a number of
	% parameters.  These are defined by the \deferredtextparams
	% macro.  This allows us to capture the environment in which the
	% defertext environment was found, and pass on any relevant
	% information to the deferred text environment.
	%
	% The command:
	%
	%	\Opensolutionfile{deferred}[filename]
	%
	% associates an actual file name (in this case <filename>) with
	% the solution file handle <deferred>.  This allows a single
	% solution file handle to be associated with multiple physical
	% files, one per wordlist.
	%
	% So that's the background, no on to the deferred environments!

	% Override the default file extension (.tex) for these support
	% files.  Making it something else (.sub) will make it easy to
	% delete them after a run.
	\renewcommand{\solutionextension}{sub}

	% Define a new solution handle for each of the informative
	% environments:

	\Newassociation{rationale}{worddefer}{rationale}
	\Newassociation{testing}{worddefer}{testing}
	\Newassociation{implement}{worddefer}{implementation}

	% The pre<x> macros are invoked before the text is shipped out to
	% the auxiliary file.  We use them to redirect the reader to the
	% appropriate appendix.

%	\newcommand{\prerationale}{%
%		\item[Rationale] See \rref{\word@list:\word@label}{\word@name}.
%	}

%	\newcommand{\pretesting}{%
%		\item[Testing] See \tref{\word@list:\word@label}{\word@name}.
%	}

%	\newcommand{\preimplement}{%
%		\item[Implementation] See \iref{\word@list:\word@label}{\word@name}.
%	}	

	% The text for all three environments will be processed by
	% the worddefer environment.  This will be given a number
	% of paramaters, which must capture the current environment
	% when the source environment was used.

	\renewcommand{\worddeferparams}{%
		{\ifnum\value{word@core}=\value{chapter}\thesection\else\thesubsection\fi}%	Section (or sub-section) number
		{\ifx\empty\word@num0\else\word@num\fi}%		2 Word number or \empty
		{\ifx\empty\word@sub0\else\word@sub\fi}%		3 Word sub-number
		{\word@list}%		4 The current word list
		{\word@label}%		5 The label for the word
		{\word@name}%		6 The LaTeX name for the word
		{\if@star\word@prop\fi}%	7 Proposal
	}

	% The exported text has to interact with the appendix which
	% includes the text.  It does this though the following
	% interface:

	% The appendix must define a namespace for itself.  This tells
	% worddefer which label to generate (rat, test or imp).

	\def\defer@space{%
		\@latex@error{No name space defined - Use the
			\protect\namespace command to define a namespace}\@ehc
	}

	\newcommand{\namespace}[1]{%
		\gdef\defer@space{#1}
	}

	% If the appendix generates a header for each section, there is
	% the potential for a header to appear with no body if there is
	% no exported text for the appendix in a given wordlist.  To
	% prevent this rather unsightly situation the appendix uses the
	% \defersection command to define the current section heading.

	\newcommand{\defersection}[1]{\gdef\defer@title{#1}}

	% deferword will output an appropriate section heading, and then
	% resets \defer@title to \empty so that it is only output once.

	% However, as we do not output a section header, we still need to
	% be able to increment the section number, so that the numbering
	% keeps in step with the wordlist definitions.  Thus we provide
	% a macro to increment the section number if the header was not
	% output.  This should be called after the support file has been
	% input into the document.

	\newcommand{\stepsection}{%
		\ifx\defer@title\empty\else
			\stepcounter{section}
		\fi
	}

	% Now we have set up the environment we can finally override the
	% default worddefer environment.  This takes seven parameters which
	% where defined by \deferwordparams to be:
	%
	% #1	Section (or sub-section) number
	% #2	Word number or 0
	% #3	Word sub-number or 0
	% #4	The current word list
	% #5	The label for the word
	% #6	The LaTeX name for the word
	% #7	The proposal for the word

	% We redefine the standard worddefer environment to take account
	% of the parameters we have just defined.

%	\newcommand{\word@defer@error}[1]{%
%		\@latex@error{%
%			In rationale for \word@num\space "\word@name" of wordset
%			"\word@list" \MessageBreak #1}\@ehc
%	}

	% The \format@<x> commands are called by the general worddefer environment
	% to initialise the formatting for the section.  In the rationale and test
	% appendices this is the "normal" roman font, but in the implementation
	% appendix this is the type-type (courier) font.

	\let\format@rat\rmfamily
	\let\format@test\rmfamily
	\let\format@imp\ttfamily

	\renewenvironment{worddefer}[7]{%
		%
		% Output the section heading
		%
		\ifx\defer@title\empty\else
			\section{The optional \defer@title{} word set}
			\label{\defer@space:\defer@title}
			\gdef\defer@title{}
		\fi
		%
		% Output the word header.
		% Mark the header as the target for the hyperlink.
		%
		\pagebreak[3]
		%
		\hyperdef{\defer@space.#4}{#5}{%
			\textbf{\rmfamily\thechapter.#1%
				\ifnum#2=0\empty.\rule[.8ex]{2em}{.5pt}\else.#2\fi%
				\ifnum#3=0\empty\else.#3\fi
				\quad \hyperref{}{}{#4.#5}{\texttt{#6}}
			}
		} \\[-1.4\baselineskip]
		%
		\ifx#7\empty\else%
			\@startrue%
			\cbstart\patch{#7}%
		\fi%
		\pagebreak[1]
		%
		% Start the body environment
		%
		\begin{list}{}{
			\setlength{\labelwidth}{2em}	% <== Magic number, width of indent
			\setlength{\leftmargin}{\labelwidth}
			\addtolength{\leftmargin}{\labelsep}
			\renewcommand{\makelabel}{\word@item}
		}
		\item\relax
		%
		% Store a few values just in case there is an error
		%
		\def\word@num{\thechapter.#1%
			\ifx#2\empty.--\else.#2\fi%
			\ifx#3\empty\else.#3\fi}
		\def\word@list{#4}
		\def\word@label{#5}
		\def\word@name{#6}
		%
		% Create a few variables, used by \label
		%
		\def\@currentlabel{\thechapter.#1{}.#2{}\ifnum#3=0\else.#3\fi}
		\edef\@currentlabelname{#6}
		\def\@currentHref{\defer@space.#4.#5}
		%
		% Record a cross reference label for the section
		%
		\label{\defer@space:\word@list:\word@label}
		\typeout{\ifnum#2=0----\else #2\fi: \defer@space:\word@list:\word@label}
		%
		% Format the section
		%
		\csname format@\defer@space\endcsname
		%
		% Patch the error message to report "rationale"
		%
%		\let\word@error=\word@defer@error
	}{
		%
		% Ignore the no \item error
		%
%		\def\@noitemerr{}
		%
		% End the list environment
		%
		\end{list}
		%
		\if@star%
			\cbend%
			\@starfalse%
		\fi%
		%
		\pagebreak[3]
	}

	% Sometime we want "normal" text in the implementation and
	% testing sections.  We define a "Deferred Font" to hide the
	% sf/rm font switch.
	\newcommand{\textdf}[1]{\textrm{#1}}
	\newcommand{\dffamily}{\rmfamily}
\fi

\newcommand{\proposal}[1]{%
	\ifrelease\else%
		\vspace*{-3ex}\hfill\textsf{\small #1}\\[-4ex]
	\fi
}

% ========== Special Characters ==========

% \tab[n]   => extra horizontal space
\newlength{\tablength}
\setlength{\tablength}{1em}
\newcommand{\tab}[1][1]{\hspace*{#1\tablength}}

% \arg{x}   => <x>
\renewcommand{\arg}[1]{$\langle$\textit{#1}$\rangle$}

% \bs       => \
\newcommand{\bs}{\char"5C}

% \tilde    => ~
\renewcommand{\tilde}{\char"7E}

% \num		=> #
\newcommand{\num}{\char"23}

% \brace		=> {
\renewcommand{\brace}{\char"7B}

% ========================================



% ========== Extend Cross Referencing ==========

% Thanks to hyperref, when we execute the label it expands to four
% augments:
%
% 1: Number - the \@curentlabel when the label was defined
% 2: Page   - the page the label was defined on (\c@page)
% 3: Title  - The title of the label (\@currentlabelname)
% 4: Link   - The hyperdef associated with the label (\@currenHref)

% Output a word name. The name is given in courier-bold and hyper
% linked to its definition.
% If we are using the \showref flag we also underline it, show we can
% see which words are linked, in the dvi viewer and which are not.

\newcommand{\word@word}[4]{% {number}{page}{name}{link}
	\hyperref{}{}{#4}{%
		\textbf{\texttt{%
			\frenchspacing%
			\ifshowref
				\underline{#3}%
			\else%
				{#3}%
			\fi%
			\nonfrenchspacing
		}}%
	}%
}

\ifshowref
	\newcommand{\@noword}[2]{% {<wordset>}{<word>}
		\@latex@error{Can't find "#2" in "#1", in file \includefile}\@ehc%
	}
\else
	\newcommand{\@noword}[2]{% {<wordset>}{<word>}
		\@latex@warning{Can't find "#2" in "#1", in file \includefile}{}%
	}
\fi

% \word[<wordlist>]{<wordlabel>}
% Typeset the word associated with the label <wordlabel>. The word is
% either in the current wordlist, the core word list or the optional
% <wordlist>. The word is hyperlinked back to its definition.
%
% If the word has not been defined, can not be found, it reports an
% error. The word is still typeset but with a line though it.

% Note that three \expandafter's are needed to call \word@word with
% the value held by the label. For example if we consider the core
% word ! (store), we would have three levels of expansion as follows:
%
% 1: expand \csname r@#1:#2\endcsname      to \r@core:store
% 2: execute \r@core:store                 to obtain {0010}{12}{!}{store}
% 3: call \word@word with those arguments

\newcommand{\word}[2][\word@list]{% [<wordlist>]{<wordlabel>}
	% Is label <wordlist>:<wordlabel> defined
	\expandafter\ifx\csname r@#1:#2\endcsname\relax%
		% No - try looking for the label core:<wordlabel>
		\expandafter\ifx\csname r@core:#2\endcsname\relax%
			% No - then its not a standard word
			\textbf{\texttt{\ifshowref\sout{#2}\else{#2}\fi}}%
			\@noword{#1}{#2}%
		\else%
			% word in core wordlist
			\expandafter\expandafter\expandafter\word@word\csname r@core:#2\endcsname%
		\fi%
	\else%
		% word in given wordlist
		\expandafter\expandafter\expandafter\word@word\csname r@#1:#2\endcsname%
	\fi%
}

% \xref[<text>]{<label>}
% Extended cross reference.
%
% This was originally developed as a tool to help in the conversion of
% existing documents into LaTeX form. It relies on the extended \label
% command provided by the hyperref package.  It will look up <label>
% and places the section number followed by the section name as a
% hyperlink to <label>.  Should <label> not be found it places <label>
% (between brackets) with the optional <text> along side.  The idea
% being that the user can see what was in the original document
% (<text>), and which <label> was not found.  If the <text> is not
% given, the traditional double question mark is used.
%
% Thus for the following example, the label "foo" refers to section
% 3.2.1 which has the name "Foo", the text:
%
%	section \xref[original text]{foo}.
%
% If the label foo is found this would produce:
%
%	section 3.2.1 Foo.
%
% where the "3.2.1 Foo" is a hyperlink to the label foo.
%
% If the label foo does not exist this would produce the text:
%
%	section [foo: original text].
%
% where the "[foo: original text]" appears in bold. This is intended
% to indicate that the label foo was not found, but the original
% document had "original text" as the text which should appear here.

% We define a helper command which interprets the parameters generated
% by executing the label.  It will output the section number (#1) and
% title (#3)

\newcommand{\word@xref}[4]{% {number}{page}{name}{link}
	\textbf{%
		\hyperref{}{}{#4}{#1} \linebreak[3]
		\hyperref{}{}{#4}{#3}%
	}%
}

\newcommand{\xref}[2][??]{% [<text>]{<label>}
	% Look for the label
	\expandafter\ifx\csname r@#2\endcsname\relax%
		% label is not found
		% Spit out a warning
		\@latex@warning{Reference `#2' in file \includefile\space undefined}%
		% Tell the user the label and original text
		\textbf{[#2: #1]}%
	\else%
		% Label found so output a the section number and title
		\expandafter\expandafter\expandafter\word@xref\csname r@#2\endcsname
	\fi
}


% \wref{<label>}{<Name>} - Word reference
%	<label> will be of the form <wordlist>:<label> i.e., core:store
%	<name>	is the LaTeX which will be typeset for the word reference

\newcommand{\word@ref}[4]{% <section> <page> <name> <label>
	\hyperref{}{}{#4}{\textbf{#1}} \linebreak[3]
	\hyperref{}{}{#4}{\texttt{#3}}%
}

\newcommand{\wref}[2]{% {label}{name}
	% Look for the word's label
	\expandafter\ifx\csname r@#1\endcsname\relax%
		% Not found - output label and then name
		\textbf{[#1] #2}%
		\@latex@warning{Reference `#1' to word `#2' in file \includefile\space undefined}%
	\else%
		\expandafter\expandafter\expandafter\word@ref\csname r@#1\endcsname%
	\fi%
}

% \rref{<label>}{<name>} - Rationale reference
%	\rref is the same as \wref except it looks in the rationale (rat:)
%	name space

\newcommand{\word@ref@inline}[4]{\word@ref{A.#1}{#2}{#3}{#4}}

\newcommand{\rref}[2]{% {<label>}{<name>}
	\expandafter\ifx\csname r@rat:#1\endcsname\relax%
		% Not found - output a warning, the label and the word
		\textbf{[rat:#1] #2}%
		\@latex@warning{Reference `#1' to rationale of `#2' on page
			\thepage\space undefined}%
	\else%
		\ifinline%
			\expandafter\expandafter\expandafter\word@ref@inline\csname r@#1\endcsname%
		\else%
			\expandafter\expandafter\expandafter\word@ref\csname r@rat:#1\endcsname%
		\fi%
	\fi%
}

% \tref{<label>}{<name>} - Testing

\newcommand{\word@test@inline}[4]{\word@ref{\ref{annex:test}.#1}{#2}{#3}{#4}}
\newcommand{\tref}[2]{% {<label>}{<name>}
	\expandafter\ifx\csname r@test:#1\endcsname\relax%
		\textbf{[test:#1] #2}%
		\@latex@warning{Reference '#1' to testing of '#2' on page
			\thepage\space undefined}%
	\else%
		\ifinline%
			\expandafter\expandafter\expandafter\word@test@inline\csname r@#1\endcsname%
		\else%
			\expandafter\expandafter\expandafter\word@ref\csname r@test:#1\endcsname%
		\fi%
	\fi%
}

% \iref{<label>}{<name>} - Implementation
\newcommand{\word@imp@inline}[4]{\word@ref{\ref{annex:implement}.#1}{#2}{#3}{#4}}
\newcommand{\iref}[2]{% {<label>}{<name>}
	\expandafter\ifx\csname r@imp:#1\endcsname\relax%
		\textbf{[imp:#1] #2}%
		\@latex@warning{Reference '#1' to implementation of '#2' on page
			\thepage\space undefined}%
	\else%
		\ifinline%
			\expandafter\expandafter\expandafter\word@imp@inline\csname r@#1\endcsname%
		\else%
			\expandafter\expandafter\expandafter\word@ref\csname r@imp:#1\endcsname%
		\fi%
	\fi%
}
% =============================================




% ========== Format of Headings ==========

\setcounter{secnumdepth}{4}

\renewcommand{\chapter}{\@startsection
	{chapter}{0}{0pt}{1pt}{\baselineskip}
	{\normalfont\LARGE\sffamily\bfseries}
}
\renewcommand{\chaptermark}[1]{
	\markboth{\textsf{\thechapter. #1}}{}
}
\renewcommand{\section}{\@startsection
	{section}{1}{0pt}{1pt}{1pt}
	{\normalfont\Large\sffamily\bfseries}
}
\renewcommand{\subsection}{\@startsection
	{subsection}{2}{0pt}{1pt}{1pt}
	{\normalfont\large\sffamily\bfseries}
}
\renewcommand{\subsubsection}{\@startsection
	{subsubsection}{3}{0pt}{1pt}{1pt}
	{\normalfont\normalsize\sffamily\bfseries}
}

\newcommand{\annex}[2][\empty]{%
	\refstepcounter{chapter}
	\begin{center}
		\normalfont\Large\sffamily
		{\bfseries Annex \thechapter} \\
		(informative) \\
		{\bfseries #2}
	\end{center}
	\ifx\empty#1 \def\tmp@a{#2}\else\def\tmp@a{#1}\fi
	\chaptermark{\tmp@a}
	\addcontentsline{toc}{chapter}{\protect\numberline{\thechapter}\tmp@a}
	%
	% Set up variables for \label
	\def\@currentlabel{\thechapter}%
	\edef\@currentlabelname{\tmp@a}%
}

\usepackage{environ}[2008/06/18]

\NewEnviron{editor}{%
	{\color{blue}\fbox{%
	\begin{minipage}{\linewidth}
		\slshape\textbf{Editor:} \par \BODY
	\end{minipage}}}
}


% \@history@label defined/used by history package
\newcommand{\patch}[1]{% {<name>}
	\edef\temp@b{\thepage.#1}
	\ifx\temp@b\@history@label
		% Label already used on this page
		\marginpar{\tiny{\color{white}c:b}}
	\else
		% New label for this page
		\marginpar{\tiny\textsf{#1}{\color{white}c:b}}
		\edef\@history@label{\temp@b}
	\fi
}

\newcommand{\strike}[3][3]{% [<end-space>]{<height>}{<width>}
	\rule{-#3pt}{0pt}%
	\rule[#2pt]{#3pt}{.5pt}%
	\rule[#2pt]{3pt}{.5pt}%
	\rule{-#1pt}{0pt}%
}

% The LaTeX to HTML converter occasionally needs a helping hand.
% The \html{} command allows me to embed HTML that is copied
% directly into the HTML output untouched.  But is ignored by
% LaTeX.
\newcommand{\html}[1]{}

% ========================================

% Modify itemize and enumerate environments

\renewcommand{\labelenumi}{\alph{enumi})}
\renewcommand{\labelenumii}{\arabic{enumii})}

\renewcommand{\labelitemi}{\bfseries --}
\renewcommand{\labelitemii}{\m@th\bullet}

% Reduce space between to \hline commands
\doublerulesep=1pt

\makeatother

% ========================================================
% ==========									==========
% ========== Finally we can start the document	==========
% ==========									==========
% ========================================================

\begin{document}

% \nochangebars\rule{\linewidth}{1pt}\hspace*{-\linewidth}\rule[3pt]{\linewidth}{1pt}

\include{hyphenation}
\include{titlepage}
\thispagestyle{empty}
\def\includefile{}

% Change style of page numbering without changing the page number.
% What used to be \frontmatter is now this crap:

\makeatletter
\cleardoublepage
\@tempcnta = \c@page
\frontmatter
\c@page = \@tempcnta
\makeatother

\setcounter{tocdepth}{2}
{\parskip 0pt \tableofcontents}	\addcontentsline{toc}{chapter}{\contentsname}
%%{\parskip 0pt \listoftables}	\addcontentsline{toc}{chapter}{\listtablename}
%%{\parskip 0pt \listoffigures}	\addcontentsline{toc}{chapter}{\listfigurename}
%%{\parskip 0pt \listofprograms}	\addcontentsline{toc}{chapter}{\listprogramname}

%\newpage
\include{foreword}
%\include{foreword-ans}
\ifrelease\else
\include{process}
\fi
\include{members-2x}
%\include{members-x3}

% Because some people are unable to handle the concept of sheet
% numbers being different to page numbers we have to bastardise
% the page numbering by preserving the page number between
% the font and main matter, converting page number into sheet
% numbering.
% What used to be \mainmatter is now this crap:

\makeatletter
\cleardoublepage
\@tempcnta = \c@page
\mainmatter
\c@page = \@tempcnta
\makeatother

% Part I: Introduction

\include{intro}
\include{notation}
\include{usage}
\include{doc}
\include{label}

% Part II: Glossary

\raggedbottom
\cfoot{\collate}

\addtocontents{toc}{\protect\setcounter{tocdepth}{0}}
\include{core}		% 6
\include{block}		% 7
\include{double}	% 8
\include{exception}	% 9
\include{facility}	% 10
\include{file}		% 11
\include{float}		% 12
\include{locals}	% 13
\include{memory}	% 14
\include{tools}		% 15
\include{search}	% 16
\include{string}	% 17

\addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
\include{xchar}		% 18

% Close the deferred output files
\Closesolutionfile{rationale}
\Closesolutionfile{testing}
\Closesolutionfile{implementation}

\flushbottom
\cfoot{}


% Part III: Rational

\appendix
\include{rationale}		% A

% Part IV: Informative background

\include{bib}			% B
%	\include{history}	% C
\include{diff}			% D
\include{port}			% E
\ifrelease\else
	\include{implement}	% F
	\include{testsuite}	% G
\fi

% Close the glossary file
\immediate\closeout\wordfile

% Part V: Index

%\closehistory
\ifrelease\else
	\include{changelog}	% H
\fi
\include{alpha}			% I

\end{document}