From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- support/ltx2x/ltx2x.tex | 7453 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 7453 insertions(+) create mode 100644 support/ltx2x/ltx2x.tex (limited to 'support/ltx2x/ltx2x.tex') diff --git a/support/ltx2x/ltx2x.tex b/support/ltx2x/ltx2x.tex new file mode 100644 index 0000000000..beb6807367 --- /dev/null +++ b/support/ltx2x/ltx2x.tex @@ -0,0 +1,7453 @@ +% ltx2x.tex Description of ltx2x program +\documentclass[11pt]{article} +\usepackage{url} +\usepackage{ltx2html} +\setlength{\textheight}{8.0in} +\setlength{\textwidth}{6.0in} +\setlength{\oddsidemargin}{0.25in} +\setlength{\evensidemargin}{0.25in} +\setlength{\marginparwidth}{0.6in} +\setcounter{secnumdepth}{4} +\setcounter{tocdepth}{4} +% define these to save some typing +\newcommand{\lx}{{\small\sl LTX2X}} +\newcommand{\ctab}{command table} +\newcommand{\Express}{{\sc Express}} +\newcommand{\ExpressA}{{\sc Express-A}} +\newcommand{\ExpressG}{{\sc Express-G}} +\newcommand{\ExpressI}{{\sc Express-I}} +\newenvironment{code}{\begin{small}}{\end{small}} +\newcommand{\keyword}[1]{\begin{small}\texttt{#1}\end{small}} +\newcommand{\keytext}[1]{\begin{small}\texttt{#1}\end{small}} +\newcommand{\file}[1]{\texttt{#1}} +\mltitle{LaTeX to X translator} +\begin{document} +\title{ \textsl{LTX2X:} A \protect\LaTeX\ to X Auto-tagger} +\author{Peter R. Wilson \\ + Catholic University of America\thanks{This work was performed +while a Guest Researcher at the National Institute of Standards and +Technology} \\ + Email: \texttt{pwilson@cme.nist.gov} } +\date{January 1997} + +\bibliographystyle{unsrt} +\pagenumbering{roman} +\maketitle + +\begin{abstract} + \lx{} is a table-driven program that will replace \LaTeX\ commands +by user defined text. This report describes the beta version of the system. +\lx{} supports both a declaritive command style and an interpreted +procedural language tentatively called \ExpressA. +Details are given of the program functionality including examples. +System installation instructions are provided. +\end{abstract} + +\tableofcontents +\listoftables + +\clearpage +\pagenumbering{arabic} + +\section{Introduction} \label{sec:introduction} + + \LaTeX~\cite{LAMPORT94}, which is built on top of \TeX~\cite{KNUTH84a}, +is a document tagging system +that is very popular in the academic and scientific publishing communities +because of the high quality typeset material that the system outputs +for normal text and especially for mathematics. + + In particular, many of the documents forming the +International Standard ISO~ 10303, commonly referred to as STEP~\cite{STEPIS}, +have been written using \LaTeX\ as +the document tagging language. Lately there have been moves towards converting +the STEP documents to embody SGML~\cite{GOLDFARB90} +rather than \LaTeX\ markup. This has led +to an interest in the automatic conversion from \LaTeX\ to SGML +documents. +The \lx\ system is an initial attempt to provide a generic capability for +converting \LaTeX\ tags into other kinds of tags. + + The \lx\ system described below is in a beta release state. That is, there +is probably some more work to be done on it but experience from use is +needed to determine desirable additional functionality. However, the code +has been stable for some time. +Bug reports or suggested +enhancements (especially if the suggestions are accompanied by working code) +are encouraged, as are constructive comments about this document. + + Essentially, \lx{} reads a file containing \LaTeX{} markup, +replaces the \LaTeX{} commands by user-defined text, and writes the result +out to another file. The program operates from a command table that specifies +the replacement text. In general, no programming knowledge or skills are +required to write a command table, which \lx{} will then interpret. +Some knowledge of \LaTeX{} is required, but no more than is necessary +for authoring a \LaTeX{} document. + + \lx{} has proved capable of performing such functions as: +\begin{itemize} +\item Conversion of documents marked up according to a specific \LaTeX{} + documentclass to documents tagged according to a specific SGML DTD. +\item Removal of \LaTeX{} commands to produce deTeXed source. +\item Conversion of simple \LaTeX{} documents to + HTML~\cite{MUSCIANO96} tagged documents for publication on the + World Wide Web. +\end{itemize} + + The remainder of this introduction gives an overview of the \lx{} program. +The command table is described in more detail in section~\ref{sec:command-table} +and information on running the \lx{} program is provided in +section~\ref{sec:program}. Section~\ref{sec:expressa} gives an +overview +of the \ExpressA{} language.\footnote{The overview is necessarily +rather brief as I am shortly moving to a new place of employment and +\ExpressA{} is the latest addition to the system.} +Although the functionality available through the command table facility is +suitable for many tasks, especially since an interpreter for the \ExpressA{} +general programming language is included within \lx, +section~\ref{sec:special} gives details on how the system can +be extended for cases where this proves to be inadequate. + + The report ends with several appendices. An example command table for +deTeXing a document is reproduced in~\ref{sec:detexing} and some of +the issues in converting from \LaTeX{} to HTML are discussed +in~\ref{sec:htmling}. The known limitations +of \lx{} are listed in~\ref{sec:limitations} and a summary of the command +table facilities are given in~\ref{sec:summary}. Appendix~\ref{sec:install} +provides instructions on installing the \lx{} program, together with copyright +and warranty information. Finally, \ref{sec:ctabgrammar} and \ref{sec:expgrammar}provide grammars for the \ctab and \ExpressA, respectively. + +\subsection{Overview} + + The intent of Leslie Lamport, the author of \LaTeX, was to provide a document +tagging system that enabled the capture of the logical structure of a document. +This system uses Donald Knuth's \TeX\ system as its typesetting engine~\cite{KNUTH84a}, +and thus has an inherent capability for high quality typesetting. + + All \LaTeX\ commands are distinguished by starting with a backslash (\verb|\|). +Generally speaking, the name of a command is a string of alphabetic characters +(e.g. \verb|\acommand|). Commands may take arguments. Required arguments are +enclosed in curly braces (i.e. \verb|{| and \verb|}|). Optional arguments +are enclosed in square brackets (i.e. \verb|[| and \verb|]|). The general syntax +for a command is the command name (preceded by a backslash) followed by the +argument list with a maximum\footnote{Under very unusual +circumstances this limit may be exceeded.} of nine arguments. + + The \lx\ program reads a \LaTeX\ document file and outputs a +transformation of this file. By default it outputs the normal text +while for each \LaTeX{} command and argument performs some +user-specified actions; typically these actions involve the output +of specific text corresponding to the particular command. +The actions are specified in a \emph{\ctab} file, written by the user, +which is read into the \lx\ system before document processing is +begun. A \ctab\ consists of a listing of the \LaTeX\ commands of interest +together with the desired actiond for each of these commands and their +arguments. +Different effects may be easily obtained by changing the \ctab\ +file. For example, a simple \ctab{} file may be written that will delete +all the \LaTeX\ commands from a document, resulting in a plain ASCII file +with no embedded markup.\footnote{To afficionados, +this process is known as de-\TeX ing.} +A more complex command table may be written that will replace \LaTeX\ tags +with appropriate SGML tags. + + In some circles it is traditional to introduce a programming +language by providing an example program that prints `Hello world'. +In contrast, the following \ctab{} file called \file{bye.ct}, +when used in conjunction +with a typical vanilla \LaTeX{} file, will transform the \LaTeX{} file +to a file that consists only of the words `Goodbye document'. + +\begin{code} +\begin{verbatim} +C= bye.ct "Goodbye document" for ltx2x + +TYPE= COMMAND +NAME= \documentclass + START_TAG= "Goodbye document" + PC_AT_END= NO_PRINT +END_TYPE + +C= just in case a LaTeX v2.09 document +TYPE= COMMAND +NAME= \documentstyle + START_TAG= "Goodbye document" + PC_AT_END= NO_PRINT +END_TYPE + +C= just in case there is no \documentclass/style command +TYPE= BEGIN_DOCUMENT + START_TAG= "Goodbye document" + PC_AT_END= NO_PRINT +END_TYPE + +TYPE= OTHER_COMMAND + PRINT_CONTROL= NO_PRINT +END_TYPE + +TYPE= OTHER_BEGIN + PRINT_CONTROL= NO_PRINT +END_TYPE + +TYPE= OTHER_END + PRINT_CONTROL= NO_PRINT +END_TYPE + +END_CTFILE= end of bye.ct +\end{verbatim} +\end{code} + + Essentially the \ctab{} instructs \lx{} what to print for each \LaTeX{} +command. A \ctab{} file consists of a series of commands, one per line +and introduced by a keyword such as \keyword{TYPE=}. Keywords are case +insensitive but by convention are written in upper case. Comments in +a \ctab{} are introduced by the keyword \keyword{C=}. + + The main body of a \ctab{} consists of the specification of +\LaTeX{} commands of interest and the actions to be taken for these. +Each specification commences with the keyword \keyword{TYPE=} and is +completed by the keyword \keyword{END\_TYPE}, the relevant actions +being listed between these two keywords. + + \lx{} treats some \LaTeX{} commands specially; among these are +\verb|\begin{document}| and \verb|\end{document}|. In a \ctab{} +these are specified by the types \keyword{TYPE= BEGIN\_DOCUMENT} and +\keyword{TYPE= END\_DOCUMENT}. The actions at +\verb|\begin{document}| are firstly to print the string `Goodbye document' +(specified in the line \keyword{START\_TAG= "Goodbye document"}) and +secondly to stop printing any output (specified in the line +\keyword{PC\_AT\_END= NO\_PRINT}). + + By not specifying the \keyword{END\_DOCUMENT} entry, the default +action is used for the \verb|\end{document}| command. + + The \ctab{} entries for the commands \verb|\documentclass| and +\verb|\documentstyle| specify that, if either of these is in the +source document, then it is to be replaced by the text string +\keytext{"Goodbye document"}, and then all further printing is to +be switched off. + + The other three entries in the \ctab{} specify the actions for any +other kind of \LaTeX{} command. The keyword \keyword{OTHER\_BEGIN} +signifies a \LaTeX{} command of the form \verb|\begin{name}| and +\keyword{OTHER\_END} signifies a command of the form \verb|\end{name}|. +The keyword \keyword{OTHER\_COMMAND} signifies any other kind of +\LaTeX{} command (e.g., \verb|\acommand ... |). The actions declared +for these are all \keyword{PRINT\_CONTROL= NO\_PRINT} which shuts off +any printing of the command or its arguments. In the \ctab{} \file{bye.ct} +these are only included to prevent printing before the +\verb|\begin{document}|. + + To run \lx{} with the above \ctab, type the following (where \verb|>| +is assumed to be the system prompt): +\begin{verbatim} +> ltx2x -f bye.ct input.tex output.tex +\end{verbatim} +where \file{bye.ct} is the name of the \ctab, and +\file{input.tex} and \file{output.tex} are the names of the input \LaTeX{} +file and the resulting processed file respectively. + + + As an example of a more useful \ctab\ file, the following one called +\file{decomm.ct} will remove all \LaTeX\ comments from a typical +\LaTeX{} source file. + +\begin{code} +\begin{verbatim} +C= decomm.ct Command table file for ltx2x to de-comment LaTeX source + +C= ------------------------------------ set newline characters +ESCAPE_CHAR= ? +NEWLINE_CHAR= N + +C= ----------------------------------- built in commands +TYPE= BEGIN_DOCUMENT + START_TAG= "\begin{document}" +END_TYPE + +TYPE= END_DOCUMENT + START_TAG= "\end{document}" +END_TYPE + +TYPE= BEGIN_VERB + START_TAG= "\verb|" +END_TYPE + +TYPE= END_VERB + START_TAG= "|" +END_TYPE + +TYPE= BEGIN_VERBATIM + START_TAG= "\begin{verbatim}" +END_TYPE +\end{verbatim} +\verb|TYPE= END_VERBATIM| \\ +\verb| START_TAG= "\end{verbatim}"| \\ +\verb|END_TYPE| +\begin{verbatim} +TYPE= LBRACE + START_TAG= "{" +END_TYPE + +TYPE= RBRACE + START_TAG= "}" +END_TYPE + +TYPE= PARAGRAPH + START_TAG= "?N?N " +END_TYPE + +C= ------------------- define '\item' tags within lists + +TYPE= BEGIN_LIST_ENV +NAME= itemize + START_TAG= "\begin{itemize}" + START_ITEM= "\item " +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= enumerate + START_TAG= "\begin{enumerate}" + START_ITEM= "\item " +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= description + START_TAG= "\begin{description}" + START_ITEM= "\item" + START_ITEM_PARAM= "[" + END_ITEM_PARAM= "] " +END_TYPE + +TYPE= END_LIST_ENV + NAME= itemize +END_TYPE + +TYPE= END_LIST_ENV + NAME= enumerate +END_TYPE + +TYPE= END_LIST_ENV + NAME= description +END_TYPE + +C= --------------------- pass through all other LaTeX commands + +TYPE= OTHER_COMMAND +END_TYPE + +TYPE= OTHER_BEGIN +END_TYPE + +TYPE= OTHER_END +END_TYPE + +END_CTFILE= end of file decomm.ct +\end{verbatim} +\end{code} % end small + + In the above \ctab\ file, the first pair of commands (\keyword{ESCAPE\_CHAR=} +and \keyword{NEWLINE\_CHAR=}) define the character pair that are to be used to +signify a `newline' within a tag. An example of their use is later in the +file in the \keyword{PARAGRAPH} command type. + + As indicated above, \lx\ treats some \LaTeX\ commands specially. +These are listed next in the +\ctab. The special \LaTeX{} commands are the begin and end of the +\verb|document| and \verb|verbatim| +environments, together with the \verb|\verb| command, left and right braces, +the \verb*|\ | command, and the \lx{} \keyword{PARAGRAPH} specification. +There are default actions for these, but apart from the \verb*|\ | command +the defaults are not appropriate in this case. +Above, the actions are to replace the +\LaTeX{} command by the string forming the \LaTeX{} command. The exception +is that paragraphs (the \keyword{PARAGRAPH} specification) should start +with at least one blank line and be indented some spaces. + + The \LaTeX\ \verb|\item| command is used within lists. \lx\ has to be +told how to treat the \verb|\item| command within each kind of list. This +has been done above for the \verb|itemize|, \verb|enumerate| and +\verb|description| environments. + + The final instructions in the \ctab\ file tell \lx\ to pass through the +text of all other commands and their arguments. The end of the \ctab\ file +is either the physical end of the file or the command \keyword{END\_CTFILE=}, +whichever comes first. The \keyword{END\_CTFILE=} command acts like the +\keyword{C=} command in that arbitrary text can be put after the command. + + To use the \file{decomm.ct} \ctab{} to de-comment a \LaTeX\ file, type +the following (where \verb|>| is assumed to be the system prompt): +\begin{verbatim} +> ltx2x -f decomm.ct input.tex output.tex +\end{verbatim} +where \file{input.tex} and \file{output.tex} are the names of the input \LaTeX\ +file for de-commenting and the resulting de-commented version respectively. + +\section{The \ctab\ file} \label{sec:command-table} + + By default, \lx\ does not output any \LaTeX\ comments. +Otherwise, whenever it comes +across a \LaTeX\ command it looks at the data in the \ctab\ file to determine +what actions it should take. The two most typical actions are either +to print out the command as read in, or to replace the command by some (possibly +empty) text. + + Each line in a \ctab\ file is either blank or starts with a keyword followed +by one or more blanks. For +example, a comment in the file is a line that starts with \keyword{C= }; +the remainder of the line is any comment text. Comments may be placed anywhere +in the file. + + +\subsection{Special print characters in tags} + + \lx\ is written in C~\cite{KERNIGHAN88}. +The C language enables certain non-printing characters +to be defined. These are typically written in the form \verb|\c| where \verb|\| +is the C escape character and \verb|c| +is a particular character. \lx\ understands some of these special printing +characters and the \ctab\ enables these to be given non-default values. + + The default escape character (\verb|\|) may be redefined via the +\keyword{ESCAPE\_CHAR=} command. For example, +\begin{code} +\begin{verbatim} +ESCAPE_CHAR= ? +\end{verbatim} +\end{code} +will make the question mark character the escape character. Typically, the escape +character is changed in most \ctab s to avoid clashing with the \LaTeX{} \verb|\| +character. +The following commands +can be used to redefine the C special characters. Each of these commands takes +a single character as its value. If a relevant command is not given, then the +default value is used. +\begin{description} +\item[\keyword{NEWLINE\_CHAR=}] a new line (default is \verb|n|) \\ +\item[\keyword{HORIZONTAL\_TAB\_CHAR=}] horizontal tab (default is \verb|t|) \\ +\item[\keyword{VERTICAL\_TAB\_CHAR=}] vertical tab (default is \verb|v|) \\ +\item[\keyword{BACKSPACE\_CHAR=}] backspace (default is \verb|b|) \\ +\item[\keyword{CARRIAGE\_RETURN\_CHAR=}] carriage return (default is \verb|r|) \\ +\item[\keyword{FORMFEED\_CHAR=}] formfeed (default is \verb|f|) \\ +\item[\keyword{AUDIBLE\_ALLERT\_CHAR=}] beep the terminal (default is \verb|a|) \\ +\item[\keyword{HEX\_CHAR=}] following characters form the hexadecimal number of + the character + to be printed (default is \verb|x|) (e.g. \verb|?xA3|) \\ +\end{description} + These command lines are all optional within a \ctab\ and their ordering is +immaterial. However, if any are present then they must be at the beginning of +the \ctab. + + The above special characters are useful when specifying the replacement text +for \LaTeX\ commands. + + +\subsection{\protect\LaTeX\ command types} + + The commands for controlling the actions performed on \LaTeX\ commands +are enclosed between the command lines \keyword{TYPE= } and \keyword{END\_TYPE}, +as below. +\begin{code} +\begin{verbatim} +TYPE= CommandType + C= a possibly empty set of commands +END_TYPE +\end{verbatim} +\end{code} +where \keyword{CommandType} is an \lx\ keyword signifying the kind of \LaTeX\ +command being specified. + +\subsubsection{Built in command types} + + Some \LaTeX\ commands are pre-defined within \lx. Default actions +are provided for these but it is recommended that type specifications +for each of these commands be put in the \ctab{} anyway. The keywords for +these commands are: +\begin{description} +\item[\keyword{BEGIN\_DOCUMENT}] Corresponds to the \LaTeX\ command + \verb|\begin{document}|. +\item[\keyword{END\_DOCUMENT}] Corresponds to the \LaTeX\ command + \verb|\end{document}|. +\item[\keyword{BEGIN\_VERBATIM}] Corresponds to the \LaTeX\ commands + \verb|\begin{verbatim}| and \\ + \verb|\begin{verbatim*}|. +\item[\keyword{END\_VERBATIM}] Corresponds to the \LaTeX\ commands + \verb|\end{verbatim}| and \verb|\end{verbatim*}|. +\item[\keyword{BEGIN\_VERB}] Corresponds to the \LaTeX\ commands + \verb|\verb| and \verb|\verb*|, together with the succeeding character. +\item[\keyword{END\_VERB}] Corresponds to the appearance of the character + that completes the \LaTeX\ commands + \verb|\verb| and \verb|\verb*|. +\item[\keyword{LBRACE}] Corresponds to the \LaTeX\ left brace character + \verb|{|. +\item[\keyword{RBRACE}] Corresponds to the \LaTeX\ right brace character + \verb|}|. +\item[\keyword{BEGIN\_DOLLAR}] Corresponds to the \LaTeX\ \verb|$| symbol signalling the + start of an in-text math formula. +\item[\keyword{END\_DOLLAR}] Corresponds to the \LaTeX\ \verb|$| symbol signalling the + end of an in-text math formula. +\item[\keyword{PARAGRAPH}] Corresponds to the \LaTeX\ protocol of a blank + line signalling the start/end of a paragraph. +\item[\keyword{SLASH\_SPACE}] Corresponds to the \LaTeX\ \verb*|\ | command. +\item[\keyword{OTHER\_COMMAND}] Corresponds to any \LaTeX\ command of the form + \verb|\command| not specified elsewhere within the \ctab. +\item[\keyword{OTHER\_BEGIN}] Corresponds to any \LaTeX\ command of the form + \verb|\begin{environment}| not specified elsewhere within the \ctab. +\item[\keyword{OTHER\_END}] Corresponds to any \LaTeX\ command of the form + \verb|\end{environment}| not specified elsewhere within the \ctab. +\end{description} + + + The ordering of these built in type specifications is immaterial. If +any of the above are not specified within the \ctab{} then \lx{} will use +their default action. + With the exception of the \keyword{SLASH\_SPACE} command type, the +default action is to do nothing (i.e., produce no output). +The default action for the \keyword{SLASH\_SPACE} +command type is to output a space. + +\subsubsection{Optional command types} + + For the purposes of \lx, \LaTeX\ commands are divided into various classes. +The keywords for these clases, and the class descriptions, are listed below. + +\begin{description} +\item[\keyword{TEX\_CHAR}] Corresponding to \LaTeX's special characters (with the exception + of the \$, \{\ and \}\ characters). +\item[\keyword{CHAR\_COMMAND}] Corresponding to \LaTeX\ commands of the type + \verb|\c| where \verb|c| is a single non-alphabetic character. +\item[\keyword{COMMAND}] Corresponding to \LaTeX\ commands of the type + \verb|\command|, where \verb|command| is the name of the command (except for + \verb|\begin|, \verb|\end| and \verb|\item|). +\item[\keyword{BEGIN\_ENV}] Corresponding to \LaTeX\ commands of the type + \verb|\begin{environment}| where \verb|environment| is the name of the + environment, except for those list environments whose bodies + consist of \verb|\item| commands. +\item[\keyword{END\_ENV}] Corresponding to \LaTeX\ commands of the type + \verb|\end{environment}|, with the same restrictions as for \verb|BEGIN_ENV|. +\item[\keyword{BEGIN\_LIST\_ENV}] Corresponding to \LaTeX\ commands of the type + \verb|\begin{environment}| where \verb|environment| is the name of an + environment whose body consists of \verb|\item| commands. +\item[\keyword{END\_LIST\_ENV}] Corresponding to \LaTeX\ commands of the type + \verb|\end{environment}| to match \verb|BEGIN_LIST_ENV|. +\item[\keyword{VCOMMAND}] Corresponding to a \LaTeX{} \verb|\verb|-like command. +\item[\keyword{BEGIN\_VENV}] Corresponding to the start of a verbatim-like + environment. +\item[\keyword{END\_VENV}] Corresponding to the end of a verbatim-like + environment. +\item[\keyword{SECTIONING}] Corresponding to \LaTeX\ commands of the type + \verb|\command|, where \verb|command| is a document sectioning command + such as \verb|chapter| or \verb|subsection|. +\item[\keyword{SPECIAL}] Reserved for possible future use. +\item[\keyword{SPECIAL\_COMMAND}] Corresponding to the \verb|COMMAND| keyword, + except that some special output processing is to be defined. +\item[\keyword{SPECIAL\_BEGIN\_ENV}] Corresponding to the \verb|BEGIN_ENV| keyword, + except that some special output processing is to be defined. +\item[\keyword{SPECIAL\_END\_ENV}] Corresponding to the \verb|END_ENV| keyword, + except that some special output processing is to be defined. +\item[\keyword{SPECIAL\_BEGIN\_LIST}] Corresponding to the \verb|BEGIN_LIST_ENV| + keyword, + except that some special output processing is to be defined. +\item[\keyword{SPECIAL\_END\_LIST}] Corresponding to the \verb|END_LIST_ENV| keyword, + except that some special output processing is to be defined. +\item[\keyword{SPECIAL\_SECTIONING}] Corresponding to the \verb|SECTIONING| keyword, + except that some special output processing is to be defined. +\item[\keyword{\_PICTURE\_}] Corresponding to some of the \LaTeX\ picture + drawing commands. +\item[\keyword{COMMAND\_...}] Corresponding to some of the \LaTeX{} commands + whose arrangements of required and optional arguments are untypical. +\end{description} + + The ordering of these types within a \ctab\ is immaterial. + + Each of the above type specifications requires a \keyword{NAME=} command, +whose value is the +name of the relevant command or environment being specified. For example, the +following is a (partial) specification of the figure environment and the caption +command. + +\begin{code} +\begin{verbatim} +TYPE= BEGIN_ENV +NAME= figure +END_TYPE + +TYPE= END_ENV +NAME= figure +END_TYPE + +TYPE= COMMAND +NAME= \caption +END_TYPE +\end{verbatim} +\end{code} + +\subsection{Command action tags} + + When \lx\ reads a \LaTeX\ command it performs the following actions: +\begin{enumerate} +\item Looks up the name of the command or environment in the \ctab. If + it is not found, then the appropriate default type is used. +\item Sets the printing mode according to the \keyword{PC\_AT\_START=} + command. +\item Performs the actions specified in the \ctab\ by the + \keyword{START\_TAG=} command. +\item Processes any specified arguments to the command. +\item Performs the actions specified in the \ctab\ by the \keyword{END\_TAG=} + command. +\item Sets the printing mode according to the \keyword{PC\_AT\_END=} command. +\end{enumerate} + +\begin{description} +\item[NOTES]: +\begin{enumerate} +\item Except for the default processing of \keyword{OTHER\_} types, it does not + output the command itself. +\item If a tag action is not specified, then the default action is null (e.g., + nothing will appear in the output). +\end{enumerate} +\end{description} + + Within a \ctab\ all text strings for output are enclosed within double +quotes. For example: +\begin{code} +\begin{verbatim} +START_TAG= "Some "text" string\n another line of text." +\end{verbatim} +\end{code} + + Assuming that \verb|\n| means a newline, when this string action is performed +by \lx\ it will appear in the output file as: +\begin{code} +\begin{verbatim} +Some "text" string +another line of text. +\end{verbatim} +\end{code} + + A text string starts with the first double quote and ends with the last double +quote on the command line. A text string has to be written on a single line +within the \ctab. C language special print characters can be embedded within the +text string (e.g. the \verb|\n| for a newline in the above example). Remember +that the first section of the \ctab\ is used for specifying the +particular \ctab\ version of these. + + If a text string is too long to fit comfortably on a single line in the +\ctab, it may be continued via the \keyword{STRING:} command. As many of these +can be used in succession as required (subject to internal limitations within \lx). + + For instance, +\begin{code} +\begin{verbatim} +START_TAG= "Some "text" string\n" + STRING: "another line of text." +\end{verbatim} +\end{code} +has the same effect as the previous example. + + The following specification is designed to write out the contents of the +\verb|\caption| command\footnote{Strictly speaking, the specification does not +do this exactly, but this simplified illustration will be corrected in +the next sections.}, +preceded by the word `CAPTION' and followed by at least one +blank line (assuming that the escape character has been set to \verb|?|). + +\begin{code} +\begin{verbatim} +TYPE= COMMAND +NAME= \caption + START_TAG= "?n CAPTION " + END_TAG= "?n?n" +END_TYPE +\end{verbatim} +\end{code} +Assuming that somewhere in a \LaTeX\ file there is the command +\begin{code} +\begin{verbatim} +stuff +\caption{This is a caption.} +more stuff +\end{verbatim} +\end{code} +then the expected effect (see footnote) is +\begin{code} +\begin{verbatim} +stuff + + CAPTION This is a caption. + +more stuff +\end{verbatim} +\end{code} + +\subsection{Argument actions} + + \LaTeX\ commands can take arguments. The text for a required argument is +enclosed in curly braces, while the text for an optional argument is enclosed +in square brackets. \lx\ can be directed to perform actions at the start and end +of each argument. + + The number of required arguments is specified by the command line +\keyword{REQPARAMS=} +where the value of the command is a digit between 1 and 9 inclusive. + + \lx\ assumes that a command can have only one optional argument, and that this +is either first or last in the argument list. The potential presence of an +optional argument is indicated by the command line \keyword{OPT\_PARAM=}, +where the +value is either the keyword \keyword{FIRST} (for first in the list) or +\keyword{LAST} (for last in the list). + + The actions to be performed at the start and end of each required argument +are specified via the commands \keyword{START\_TAG\_1=} and \keyword{END\_TAG\_1=} +for the first required argument, through \keyword{START\_TAG\_9=} and +\keyword{END\_TAG\_9=} for the ninth argument. +The actions to be performed at the start and end of the optional argument +are specified by the command lines \keyword{START\_OPT=} and \keyword{END\_OPT=}. + + The argument delimiters (the braces or brackets) are not printed. + + In the simplest case, the action is to print a specified text string +(enclosed in double quotes, and continued with \keyword{STRING:} commands +if necessary). Other kinds of actions are also possible. +An unspecified tag defaults to doing no action. + +\subsubsection{Print options} + +\paragraph{Argument processing} + + By default, \lx\ processes (i.e. outputs as appropriate) +the text of a argument. +Printing of the argument text may be disabled, if required. The command line +that controls argument printing is of the form \keyword{PRINT\_P1=} through +\keyword{PRINT\_P9=} for required arguments and +\keyword{PRINT\_OPT=} for the optional +argument. The value of these commands is one from several keywords, +the most common being \keyword{NO\_PRINT}; this +switches off printing of the text of the indicated argument. +Default printing is resumed after the indicated argument. + + Continuing the caption example from earlier, we can now complete it. The full +syntax of the \LaTeX\ command is: +\begin{code} +\begin{verbatim} +\caption[optional table of contents entry]{Caption in the text} +\end{verbatim} +\end{code} +That is, it has one required argument, which prints the caption text both in +the body of the document and in the table of contents, unless the first optional +argument is present, in which case its value gets printed in the table of +contents instead. + + Assume that an instance of the caption command in a document is: +\begin{code} +\begin{verbatim} +Some stuff +\caption[Short caption]{Long caption for the body of the text.} +More stuff +\end{verbatim} +\end{code} +Recall the previous \ctab\ caption specification. The actual output from +processing this would be +\begin{code} +\begin{verbatim} +Some stuff + + CAPTION [Short caption]{Long caption for the body of the text.} + +More stuff +\end{verbatim} +\end{code} +because, unless \lx\ is told that there are command arguments and how they should +be treated, it will just print them out together with their surrounding +delimiters. + + The following \ctab\ entry will give more acceptable results. +\begin{code} +\begin{verbatim} +TYPE= COMMAND +NAME= \caption + START_TAG= "?n CAPTION " + END_TAG= "?n?n" + OPT_PARAM= FIRST + PRINT_OPT= NO_PRINT + REQPARAMS= 1 +END_TYPE +\end{verbatim} +\end{code} + + For the above captioning instance, the output will now be: +\begin{code} +\begin{verbatim} +Some stuff + + CAPTION Long caption for the body of the text. + +More stuff +\end{verbatim} +\end{code} + + The default print mode is to print text to the output file. + + The keywords that can be used to control argument printing are: +\begin{description} +\item[\keyword{NO\_PRINT}] Do not print anything. +\item[\keyword{TO\_SYSBUF}] Print to the \lx{} system buffer. +\item[\keyword{TO\_BUFFER num}] Print to the \lx{} buffer + number \keyword{num}. +\item[\keyword{TO\_FILE name}] Print to the file called \keyword{name}. +\item[\keyword{NO\_OP}] Skip all processing of the argument. +\end{description} +Note that even if the print mode is set to \keyword{NO\_PRINT}, the +argument text will still be processed. Only the \keyword{NO\_OP} +specification temporarly turns off the processing. + + +\paragraph{General printing} + + Just as the printing mode can be set for each argument, it can also be +set at the start and end of processing a \LaTeX{} command or environment. + + The specifications \keyword{PC\_AT\_START=} and \keyword{PC\_AT\_END=} +can be used to set the printing mode at the start of processing a command +and at the end, respectively. The keywords that can be used in these +specifications are: +\begin{description} +\item[\keyword{NO\_PRINT}] Do not print anything. +\item[\keyword{TO\_SYSBUF}] Print to the \lx{} system buffer. +\item[\keyword{TO\_BUFFER num}] Print to the \lx{} buffer + number \keyword{num}. +\item[\keyword{TO\_FILE name}] Print to the file called \keyword{name}. +\item[\keyword{RESET}] Reset the print mode back to what it was. +\end{description} + + Unlike the argument printing controls, the print mode is not +automatically reset. This has to be explicitly specified. + + As an example, assume that it is required to remove all \keytext{figure} +environments from a \LaTeX{} source and put them into a file on their own. +The following \ctab{} code could be used to accomplish this. +\begin{code} +\begin{verbatim} +TYPE= BEGIN_ENV +NAME= figure + PC_AT_START= TO_FILE allfigs.tex + START_TAG= "?n\begin{figure}" +END_TYPE + +TYPE= END_ENV +NAME= figure + START_TAG= "\end{figure}" + PC_AT_END= RESET +END_TYPE +\end{verbatim} +\end{code} +When a \LaTeX{} \keytext{figure} environment is started, printing is switched +to go to the file called \file{allfigs.tex}. At the end of the \keytext{figure} +environment, the print mode is reset back to what it was before the environment +began. If at the first \keytext{figure} environment the \file{allfigs.tex} +file did not exist, then \lx{} would create it automatically. + +\paragraph{Read actions} + + As noted above, one of the actions that can be specified for a +\LaTeX{} comand's argument is to set the print mode for printing to a buffer +or a file. Similarly there are actions which will read from a buffer or +a file and print the contents. Within an argument tag these kinds of actions are +specified via the keyword \keyword{SOURCE:}. This can take one of several +values: +\begin{description} +\item[\keyword{SYSBUF}] Print the contents of the \lx{} system buffer. +\item[\keyword{BUFFER num}] Print the contents of the \lx{} buffer + number \keyword{num}. +\item[\keyword{FILE name}] Print the contents of the file called + \keyword{name}. +\end{description} + + In a previous example, the \LaTeX{} \keytext{figure} environments +were all written to the file \file{allfig.tex}. This file could be read +in again just before the end of the document so that all figures will be +typeset after everything else. +\begin{code} +\begin{verbatim} +TYPE= END_DOCUMENT + END_TAG= "?n % figures collected here by LTX2X ?n" + SOURCE: FILE allfigs.tex + STRING: "?n\end{document}?n" +END_TYPE +\end{verbatim} +\end{code} + + As another example of the use of the print actions consider the \LaTeX{} +\verb|\maketitle| command. This typesets the arguments of the \verb|\title|, +\verb|\author| and \verb|\date| commands, which must have been previously +specified but not necessarily in this ordering. Here is one way this can +be simulated using \lx. +\begin{code} +\begin{verbatim} +TYPE= COMMAND +NAME= \title + START_TAG= + RESET_BUFFER: 1 + REQPARAMS= 1 + PRINT_P1= TO_BUFFER 1 +END_TYPE + +TYPE= COMMAND +NAME= \author + START_TAG= + RESET_BUFFER: 2 + REQPARAMS= 1 + PRINT_P1= TO_BUFFER 2 +END_TYPE + +TYPE= COMMAND +NAME= \date + START_TAG= + RESET_BUFFER: 3 + REQPARAMS= 1 + PRINT_P1= TO_BUFFER 3 +END_TYPE + +TYPE= COMMAND +NAME= \maketitle + START_TAG= "?n" + SOURCE: BUFFER 1 + STRING: "?n?n" + SOURCE: BUFFER 2 + STRING: "?n?n" + SOURCE: BUFFER 3 + STRING: "?n?n" + END_TAG= + RESET_BUFFER: 1 + RESET_BUFFER: 2 + RESET_BUFFER: 3 +END_TYPE +\end{verbatim} +\end{code} +For the \verb|\title| command, the print mode for its argument is set +for printing to the buffer number~1. The single action at the start of +the command is to make sure that buffer~1 is empty (the line +\keyword{RESET\_BUFFER: 1}). The actions for the \verb|\author| and +\verb|\date| commands are similar, except that they print their argument +texts to buffers~2 and~3 respectively. + + The \verb|\maketitle| command takes no arguments, so all actions +must be placed under \keyword{START\_TAG=} and/or \keyword{END\_TAG=}. +There are a set of actions specified for \keyword{START\_TAG=}. Firstly +a newline is printed and this is followed by the contents of buffer~1 +(i.e., the text of the argument of the \verb|\title| command). +Then two new lines are printed, followed by the contents of buffer~2 +(the author). Finally another two newlines are printed, the contents +of buffer~3 (the date), and another two newlines. The actions +for \keyword{END\_TAG=} are to clear the contents of the three buffers. + + Just to extend the example, here is a specification for the +\LaTeX{} \verb|\thanks| command. \lx{} is not designed to do footnoting +(as it does not do page breaking) +so instead the thanks text will be placed inside parentheses on a new line. +\begin{code} +\begin{verbatim} +TYPE= COMMAND +NAME= \thanks + START_TAG= "?n (" + REQPARAMS= 1 + END_TAG= ") " +END_TYPE +\end{verbatim} +\end{code} + + + Given these \ctab{} specification and the following portion of a +\LaTeX{} document +\begin{code} +\begin{verbatim} +\date{29 February 2000} +\title{The Calculation of Leap Days\thanks{Originally published in JIR}} +\author{A. N. Other} +... +\maketitle +\end{verbatim} +\end{code} +then output from \lx{} will be: +\begin{code} +\begin{verbatim} +The Calculation of Leap Days + (Originally published in JIR) + +A. N. Other + +29 February 2000 +\end{verbatim} +\end{code} +Note that as the \verb|\thanks| command appears within the argument of the +\verb|\title| command, it is written to the same place as the text of +the argument of \verb|\title|. Thus, it also gets written to the output file +when \verb|\maketitle| is processed. + +\subsubsection{Print switching} + + There are individual actions that enable the printing destination +to be changed at will within the action set for any particular tag. +\begin{description} +\item[\keyword{SWITCH\_TO\_BUFFER: num}] Direct any following printing + to the \lx{} buffer number \keyword{num}. +\item[\keyword{SWITCH\_TO\_FILE: name}] Direct any following printing + to the file called \keyword{name}. +\item[\keyword{SWITCH\_TO\_SYSBUF}] Direct any following printing + to the \lx{} system buffer. +\item[\keyword{SWITCH\_BACK:}] Undo the effect of the last + \keytext{SWITCH\_TO...} action. +\end{description} + + As an example of the utility of this type of action, consider +again the \LaTeX{} \verb|\maketitle| command. When \LaTeX{} processes +this command, it typesets the date as specified by the \verb|\date| +command, or if this has not been specified then it prints the current +date instead. We can arrange for \lx{} to do something similar by +adding the following to the \ctab{} shown earlier for the \verb|\date| +and \verb|\maketitle| commands. +\begin{code} +\begin{verbatim} +TYPE= COMMAND +NAME= \documentclass + OPT_PARAM= FIRST + REQPARAMS= 1 + PRINT_OPT= NO_PRINT + PRINT_P1= NO_PRINT + START_TAG= + c= Initialise buffer 3 to `Today' + RESET_BUFFER: 3 + SWITCH_TO_BUFFER: 3 + STRING: "Today" + SWITCH_BACK: +END_TYPE +\end{verbatim} +\end{code} + At the start of the document, the above actions put the string +\keytext{Today} into \keytext{BUFFER 3}, having first ensured that it is +empty. If the \LaTeX{} source includes a \verb|\date| command, then +the contents of the buffer will be overwritten, otherwise it will be +as initialised. In any event, when the \verb|\maketitle| command is +processed, the value output for the date will be either \keytext{Today} +or whatever the argument was of the \verb|\date| command. + +\subsubsection{Notes on the use of buffers and files} + + Resetting a buffer or a file always has the effect of emptying it +of an prior contents. + + When printing from a buffer or a file, the entire contents are +printed. There is no limit to the number of times that a buffer +or a file can be used as a printing source. + + When printing to a buffer, the new strings are appended at +the end of the current contents of the buffer, at least until it +overflows. Unlike the behaviour of files, +this is independant of any intervening prints from the buffer. + + When printing to a file, the new strings are appended at the +end of the current contents of the file. However, if a file is printed +to after it has been printed from, the prior contents of the file +are lost, and the new string is added at the start of the file. +In general, it is safest to treat files as either read-only or write-only. + + + +\subsubsection{User specified modes} + + Consider the \LaTeX{} command \verb|\\|. In normal text this signifies +that a line break must occur. In a \verb|tabular| environment, though, +it signifies the end of a row in a table. Suppose that in the \lx{} +procesing of a tabular environment it is required to start and end each +row with a vertical bar and to seperate each column also with a vertical +bar. However, in normal text a \verb|\\| command should just translate +into a newline. Just to complicate matters further, assume that in +an \verb|eqnarray| environment, the \verb|&| column seperator is to +be translated to some spaces, and that the string `(X)' is to be +put at the end of every row. + + In other words, we need to process some commands differently +according to where they appear in the LaTeX{} source. An \lx{} \ctab{} +provides this capability through mode setting and mode-dependent actions. +Here is an example of using this facility to solve the requirements +outlined above. +\begin{code} +\begin{verbatim} +TYPE= BEGIN_ENV +NAME= tabular + C= starting actions, etc., here + END_TAG= + SET_MODE: tabular +END_TYPE + +TYPE= END_ENV +NAME= tabular + START_TAG= + RESET_MODE: +END_TYPE + +TYPE= BEGIN_ENV +NAME= eqnarry + C= starting actions, etc., here + END_TAG= + SET_MODE: eqn +END_TYPE + +TYPE= END_ENV +NAME= eqnarray + START_TAG= " (X)?n" + RESET_MODE: +END_TYPE + +TYPE= TEX_CHAR +NAME= & + START_TAG= " | " +IN_MODE= eqn + START_TAG= " " +END_MODE +END_TYPE + +TYPE= CHAR_COMMAND +NAME= \\ + START_TAG= "?n" +IN_MODE= tabular + START_TAG= " |?n" + STRING: " | " +END_MODE +IN_MODE= eqn + START_TAG= " (X)?n" +END_MODE +END_TYPE +\end{verbatim} +\end{code} + + Let us look at the specification for the \verb|\tabular| environment first. +The \keyword{END\_TAG=} action is specified by the single command line +\keyword{SET\_MODE:}~\keytext{tabular}, where \keytext{tabular} is any convenient +name for identifying a mode. Thus, this will set the mode to be \keytext{tabular}. +The action at the end of the environment is to reset the mode +(\keyword{RESET\_MODE:}) +to whatever its previous value was. It is assumed that the last row in any +\verb|tabular| environment is finished by \verb|\\|. Similar actions are +performed for the \verb|eqnarray| environment, except that the mode is called +\keytext{eqn} instead of \keytext{tabular}. The other difference is that it +is assumed that the last row is not ended by \verb|\\|, so the end of +the \verb|eqnarray| environment has to also act like the \verb|\\|. + + Turning now to the specification for the \verb|&| command, the first part +of the specification identifies the type and name of the \LaTeX{} command. +This is then followed by the mode-independent set of actions, +which in this case +consists of printing a vertical bar with some spaces on either side of it. +Following these are any mode-dependent actions, bracketed between +\keyword{IN\_MODE=} and \keyword{END\_MODE}. The value for \keyword{IN\_MODE=} +is the name of the relevent mode. In this case the only mode-dependent +action occurs when \keytext{MODE eqn} is in effect and it is to print +some spaces instead of the default spaces and vertical bar. + + The specification for the \verb|\\| command has its set of +mode-independent default actions, +namely just to print a newline, and two sets of mode-dependent actions. +When the \keytext{tabular} mode is in effect, it prints some spaces, a vertical +bar, a newline, more spaces, a vertical bar, and finally some more spaces. +On the other hand, when the \keytext{eqn} mode is in effect, it prints some +spaces, the string `(X)' and a newline. If a mode is in effect +that is not defined within the specification (e.g., mode \keytext{anon}) +it performs the default mode-independent actions. + + As a perhaps more practical example, the following \ctab{} code will +convert simple \LaTeX{} \verb|tabular| + environments to appropriate mark-up for HTML tables. It is assumed that +the \verb|tabular| environment is always within a \verb|table| environment. + + To set the perspective a little, here is the code for a simple table +in \LaTeX: +\begin{code} +\begin{verbatim} +\begin{table}[tbp] +\centering +\caption{A simple table typeset by \LaTeX.} \label{tab:lxtab} +\begin{tabular}{|l||r|r||r|r|} \hline +Stock & \multicolumn{2}{c||}{1994} & \multicolumn{2}{c|}{1995} \\ \cline{2-5} + & low & high & low & high \\ \hline +ABC & 27 & 36 & 23 & 45 \\ +DEF & 53 & 72 & 19 & 54 \\ +GHI & 28 & 49 & 17 & 79 \\ \hline +\end{tabular} +\end{table} +\end{verbatim} +\end{code} +This will be typeset as shown in table~\ref{tab:lxtab}. +\begin{table}[tbp] +\centering +\caption{A simple table typeset by \LaTeX.} \label{tab:lxtab} +\begin{tabular}{|l||r|r||r|r|} \hline +Stock & \multicolumn{2}{c||}{1994} & \multicolumn{2}{c|}{1995} \\ \cline{2-5} + & low & high & low & high \\ \hline +ABC & 27 & 36 & 23 & 45 \\ +DEF & 53 & 72 & 19 & 54 \\ +GHI & 28 & 49 & 17 & 79 \\ \hline +\end{tabular} +\end{table} + + The corresponding HTML code for the table after translation is: +\begin{latexonly} +\begin{code} +\begin{verbatim} +

+ + + + + + + +
A simple table typeset by LaTeX.
Stock 1994 1995
+ low high low high
ABC 27 36 23 45
+DEF 53 72 19 54
+GHI 28 49 17 79
+
+\end{verbatim} +\end{code} +\end{latexonly} + +\begin{code} +\begin{htmlverbatim} +\ST{p}\ST{center}\ST{table border} +\ST{caption}A simple table typeset by LaTeX.\ET{caption} \ST{a name="tab:lxtab"}\ET{a} + +\ST{tr}\ST{td} Stock \ET{td}\ST{td colspan=2} 1994 \ET{td}\ST{td colspan=2} 1995 \ET{tr} +\ST{tr}\ST{td} + \ET{td}\ST{td} low \ET{td}\ST{td} high \ET{td}\ST{td} low \ET{td}\ST{td} high \ET{tr} +\ST{tr}\ST{td} ABC \ET{td}\ST{td} 27 \ET{td}\ST{td} 36 \ET{td}\ST{td} 23 \ET{td}\ST{td} 45 \ET{tr} +\ST{tr}\ST{td} +DEF \ET{td}\ST{td} 53 \ET{td}\ST{td} 72 \ET{td}\ST{td} 19 \ET{td}\ST{td} 54 \ET{tr} +\ST{tr}\ST{td} +GHI \ET{td}\ST{td} 28 \ET{td}\ST{td} 49 \ET{td}\ST{td} 17 \ET{td}\ST{td} 79 \ET{tr} +\ST{tr}\ST{td} +\ET{table}\ET{center} +\end{htmlverbatim} +\end{code} + + In the HTML browser that I use this is displayed +approximately as shown for table~\ref{tab:httab}. + +\begin{table}[tbp] +\centering +\caption{A simple table typeset after translation to HTML.} \label{tab:httab} +\begin{tabular}{||l|l|l|l|l||} \hline\hline +Stock & \multicolumn{2}{l||}{1994} & \multicolumn{2}{l|}{1995} \\ \hline + & low & high & low & high \\ \hline +ABC & 27 & 36 & 23 & 45 \\ +DEF & 53 & 72 & 19 & 54 \\ +GHI & 28 & 49 & 17 & 79 \\ \hline \hline +\end{tabular} +\end{table} + + In HTML a table is enclosed between +\keytext{\ST{table}} and \keytext{\ET{table}} tags. +Each row of the table is enclosed between +\keytext{\ST{tr}} and \keytext{\ET{tr}} tags, +and each element in a row is enclosed between +\keytext{\ST{td}} and \keytext{\ET{td}} tags. +Under certain circumstances the closing tags (i.e., +those like \keytext{\ET{...}}) +can be inferred by the HTML procesors and need +not be explicitly put into the source text. The equivalent HTML tags to a +\LaTeX{} \verb|\multicolumn{num}{col}{text}| command are\\ +\keytext{\ST{td colspan=num} text \ET{td}}. + + The general actions that \lx{} has to perform in doing the \LaTeX{} to +HTML translation are: +\begin{itemize} +\item The start and end of a \verb|table| environment has to translate to + the HTML start and end table tags \keytext{\ST{table}} and + \keytext{\ET{table}}. + (Actually this also needs to handle the + centering of the HTML table and drawing a border round it as well.) + +\item The start and end of the \verb|tabular| environment has to translate + into a row start + \keytext{\ST{tr}\ST{td}} and end \keytext{\ET{tr}} + in the HTML table (and set the mode for the + \LaTeX{} \verb|\\| command). + +\item The \verb|\\| command must end one row of the HTML table and start the + next row + (\keytext{\ET{tr}?n\ST{tr}\ST{td}}). + It need not end a data element as + this is automatically closed by the end of the row. + +\item The \verb|&| column delimeter must end one HTML data element and start + another one (i.e., \keytext{\ET{td}\ST{td}}). + +\item The difficulty is in handling the \verb|\multicolumn| command. In the easy + case the \LaTeX{} to HTML translation is: \\ + \keytext{... \Amp{} text \Amp{} ...} maps to \\ + \keytext{... \ET{td}\ST{td} text \ET{td}\ST{td} ...}. \\ + However, when a multicolumn is involved the translation is \\ +\verb|... & \multicolumn{N}{P}{text} & ...| maps to \\ +\keytext{... \ET{td}\ST{td colspan=N} text \ET{td}\ST{td} ...}. \\ +As there is no look-ahead in \lx{} we have to be careful about starting a +data element after a \verb|&| because at that point \lx{} cannot know +whether or not a \verb|\multicolumn| command comes next, or just an ordinary +data element. + +\end{itemize} + + We solve this last problem partly by using buffers +(numbers \keytext{8} and \keytext{9} in the specification below) +as temporary storage, and partly by a subtle specification for the +\verb|\multicolumn| command. + +\begin{latexonly} +\begin{code} +\begin{verbatim} +C= start of a table +TYPE= BEGIN_ENV +NAME= table + START_TAG= "
" + OPT_PARAM= FIRST + C= ignore the optional positioning argument + PRINT_OPT= NO_PRINT +END_TYPE + +C= end a table +TYPE= END_ENV +NAME= table + START_TAG= "
" +END_TYPE + +C= start a tabular +TYPE= BEGIN_ENV +NAME= tabular + START_TAG= "?n " + RESET_BUFFER: 8 + SOURCE: BUFFER 9 + END_TAG= "?n " + RESET_BUFFER: 8 + SOURCE: BUFFER 9 + END_TAG= " + + + +The command table file + + By default, ... +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +... +\ET{div.2} +\ET{div.1} + +\ST{div.1} +\ST{heading}The command table file\ET{heading} + + By default, ... +\end{htmlverbatim} + +\subsection{List environment types} + + In \LaTeX\ the use of the \verb|\item| command is restricted to within a +list environment. The typeset appearance of an \verb|\item| typically depends +on the particular environment in which it is used. \lx\ has a limited capability +of modifying its \verb|\item| tagging output. It can also provide an `end item' +tag for those tagging systems that require such a thing. + + For such list environments, identified by the command type keyword +\keyword{BEGIN\_LIST\_ENV}, +the following command lines should be included within the type specification. +\begin{description} +\item[\keyword{START\_ITEM=}] Actions to be performed at the start + of each \verb|\item| command in the list. +\item[\keyword{END\_ITEM=}] Actions to be performed after processing all + the \verb|\item|'s text. +\item[\keyword{START\_ITEM\_PARAM=}] Actions to be performed at the start of an + \verb|\item|'s optional argument text. +\item[\keyword{END\_ITEM\_PARAM=}] Actions to be performed at the end of an + \verb|\item|'s optional argument text. +\end{description} +As usual, an unspecified tag defaults to no actions. + + For example, assume that we are not interested in tagging the end of an item, +but we do want to mark each item in an \verb|itemize| environment with the lowercase +letter `o', each \verb|enumerate| item with `(N)' and put a colon after the +optional argument in a description environment. Also, each item should have some +indentation from the left hand margin. + +\begin{code} +\begin{verbatim} +TYPE= BEGIN_LIST_ENV +NAME= itemize + START_ITEM= "?n o " +END_TYPE + +TYPE= END_LIST_ENV +NAME= itemize +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= enumerate + START_ITEM= "?n (N) " +END_TYPE + +TYPE= END_LIST_ENV +NAME= enumerate +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= description + START_ITEM= "?n " + END_ITEM_PARAM= " : " +END_TYPE + +TYPE= END_LIST_ENV +NAME= description +END_TYPE +\end{verbatim} +\end{code} + + With the above commands, this \LaTeX{} text: +\begin{verbatim} +\begin{description} +\item[An example] + \begin{itemize} + \item the first item; + \item the second item. + \end{itemize} +\end{description} +\end{verbatim} +will be transformed into: +\begin{verbatim} + An example : + o the first item; + o the second item. +\end{verbatim} + +\subsection{Character types} + + \LaTeX\ treats some characters specially. These special characters are: +\verb|#|, +\verb|$|, +\verb|%|, +\verb|&|, +\verb|~|, +\verb|_|, +\verb|^|, +\verb|\|, +\verb|{|, +\verb|}|, +and, under some circumstances, also the +character \verb|@|. + \lx\ recognizes these special characters and, if directed, will +perform specified actions; otherwise it treats them as it treats any alphanumeric +character, which is just to print it. + + It has already been stated that commands for the left and right braces +(i.e. \verb|{| and \verb|}|) must be given +within the \ctab\ as command types +\keyword{LBRACE}, \keyword{RBRACE} respectively. +The dollar symbol (\$) must also be specified via the two command types +\keyword{BEGIN\_DOLLAR} and \keyword{END\_DOLLAR}. Here is an +example of replacing the dollar signs by tags intended to indicate +the start and end of a mathematical phrase. +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= BEGIN_DOLLAR + START_TAG= "" +END_TYPE + +TYPE= END_DOLLAR + START_TAG= "" +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= BEGIN\_DOLLAR + START\_TAG= "\ST{math}" +END\_TYPE + +TYPE= END\_DOLLAR + START\_TAG= "\ET{math}" +END\_TYPE +\end{htmlverbatim} + + Commands for the other special \LaTeX\ characters are specified with the +\keyword{TEX\_CHAR} command type keyword. + +The characters \verb|_| (underscore) and \verb|^| (caret) are used in +\LaTeX{} math mode to indicate subscripting and superscripting respectively. The +following will replace \verb|^| by \keytext{\ST{sup}}, print the superscript +text (which must be enclosed in braces\footnote{It is good practice to +always enclose superscript and subscript text in braces, even though +\TeX\ does not always require this.}) and at the end close with +\keytext{\ET{sup}}. +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= TEX_CHAR +NAME= ^ + START_TAG= "" + REQPARAMS= 1 + END_TAG= "" +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} + +\begin{htmlverbatim} +TYPE= TEX\_CHAR +NAME= \verb|^| + START\_TAG= "\ST{sup}" + REQPARAMS= 1 + END\_TAG= "\ET{sup}" +END\_TYPE +\end{htmlverbatim} + +Given the above specifications, then \verb|$(2^{15} - 1)$| will be transformed +into \\ +\keytext{\ST{math}(2\ST{sup}15\ET{sup} - 1)\ET{math}}. + +\subsection{Verbatim like types} + + The command type \keyword{VCOMMAND} is for the procesing of \LaTeX{} +\verb|\verb|-like commands where the argument of the command is to be +typeset as-is. For example, there might be a command called \verb|\url| +which takes one argument which is meant to be an Internet URL. If the +application was the conversion of a \LaTeX{} document to HTML, then the +following specification could be useful. +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= VCOMMAND +NAME= \url + REQPARAMS= 1 + PRINT_P1= TO_BUFFER 7 + START_TAG= + RESET_BUFFER: 7 + END_TAG= "" + SOURCE: BUFFER 7 + STRING: "" + RESET_BUFFER: 7 +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= VCOMMAND +NAME= \verb|\url| + REQPARAMS= 1 + PRINT\_P1= TO\_BUFFER 7 + START\_TAG= + RESET\_BUFFER: 7 + END\_TAG= "\LT{}a href="" + SOURCE: BUFFER 7 + STRING: ""\GT" + SOURCE: BUFFER 7 + STRING: "\ET{a}" + RESET\_BUFFER: 7 +END\_TYPE +\end{htmlverbatim} + +If the \LaTeX{} source included: +\begin{code} +\begin{verbatim} +... obtainable from +\url{http://www.cdrom.com/pub/tex} +\end{verbatim} +\end{code} +then the resulting \lx{} output would be: +\begin{latexonly} +\begin{code} +\begin{verbatim} +... obtainable from +http://www.cdrom.com/pub/tex +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +... obtainable from +\ST{a href="http://www.cdrom.com/pub/tex"}http://www.cdrom.com/pub/tex\ET{a} +\end{htmlverbatim} +which, if this was then read via an appropriate browser, a link to the URL +\begin{htmlonly} +http://www.cdrom.com/pub/tex +\end{htmlonly} +would be automatically established. + + Similarly \verb|verbatim|-like environments can also be specified with +the types \keyword{BEGIN\_VENV} and \keyword{END\_VENV}. +For example, the \file{html.sty} package defines three \LaTeX{} +environments for documents that might be converted from \LaTeX{} tagging +to HTML tagging. One of these, \verb|latexonly| is for \LaTeX{} code +that is not to occur in the HTMLed document and another is \verb|htmlonly| +which contains HTML code that is required for an HTML version +of the document but which is not to appear in the \LaTeX ed document. +The third one is \verb|rawhtml| which is for HTML code to be output +verbatim to the HTML document source. +These could be simulated by: +\begin{code} +\begin{verbatim} +TYPE= BEGIN_VENV +NAME= latexonly + PC_AT_START= NO_PRINT +END_TYPE + +TYPE= END_VENV +NAME= latexonly + PC_AT_END= RESET +END_TYPE + +TYPE= BEGIN_ENV +NAME= htmlonly +END_TYPE + +TYPE= END_ENV +NAME= htmlonly +END_TYPE + +TYPE= BEGIN_VENV +NAME= rawhtml +END_TYPE + +TYPE= END_VENV +NAME= rawhtml +END_TYPE +\end{verbatim} +\end{code} + + +\subsection{Odd command types} + + The majority of commands in \LaTeX{} that take optional arguments +have only a single optional argument that is either immediately after +the command or after all the required arguments. There are, however, some +commands that do not fit this pattern. This set of command types enables +at least some of these `odd' commands to be handled. + + The command type keyword is of the form \keytext{COMMAND\_code}, where +\keytext{code} indicates the type and ordering of the arguments. The +\keytext{code} is composed from combinations of the letters \keytext{O} +(for an optional argument) and \keytext{P} (for a required parameter (i.e., +argument)). The ordering of these letters in the \keytext{code} specifies +the type and ordering of the command's arguments. + + The `odd' command types are: +\begin{description} +\item[\keyword{COMMAND\_OOP}] Corresponding to a \LaTeX{} command of the form \\ +\verb|\com[OptParam][OptParam]{ReqParam}|. +For example, the \verb|\makebox| +command falls into this category. + +\item[\keyword{COMMAND\_OOOPP}] Corresponding to a \LaTeX{} command of the form \\ +\verb|\com[OptParam][OptParam][OptParam]{ReqParam}{ReqParam}|. +For example, the \verb|\parbox| +command falls into this category. + +\item[\keyword{COMMAND\_OPO}] Corresponding to a \LaTeX{} command of the form \\ +\verb|\com[OptParam]{ReqParam}[OptParam]|. +For example, the \verb|\RequirePackage| and \verb|\LoadClass| +commands fall into this category. + +\item[\keyword{COMMAND\_POOOP}] Corresponding to a \LaTeX{} command of the form \\ +\verb|\com{ReqParam}[OptParam][OptParam][OptParam]{ReqParam}|. + +\item[\keyword{COMMAND\_POOP}] Corresponding to a \LaTeX{} command of the form \\ +\verb|\com{ReqParam}[OptParam][OptParam]{ReqParam}|. +For example, the \verb|\newcommand| and its companion commands +fall into this category. + +\item[\keyword{COMMAND\_POOPP}] Corresponding to a \LaTeX{} command of the form \\ +\verb|\com{ReqParam}[OptParam][OptParam]{ReqParam}{ReqParam}|. +For example, the \verb|\newenvironment| and its companion command +fall into this category. +\end{description} + + As usual, the command name is required, as are any actions. However, +it is not necessary to specify the number of required arguments (i.e. +\keyword{REQPARAMS=}) nor the position of the optional argument (i.e. +\keyword{OPT\_PARAM=}), as \lx\ already has this information. The tag actions +are according to the argument ordering given in the \keytext{code} and are +specified by the required argument tags (e.g. \keytext{START\_TAG\_n=} and +\keytext{END\_TAG\_n=}). +Do not use any of the command lines for optional arguments. Argument +actions are controlled in the usual manner. + + A typical example of the use of these commands is to supress any processing +of the \LaTeX{} \verb|\newcommand| and its ilk. For example: +\begin{code} +\begin{verbatim} +TYPE= COMMAND_POOP +NAME= \providecommand + PRINT_P1= NO_OP + PRINT_P2= NO_OP + PRINT_P3= NO_OP + PRINT_P4= NO_OP +END_TYPE + +TYPE= COMMAND_POOPP +NAME= \renewenvironment + PRINT_P1= NO_OP + PRINT_P2= NO_OP + PRINT_P3= NO_OP + PRINT_P4= NO_OP + PRINT_P5= NO_OP +END_TYPE +\end{verbatim} +\end{code} + + +\subsection{Other command types} + + The \keytext{OTHER\_} command types (\keyword{OTHER\_COMMAND}, +\keyword{OTHER\_BEGIN} +and \keyword{OTHER\_END}) +are very limited in what can be affected. Basically, these provide for +default printing actions if the corresponding \LaTeX\ command has not been +identified elsewhere in the \ctab. + + If there are no commands within the specification, the name of the command and +all its arguments will be printed verbatim. + + The command lines \keyword{START\_TAG=} and \keyword{END\_TAG=} +cause the corresponding +actions to be performed before and after the name of the command is printed. Any +arguments are printed verbatim. + + The command line \keyword{PRINT\_CONTROL=} with a value of \keyword{NO\_PRINT} +causes the command name not to be printed, nor any arguments that \lx\ may +find associated with the command. + +\subsection{Picture types} + + The \keytext{\_PICTURE\_} command types differ from all the other types in +\lx, just as they do in \LaTeX. In \LaTeX\ some of the picture drawing commands +take arguments of the form \verb|(number, number)|, representing a coordinate +pair, as well as the usual +required arguments enclosed in curly braces and possibly an optional +argument enclosed in square brackets. Within \lx, commands that take coordinate +arguments are treated specially in the \ctab. + + Generally speaking, the \lx\ command types are of the form +\keytext{PICTURE\_code}, +where \keytext{code} indicates the type and ordering of the arguments. The +\keytext{code} is composed from combinations of the letters \keytext{C} (for a +coordinate argument), \keytext{O} (for an optional argument) and \keytext{P} (for +a required argument). For example, \keyword{PICTURE\_PCOP} indicates a picture +command that has a required argument, followed by a coordinate argument, +followed by an optional argument and finally another required argument. + + The provided picture types are: +\begin{description} +\item[\keyword{BEGIN\_PICTURE\_CC}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\begin{PictureEnv}(coords)(coords)|, where the final coordinate argument + is optional. +\item[\keyword{PICTURE\_CCPP}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com(coords)(coords){ReqParam}{ReqParam}|. + For example, the \verb|\multiput| command falls into this category. +\item[\keyword{PICTURE\_CO}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com(coords)[OptParam]|. + For example, the standard \LaTeX\ \verb|\oval| command falls into + this category. +\item[\keyword{PICTURE\_COP}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com(coords)[OptParam]{ReqParam}|. + For example, the \verb|\makebox| and \verb|\framebox| commands fall + into this category. +\item[\keyword{PICTURE\_CP}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com(coords){ReqParam}|. + For example, the \verb|\put|, \verb|\line| and \verb|\vector| commands + fall into this category. +\item[\keyword{PICTURE\_OCC}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com[OptParam](coords)(coords)|. + For example, the \verb|\graphpaper| command from the \verb|graphpap| + package falls into this category. +\item[\keyword{PICTURE\_OCCC}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com[OptParam](coords)(coords)(coords)|. + For example, the \verb|\qbezier| command falls into this category. +\item[\keyword{PICTURE\_OCO}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com[OptParam](coords)[OptParam]|. + For example, the \verb|\oval| command from the \verb|pict2e| package + falls into this category. +\item[\keyword{PICTURE\_PCOP}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\com{ReqParam}(coords)[OptParam]{ReqParam}|. + For example, the \verb|\dashbox| and \verb|\savebox| commands fall + into this category. +\item[\keyword{END\_PICTURE}] Corresponding to a \LaTeX\ command of the form \\ + \verb|\end{PictureEnv}|. +\end{description} + + As usual, the command name is required, as are any actions. However, +it is not necessary to specify the number of required arguments (i.e. +\keyword{REQPARAMS=}) nor the position of the optional argument (i.e. +\keyword{OPT\_PARAM=}), as \lx\ already has this information. The tag actions +are according to the argument ordering given in the \keytext{code} and are +specified by the required argument tags (e.g. \keytext{START\_TAG\_n=} and +\keytext{END\_TAG\_n=}). +Do not use any of the command lines for optional arguments. Argument +actions controlled in the usual manner. + + As an example, the following specifications within a \ctab\ should be +sufficient to ensure that any picture commands in a source file are +not passed through to the output file. + +\begin{code} +\begin{verbatim} +TYPE= BEGIN_PICTURE_CC +NAME= picture +PRINT_P1= NO_PRINT +PRINT_P2 = NO_PRINT +END_TYPE + +TYPE= PICTURE_CP +NAME= \put +PRINT_P1= NO_PRINT +PRINT_P2= NO_OP +END_TYPE + +TYPE= PICTURE_CCPP +NAME= \multiput +PRINT_P1= NO_PRINT +PRINT_P2= NO_PRINT +PRINT_P3= NO_OP +PRINT_P4= NO_OP +END_TYPE + +TYPE= PICTURE_PCOP +NAME= \savebox +PRINT_P1= NO_OP +PRINT_P2= NO_PRINT +PRINT_P3= NO_OP +PRINT_P4= NO_OP +END_TYPE + +TYPE= PICTURE_OCC +NAME= \graphpaper +PRINT_P1= NO_OP +PRINT_P2= NO_PRINT +PRINT_P3= NO_PRINT +END_TYPE + +TYPE= PICTURE_OCCC +NAME= \qbezier +PRINT_P1= NO_OP +PRINT_P2= NO_PRINT +PRINT_P3= NO_PRINT +PRINT_P4= NO_PRINT +END_TYPE + +TYPE= END_PICTURE +NAME= picture +END_TYPE +\end{verbatim} +\end{code} + +\begin{description} +\item[NOTE 1:] The action \keyword{NO\_OP} cannot be applied to an + argument that is a coordinate pair. + +\item[NOTE 2:] As \lx\ is essentially limited to printing actions, +and cannot actually process any +\LaTeX\ picture drawing commands, the suppression of picture printing is +probably the most usual use of the picture commands. +\end{description} + +\subsection{Special command types} + + The \keytext{SPECIAL\_} commands, namely \keyword{SPECIAL\-\_COMMAND}, +\keyword{SPECIAL\-\_BEGIN\-\_ENV}, + \keyword{SPECIAL\-\_BEGIN\-\_LIST}, +\keyword{SPECIAL\-\_END\-\_ENV}, +\keyword{SPECIAL\-\_END\-\_LIST} and +\keyword{SPECIAL\-\_SECTIONING}, are provided for cases where some special kind of +output processing is required that is not built into \lx. In order to implement +any commands of these types, it is necessary to modify the internals of \lx\ +and recompile the source code. This is not recommended. + +\subsection{File inclusion} + + A \ctab\ file can include other \ctab\ files. In turn an included +file can recursively include other \ctab\ files. The file inclusion command +line is +\begin{code} +\begin{verbatim} +INCLUDE= FileName +\end{verbatim} +\end{code} +where \keyword{FileName} is the name of the \ctab\ file to be included. The effect +is that the above line is replaced by the contents of \keyword{FileName}. + + For example, assume that there are three \ctab\ files called respectively +\file{detex.ct}, \file{detex.l2x} and \file{detex.fl}. The contents of these +files are: +\begin{code} +\begin{verbatim} +C= ----------file detex.ct +... +INCLUDE= detex.l2x +... +C= ----------end of detex.ct +END_CTFILE= end of detex.ct +\end{verbatim} +\end{code} +and for \file{detex.l2x} as: +\begin{code} +\begin{verbatim} +C= ---------- file detex.l2x + +TYPE= COMMAND +NAME= \lx + START_TAG= "LTX2X" +END_TYPE + +INCLUDE= detex.fl + +TYPE= COMMAND +NAME= \ctab + START_TAG= "command table" +END_TYPE + +C= ---------- end of file detex.l2x +END_CTFILE= end of file detex.l2x +\end{verbatim} +\end{code} +and lastly \file{detex.fl} is: +\begin{code} +\begin{verbatim} +C= ---------- file detex.fl + +TYPE= COMMAND +NAME= \fl + START_TAG= "FLaTTeN" +END_TYPE + +C= ---------- end file detex.fl +END_CTFILE= end file detex.fl +\end{verbatim} +\end{code} + Then, as far as \lx\ is concerned, the original \file{detex.ct} file is +treated as though it had been written as: +\begin{code} +\begin{verbatim} +C= ----------file detex.ct +... +C= ---------- file detex.l2x + +TYPE= COMMAND +NAME= \lx + START_TAG= "LTX2X" +END_TYPE + +C= ---------- file detex.fl + +TYPE= COMMAND +NAME= \fl + START_TAG= "FLaTTeN" +END_TYPE + +C= ---------- end file detex.fl + +TYPE= COMMAND +NAME= \ctab + START_TAG= "command table" +END_TYPE + +C= ---------- end of file detex.l2x +... +C= ----------end of detex.ct +END_CTFILE= end of detex.ct +\end{verbatim} +\end{code} + + Note that nasty things will happen if you have a cycle of inclusions. That is, +you must not have anything similar to file \file{A} including file \file{B} which +includes file \file{C} which in turn includes either file \file{A} or \file{B}. + +\subsection{Interpreter commands} \label{sec:intcom} + + \lx\ includes an interpreter for a procedural programming language +that is based on the ISO international standard \Express{} information +modeling language~\cite{EBOOK, EXPRESSIS}. At the moment the +programming language within \lx{} is anonymous, but for ease +of reference I will call it \ExpressA +(\Express{} -Almost? -Approximate? -Anonymous?). +The \ExpressA{} language is described later in section~\ref{sec:expressa}, +but for now it is sufficient to know the commands that signify +the start and end of this code. + + The command \keyword{CODE\_SETUP=} indicates the commencement of +code to be run before any document processing occurs. The +\keyword{END\_CODE} command signifies the end of this code block. +This block should be placed in the \ctab{} before any other commands +except for the \keytext{ESCAPE...} commands, if any. This block +can contain variable declarations, function and procedure declarations, +and statements. + + Code consisting purely of statements can be placed anywhere that +a tagging action may be specified. These statements are enclosed +between a \keyword{CODE:} and \keyword{END\_CODE} pair of commands. + + The \ExpressA{} language is described in detail in \ref{sec:expressa}, +but to give a flavour of it here +is a simple possible application. It has been noted that \lx{} will find +difficulty in processing the contents of the \LaTeX{} \keytext{picture} +environment. The following portions of a \ctab{} write the contents +of a \keytext{figure} environment to an external file and uses the programming +language to keep a count of the number of figures so processed. + +\begin{code} +\begin{verbatim} +c= declare and initialise a variable +CODE_SETUP= + LOCAL + fignum : INTEGER; + END_LOCAL; + fignum := 0; +END_CODE + +c= write figure contents to an external file +TYPE= BEGIN_ENV +NAME= figure + OPT_PARAM= FIRST + PRINT_OPT= NO_PRINT + PC_AT_START= TO_FILE figs.tmp + START_TAG= + CODE: + fignum := fignum + 1; -- increment figure counter + println; -- print a blank line + println('%%% FIGURE ', fignum); -- write counter as a LaTeX comment + END_CODE + STRING: "\begin{figure}" +END_TYPE + +c= close figure environment, back to normal output, and output +c= text indicating that a figure should be here +TYPE= END_ENV +NAME= figure + PC_AT_START= RESET + START_TAG= + SWITCH_TO_FILE: figs.tmp + STRING: "\end{figure}?n?n" + SWITCH_BACK: + CODE: + println; + println('PLACE FOR FIGURE ', fignum); + println; + END_CODE +END_TYPE +\end{verbatim} +\end{code} + +\section{The LTX2X program} \label{sec:program} + + \lx\ is written using flex and bison. The resulting C code should +compile on any system. More details are given later, but for the end-user +the next section describes how to run the program, assuming that is available +on your system. + +\subsection{Running LTX2X} + + The syntax for running the compiled version of \lx\ is: +\begin{verbatim} +ltx2x [-c] [-f table-file] [-p number] [-w] [-D dir_cat_char] + [-P path_seperators] [-S] + [-i number] [-l number] [-t] [-y number] [-C] [-E] + input-file output-file +\end{verbatim} +where elements in square brackets are options. The options fall into +two groups, one for the casual user and the other for those who may be +interested in the internals of \lx. The first group of options includes: +\begin{description} +\item[{\tt -c}] By default, \lx\ ignores all \LaTeX\ comments in the input + file. This option causes \lx\ to write the comments to the output file. + +\item[{\tt -f}] By default, \lx\ reads the \ctab\ from a file called + \verb|ltx2x.ct|. If the required \ctab\ is in a file with another name this + option is used to change from the default file. For example, +\begin{verbatim} +> ltx2x in.tex out.l2x +\end{verbatim} +reads a \ctab\ from \verb|ltx2x.ct|, while +\begin{verbatim} +> ltx2x -f detex.ct in.tex out.l2x +\end{verbatim} +reads a \ctab\ from file \verb|detex.ct|. + +\item[{\tt -p}] This option causes \lx\ to `pretty print' the output file + (as far as it is able to). The \verb|number| is required and it indicates + the desired maximum number + of characters per output line. If this is considered to be too small, + then \lx\ chooses a value. Note that pretty printing is only applied + to the source file --- not to any replacement tags. That is, it + only tries to format the running text from the source file. + +\item[{\tt -w}] By default, \lx\ outputs source white space just at it reads it. + This option causes \lx\ to collapse any amount of contiguous white space + to a single space. The \verb|-p| option includes the \verb|-w| option. + +\item[{\tt -D}] The value of this option is the character that the operating system + uses to catenate directory names to form a path (see~\ref{sec:search}). + The default value is a + slash (i.e. \verb|/|). The default could be changed to a backslash, for example, + by \verb|-D \|. + +\item[{\tt -P}] The environment variable (see~\ref{sec:search}) + contains a list of directories (also known + as path names). In the operating system that I use, these are separated by + the colon (\verb|:|) character which, together with the semi-colon + and space characters, form + the \lx\ default separators. The path separator characters can be changed + with this option. + For example, \verb|-P :| will make the separators be a colon + or a space (space is automatically included in the separator list). + +\item[{\tt -S}] This option enables the source level debugger + (see~\ref{sec:sld}) for any embedded \ExpressA{} code. +\end{description} + +The second group of options are principally for those who might be +extending the \lx{} system. + +\begin{description} +\item[{\tt -i}] This produces information that may be useful for debugging + the \ExpressA{} interpreter. \verb|number| is an integer + between 1 and 9 inclusive. + The greater the number, the more diagnostics are generated. + +\item[{\tt -l}] This produces information that may be useful for debugging + the \lx{} program. \verb|number| is an integer between 1 and 9 inclusive. + The greater the number, the more diagnostics are generated. + +\item[{\tt -t}] This generates diagnostics related to the processing of + the \ctab\ file. + +\item[{\tt -y}] Like the \verb|l| option, but produces diagnostic information + from the parser (this is actually a null option, but may be useful + in the future). + +\item[{\tt -C}] Disable any interpreter debugging information during + the code generation pass. This is not necessary unless the {\tt -i} + option is used. + +\item[{\tt -E}] Disable any interpreter debugging information during + the code execution processing.This is not necessary unless the {\tt -i} + option is used. + +\end{description} + + + + + \lx\ first reads the specified \ctab\ file, together with any included files, +looking first in the current directory, then in the directories specified by +the environment variable (if it exists). + It then reads the \verb|input-file| from the current directory, +performs the actions specified in the \ctab\ and outputs the results to +the \verb|output-file|. + + Three other files are also generated. +\begin{itemize} +\item \verb|ltx2xct.lis| --- This contains a human-readable form of the internal + representation of the \ctab. It may be useful if there are any errors + in the original \ctab. +\item \verb|ltx2x.err| --- This contains any error or warning messages generated + by \lx. It also contains any diagnostic information that may have been + requested via a command line option. +\item \verb|interp.csg| --- This contains a human readable listing of the + internal byte code generated by the \ExpressA{} interpreter. +\end{itemize} + + When \lx\ is running normally it prints out a counter to the terminal +indicating how many hundreds of input source file lines it has processed. +Lack of such output is an indication that the program may be in a loop and +chewing up CPU cycles to no avail. In this case, stop the program and examine +the output for indications of where the trouble is occurring. + + A limited number of errors are allowed when processing the \ctab\ +and the input \LaTeX\ file before \lx\ gives up and quits. In +particular, if it is reading a \ctab\ file that includes another file, say one +called \file{zilch}, +that it cannot read, it prints the following message to the user's terminal. +\begin{verbatim} +Can't open file zilch +Enter new file name, or I to ignore, or Q to quit +: +\end{verbatim} +A {\tt Q} (or {\tt q}) response stops \lx\ from any further processing. An +{\tt I} (or {\tt i}) response causes \lx\ to stop looking for the included file +and continue processing the current file. Any other response is taken to be +the name of an included file, which \lx\ then tries to read. If it fails, then +the above message is repeated. The user is given a limited number of opportunities +to identify a readable file before \lx\ quits altogether with this message: +\begin{verbatim} +Last attempt. Can't open file zilch. I'm giving up. +\end{verbatim} + + + Regarding performance, the time taken by \lx\ to process a document does +not appear to be significantly different from the time to \LaTeX\ the +same document. + +\subsubsection{Directory searching} \label{sec:search} + + The program employs a search algorithm to find files that are not +in the current directory. It first looks in the current directory and +if a file of the given name is found, then that is used. If the file +is not found, then it searches for it among directories that are +specified in a system environment variable. This variable specifies +a list of pathnames, where the directories forming the path are +combined using a catenation character. For example, \verb|dir1/dir2/dir3| +could be a pathname, where the slash (\verb|/|) is the catenation character. +If it is looking for file \verb|afile.txt| it will catenate the file name +to the path name (e.g. \verb|dir1/dir2/dir3/afile.txt|) and look for +that. The pathnames in the list are separated by another character +(in fact it can be one from a list of characters). For example here +is a list of two pathnames; \verb|dir1/dir2;dir1/dir4|, where the semi-colon +(\verb|;|) is the pathname separator. + + By default, the program uses a slash (\verb|/|) as the directory +catenation character and the pathname separators can be a space, or +a colon or a semi-colon (i.e., any of \verb*| :;|). All these characters +can be altered via the program command line options, and should be set to +match the conventions of your operating system. + + The environment variable used by the program is LTX2XTABLES. +On the operating system that I use, I set this in my login file like: +\begin{verbatim} +setenv LTX2XTABLES .:/dir1/dir2:/dir3/dir4 +\end{verbatim} +Your system may have different conventions. Note that if the environment +variable is not set, only files in the current directory are considered. + + +\subsection{System components} + + The system consists of five main components --- a lexer, a parser, a +library of support functions and \ctab\ parsing code, a +user-defined library of functions, and an interpreter for the \ExpressA{} +language. + +\subsubsection{The lexer} + + The lexer is generated by flex~\cite{LEVINE92} +(a more functional version of lex~\cite{LESK75}). +The source for the lexer is in file \file{l2x.l}. +Its principal function is to read a \LaTeX\ +source file and recognize \LaTeX\ commands. In general, it passes off the +relevant command tokens to the parser for performing appropriate actions. + + However, the lexer does do some processing of the source itself. +\begin{itemize} +\item It recognizes \LaTeX\ comments (i.e. any text starting with a percent + sign and ending with a newline). It silently ignores these comments, unless + run with the \verb|-c| option. +\item It recognizes the `standard' \LaTeX\ verbatims. It will write out the + appropriate tags at the start and end of the verbatim text, while writing + the verbatim text directly to the output file, bypassing the parser. + It does not distinguish between the unstarred and starred + versions of the verbatims. +\item Newlines and whitespace are directly written to the output file, again + bypassing the parser. The \verb|-p| and \verb|-w| options control the + final appearance of whitespace, newlines and paragraphing. +\item It recognizes the command \verb*|\ | i.e. a backslash followed by a + space, and writes the tags defined in the \verb|SLASH_SPACE| specification + directly to the output file. +\end{itemize} + + The lexer is designed to recognize four kinds of \LaTeX\ commands. +\begin{itemize} +\item Commands of the form \verb|\begin{environment}| +\item Commands of the form \verb|\end{environment}| +\item Any other command of the form \verb|\command| +\item As special cases, commands that are 'verbatim-like' or `verb-like'. +\end{itemize} +When it finds a command, it looks up the command or environment name in the +\ctab\ and sends the appropriate token and its \ctab\ location to the +parser. As a special case the contents of verbatim-like environments and +the argument of verb-like coommands are processesd within +the lexer and not sent to the parser. + + +\subsubsection{The parser} + + The parser is generated by bison~\cite{LEVINE92} +(a more powerful version of YACC~\cite{JOHNSON75}). +The source for the parser is in file \file{l2x.y}. +Essentially it defines a very simple +grammar for a \LaTeX\ document. That is, the grammar is limited to +generic kinds of commands and command arguments. It does not understand +the `meaning' of any of the commands or arguments. + + When the parser receives a token from the lexer it tries to match it with +one of the grammar rules, performing the actions specified by the \ctab. +Here is an extract from the parser grammar file, \file{l2x.y}, +for a \LaTeX\ command that has +two required arguments followed by an optional argument. + +\begin{code} +\begin{verbatim} +l2xComm2Opt: COMMAND_2_OPT + { + start_with_req($1); + } + ReqParam + { + action_p_p1($1,1); + } + ReqParam + { + action_p_opt($1,2); + } + OptParam + { + action_last_opt($1); + } + ; +\end{verbatim} +\end{code} + + The actions are enclosed in braces, and are interspersed with the elements +of the grammar. + + The token \verb|COMMAND_2_OPT| indicates that the lexer has found a command +that takes two required arguments followed by an optional argument. +The parser then performs some +actions. The \verb|start_with_req| function is the standard \lx\ function +for the first action in a command production where the final argument +is optional. The \verb|$1| refers to the +location of the particular command in the \ctab, and its value is passed to the +parser by the lexer. + + The parser then expects a required argument (i.e. \verb|{|, token \verb|LBRACE|) +as the start of the required argument, followed by the text of the argument and +finished off by a right brace (i.e. \verb|}|, token \verb|RBRACE|); the grammar +for all of this is specified in the production called \verb|ReqParam|). If it +finds these it performs some further actions, otherwise it reports an +error. +In this case the action is defined by the function \verb|action_p_p1|, +which is the standard action performed between two required arguments +(the second argument in the function call specifies the Pth argument that +has been recognized). Another required argument is then expected. +In this case the action is defined by the function \verb|action_p_opt|, +which is the standard action performed between the end of the Pth required argument +and the start of an optional argument. It then looks for an optional +argument, the grammar for which is specified in the production called +\verb|OptParam|. The final action is specified by the standard function +\verb|action_last_opt| for finishing off a command that ends with an +optional argument. + + The grammar for a command that that has two required arguments, +and possibly an +initial optional argument is similar: + +\begin{code} +\begin{verbatim} +l2xComm2: COMMAND_2 + { + start_with_opt($1); + } + OptParam + { + action_opt_first($1); + } + ReqParam + { + action_p_p1($1,1); + } + ReqParam + { + action_last_p($1,2); + } + ; +\end{verbatim} +\end{code} + +\subsubsection{The support libraries} + + Source code for the C main program and support functions is in file +\file{l2xlib.c}. + The main program is responsible for reading in the \ctab\ and calling the +lexer and parser to do the appropriate processing. + The file also contains a variety of support functions that are, or could +be, used in the lexer, parser, action library, or user-defined library. + + The standard actions for the grammar are contained in file \file{l2xacts.c}. + +\subsubsection{The user-defined library} + + The intent of this library is that masochistic users can define their +own functions for use within \lx\ when processing their \verb|SPECIAL_| +commands, without having to modify the \lx\ support or action libraries. + + Source code for the user-defined library should be maintained in a file +called \file{l2xusrlb.c} and a corresponding header file called \file{l2xusrlb.h}. + +\subsubsection{The \ExpressA{} interpreter} + + The \ExpressA{} interpreter is based on algorithms originally developed +by Ronald Mak~\cite{MAKR91} for interpreting Pascal. His original +algorithms have been modified and extended to cater for \ExpressA. +The interpreter module has a minimal interface with the rest of the +\lx{} system, and could easily be modified to be a stand-alone program +(in fact it started that way in the first place). The interface +between \lx{} and the interpreter is confined to the small +\file{l2xistup.c} file. + + +\section{The \ExpressA{} programming language} \label{sec:expressa} + + \Express{} is a language for information modeling and includes both +declarative and procedural aspects~\cite{EBOOK}. There are also two other +companion languages called respectively \ExpressG{} and \ExpressI. The former +of these is a graphical form of the declaritive aspects of \Express, and the +later is an instiation and test case specification language. These languages +are either ISO international standards~\cite{EXPRESSIS} or on the way +to becoming so~\cite{EXPRESSITR}. + + Certain of the procedural aspects of \Express{} and \ExpressI{} are relevent +to the \lx{} concepts and so, together with some other reasons, +it seemed appropriate to provide an interpreter for a similar language for +use within \lx. \ExpressA{} provides a major subset of the \Express{} procedural +language, together with some Pascal-like additions for input and output. +Of particular note, strings are a built-in type in \ExpressA. The language +also supports three-valued logic and the concept of an `indeterminate' +value of any type. + + Earlier I gave an example \ctab{} to replace the text of a +\LaTeX{} document with the words `Goodbye document'. Here is +an \ExpressA{} program that outputs `Goodbye document'. +\begin{code} +\begin{verbatim} +println('Goodbye document'); +END_CODE +\end{verbatim} +\end{code} + + The following gives a brief overview of \ExpressA. For more details +consult Schenck \& Wilson~\cite{EBOOK}. + +\subsection{Basic elements} + + \ExpressA{} is a case-insensitive language and uses the ASCII character +set. Two kinds of comments are supported --- an end of line comment, +which starts with a \verb|--| pair and continues until the end of the current +line --- and an extended comment. An extended comment starts with a +\verb|(*| pair and is ended by a matching \verb|*)| pair; extended comments +may be nested. + + The language contains many reserved words, some of which are only +applicable to the \Express{} and \ExpressI{} languages. + + Identifiers are composed of an initial letter, possibly followed by +any number of letters, digits, and the underscore character. + + Literals are self defining constant values. An integer literal consists +of one or more digits, the first of which shall not be zero. Real numbers +start with one or more digits, followed by a decimal point. Further +digits may occur after the point, and finaly there may be an exponent +in the `e' notation format (e.g., \verb|123.456e-78|). + + A string literal is any sequence of characters enclosed by single +quote marks. If a single quote mark is meant to form part of the string, +two quote marks must be used at that point. + + Logical literals consists of one of these keywords: \keyword{FALSE}, +\keyword{UNKNOWN} or \keyword{TRUE}. + + \ExpressA{} also includes some other constants. \keyword{PI} stands +for the value of the mathematical constant $\pi$ (3.1415\ldots), +and \keyword{CONST\_E} +stands for the value of the mathematical constant $e$ (2.7182\ldots), +the base of natural logarithms. The special token \verb|?| stands for +an indeterminate value of any type. The three constants +\keyword{THE\_DAY}, \keyword{THE\_MONTH} and \keyword{THE\_YEAR} are integer +values for the current date holding the day of the month (1--31), the +month of the year (1--12) and the year (four digits), respectively. + + +\subsection{Data types} + + \ExpressA{} is a typed language. The simple data types are: \keyword{INTEGER}, +\keyword{REAL}, \keyword{STRING} and \keyword{LOGICAL}. + + The aggregation data types are \keyword{ARRAY}, \keyword{BAG}, \keyword{LIST}, +and \keyword{SET}. The array data type is of a fixed size and must have +declared lower and upper bounds (index range), such as \verb|ARRAY [-7:10] OF|. +The other aggregate data types are dynamic in size, but may have lower and +upper bounds specified for the number of elements, such as \verb|SET [2:5] OF|, +meaning a set that should have between two and five members. For the +dynamic aggregates the upper bound may be given as \verb|?|, which means +an unlimited upper bound, such as \verb|LIST [2:?] OF|. If a bound +specification is absent, then the dynamic aggregate can hold from zero +to any number of elements.\footnote{The dynamic aggregates may not +be fully implemented due to lack of time.} + + Aggregates are one dimensional, but can be chained together for +multi-dimensional aggregates, like +\begin{code} +\begin{verbatim} +ARRAY [1:4] OF LIST OF INTEGER; +\end{verbatim} +\end{code} + + The enumeration data type is a parenthesised comma seperated list of +identifiers. These identifiers represent the values of the enumerated type; +for instance +\begin{code} +\begin{verbatim} +ENUMERATION OF (red, green, blue) +\end{verbatim} +\end{code} + + A defined data type is one declared and named by the user using the +\keyword{TYPE} and \keyword{END\_TYPE} construct. For example +\begin{code} +\begin{verbatim} +TYPE length = REAL; END_TYPE; +TYPE crowd_size = INTEGER; END_TYPE; +TYPE signal_colour = ENUMERATION OF (red, amber, green); END_TYPE; +\end{verbatim} +\end{code} + + An entity data type consists of a list of attributes and their types, enclosed +in a \keyword{ENTITY} and \keyword{END\_ENTITY} pair. An entity type +is named. +\begin{code} +\begin{verbatim} +ENTITY an_ent; + auditorium_width : length; + audience : crowd_size; + title : STRING; + profit : REAL; +END_ENTITY; +\end{verbatim} +\end{code} + + \ExpressA{} provides for algorithms in the form of functions and procedures. + +A \keyword{FUNCTION} is an algorithm that operates on parameters and returns +a single resultant value of a specified data type. An invocation of a function +in an expression evaluates to the resultant value at the point of invocation. +For example: +\begin{code} +\begin{verbatim} +FUNCTION func (par1 : INTEGER; par2 : STRING) : STRING; + LOCAL + str : STRING; + -- other variable declarations + END_LOCAL; + -- the algorithm statements are here + RETURN(str); +END_FUNCTION; +\end{verbatim} +\end{code} +Note that the parameters are typed. + + A \keyword{PROCEDURE} is an algorithm that receives parameters from the +point of invocation and operates on them in some manner. Changes to the parameters +within the procedure are only reflected to the point of invocation +when the formal parameter is preceded by the keyword \keyword{VAR}. +For example: +\begin{code} +\begin{verbatim} +PROCEDURE proc (par1 : INTEGER; VAR par2 : STRING); + -- local declarations and the algorithm statements +END_PROCEDURE; +\end{verbatim} +\end{code} +Note that the parameters are typed. In this case the value of \keytext{par2} +may be changed. + + Variables are declared in a local block, enclosed by the keywords +\keyword{LOCAL} and \keyword{END\_LOCAL}. A variable declaration consists +of an identifer and its type, such as: +\begin{code} +\begin{verbatim} +LOCAL + str : STRING; + e1, e2 : an_ent; -- e1 and e2 are both of type an_ent + e3 : an_ent; -- so is e3 + num : INTEGER; + col : signal_colour; + matrix : ARRAY [1:15] OF ARRAY [1:15] OF REAL; +END_LOCAL; +\end{verbatim} +\end{code} + + The above declarations must be in the following order: +\begin{enumerate} +\item \keyword{ENTITY} and/or \keyword{TYPE} declarations +\item \keyword{FUNCTION} and/or \keyword{PROCEDURE} declarations +\item a \keyword{LOCAL} declaration block +\end{enumerate} + + After the above can come any number of statements. + +\subsection{Statements} + + \ExpressA{} supports the following statements: +\begin{itemize} +\item Null statement +\item Assignment statement +\item Call statement +\item \keyword{BEGIN} \ldots \keyword{END} compound statement +\item \keyword{CASE} \ldots \keyword{END\_CASE} statement +\item \keyword{IF} \ldots \keyword{THEN} \ldots \keyword{ELSE} + \ldots \keyword{END\_IF} statement +\item \keyword{REPEAT} \ldots \keyword{WHILE} \ldots \keyword{UNTIL} \ldots + \keyword{END\_REPEAT} statement. This also includes the + \keyword{ESCAPE} and \keyword{SKIP} statements +\item \keyword{RETURN} statement +\end{itemize} + + All the above statements are completed by a \keytext{;} (semicolon). +The \emph{null} statement just consists of a semicolon. + + The \emph{assignment} statement is used to assign an instance to a local +variable or parameter. The data types must be compatible. +\begin{code} +\begin{verbatim} +LOCAL + a, b, c : REAL; +END_LOCAL; +... + a := 2.3E-6; + b := a; + a := -27.0; + c := 33.3*b; +\end{verbatim} +\end{code} + + The \emph{call} statement invokes a procedure or a function. The actual +parameters provided with the call must agree in number, order and type +with the formal parameters specified in the procedure or function +declaration. The supplied parameter values must be assignment compatible +with the formal parameters. This is an example of calling the \ExpressA{} +defined \keyword{INSERT} procedure which takes three parameters: +\begin{code} +\begin{verbatim} +INSERT(my_list, list_element, 0); +\end{verbatim} +\end{code} + + The \emph{compound} statement consists of one or more statements enclosed +between a \keyword{BEGIN} and \keyword{END} pair. The enclosed statements +are treated as a single statement. +\begin{code} +\begin{verbatim} +... + BEGIN + a := 2.3e-7; + b := a; + c := b*33.3; + END; +\end{verbatim} +\end{code} + + The \emph{case} statement is a means of selectively executing statements +based on the value of an expresion. +\begin{code} +\begin{verbatim} +LOCAL + a : INTEGER; + x, y : REAL; +END_LOCAL; +... + a := 2; + x := 21.9; + CASE 2*a OF + 1 : x := SIN{x}; + 2 : x := SQRT(x); + 3 : x := LOG(x); + 4 : x := COS(x); -- this is executed + 5, 6 : y := y**x; + OTHERWISE : x := 0.0; + END_CASE; +\end{verbatim} +\end{code} +The integer expression following the \keyword{CASE} keyword is evaluated. +The result is compared to the values of the case labels and the +statement following the first matching label is executed. Execution then +continues at the statement following the \keytext{END\_CASE;}. If no +label matches, then no statements within the case block are executed, +except if an \keyword{OTHERWISE} label is included, which will match +anything. All other labels are examined before looking for the +\keyword{OTHERWISE}. + + The \emph{if \ldots then \ldots else} statement allows the conditional +execution of statements depending on the value of a \keyword{LOGICAL} +expression. When the expression evaluates to \keyword{TRUE} the statement(s) +following the \keyword{THEN} are executed, after which control passes +to the statement following the closing \keyword{END\_IF}. When the logical +expression evaluates to \keyword{FALSE} or \keyword{UNKNOWN} the \keyword{THEN} +statements are jumped over and execution starts at the statement(s) following +the \keyword{ELSE} keyword if present, or at the statement following +the \keyword{END\_IF} keyword. +\begin{code} +\begin{verbatim} +IF a > 20 THEN + b := a + 2; + c := c - 1; +ELSE + IF a > 10 THEN + b := a + 1; + ELSE + c := c + 1; + END_IF; +END_IF; +\end{verbatim} +\end{code} + + The \emph{repeat} statement is used to control the conditional repetition +of a series of statements. The control conditions are: +\begin{itemize} +\item finite iteration until an integer expression reaches a specified + value; +\item \keyword{WHILE} a logical condition is \keyword{TRUE}; +\item \keyword{UNTIL} a logical condition is \keyword{TRUE}. +\end{itemize} +\begin{code} +\begin{verbatim} +REPEAT i := 100 TO 0 BY -7 WHILE r >= 0.0 UNTIL err < 1.0e-8; + ... + r := ...; + err := ...; +END_REPEAT; +\end{verbatim} +\end{code} +At entry to the \keyword{REPEAT} statement the iteration variable is +initialized to the first bound. If the variable less than or equal to the +\keyword{TO} bound and the increment is positive, or the variable is less +than the \keyword{TO} bound and the increment is negative, processing +jumps to after the \keyword{END\_REPEAT}, otherwise processing continues. +The \keyword{WHILE} condition is checked and if +\keyword{TRUE} then the statements in the body are executed. After +these have been executed the \keyword{UNTIL} condition is checked. If this +is not \keyword{TRUE} then processing continues by incrementing the iteration +variable by either unity or by the \keyword{BY} value if present. The whole +process then starts again with the checking of the iteration variable +against the \keyword{TO} bound. + + All three types of controls are optional. If none are given then the +\keyword{REPEAT} statement will loop for ever. The \emph{escape} statement +causes an immediate transfer out of the \keyword{REPEAT} statement +in which it occurs. The \emph{skip} statement causes a jump to the +end of the \keyword{REPEAT} statement in which it occurs (i.e., to the point +where the \keyword{UNTIL} expression is tested). +\begin{code} +\begin{verbatim} +REPEAT UNTIL (a = 1); + ... + IF a = 0 THEN + ESCAPE; + END_IF; + ... + IF a > 10 THEN + SKIP; + END_IF; + ... + ... +-- SKIP transfers control to here +END_REPEAT; + -- ESCAPE transfers control to here +\end{verbatim} +\end{code} + + The \emph{return} statement terminates the execution of a \keyword{FUNCTION} +or \keyword{PROCEDURE}. The \keyword{RETURN} statement within a function +must specify an expression, the value of which is the value returned +by the function. A \keyword{RETURN} in a procedure must not specify an +expression. +\begin{code} +\begin{verbatim} +RETURN(a <> b); -- example for within a function +RETURN; -- example for within a procedure +\end{verbatim} +\end{code} + +\subsection{Expressions} + + Expressions are combinations of operators, operands and function calls +which are evaluated to produce a value. The simplest expression is +either a literal value or the name of a variable. + +\subsubsection{Arithmetic operators} + + The arithmetic operators act on number values and produce a number +result. If any operand +is indeterminate (i.e., \verb|?|) then the result is also +indeterminate. The operators are: +\begin{description} +\item[Unary] The operators \verb|+| and \verb|-|, the latter of which +negates its following operand. +\item[Binary] Addition (\verb|+|), + subtraction (\verb|-|), + multiplication (\verb|*|), + real division (\verb|/|), + exponentiation (\verb|**|), + integer division (\keyword{DIV}), + and modulo (\keyword{MOD}). +\end{description} + +\subsubsection{Relational operators} + + The result of a relational expression is a \keyword{LOGICAL} value. +If either operand is indeterminate, the expression evaluates to +\keyword{UNKNOWN}. + +\begin{description} +\item[Value comparison] Equal (\verb|=|), + not equal (\verb|<>|), + greater than (\verb|>|), + less than (\verb|<|), + greater than or equal (\verb|>=|), and + less than or equal (\verb|<=|). + +\item[Membership] The \keyword{IN} operator tests an item for membership +in a dynamic aggregate (e.g., \keytext{IF fred IN mylist THEN ...}). + +\item[Matching] The \keyword{LIKE} operator compares a string against a pattern, +evaluating to \keyword{TRUE} if they match. The pattern characters are: + \begin{itemize} + \item \verb|@| Matches any letter. + \item \verb|^| Matches any upper-case letter. + \item \verb|?| Matches any character. + \item \verb|&| Matches remainder of string. + \item \verb|#| Matches any digit. + \item \verb|$| Matches a substring terminated by a space character + or end-of-string. + \item \verb|*| Matches any number of characters. + \item \verb|\| Begins a pattern escape sequence. + \item \verb|!| Negation character (used with the other characters). + \item Any other character matches itself. + \end{itemize} + + Some examples: + \begin{itemize} + \item \verb|'The quick red fox' LIKE '$$$$'| is \keyword{TRUE}. + \item \verb|'Page 231' LIKE '$ ###'| is \keyword{TRUE}. + \item \verb|'Page 27' LIKE 'Page ###'| is \keyword{FALSE}. + \item \verb|'\aaaa' LIKE '\\aaaa'| is \keyword{TRUE}. + \item \verb|'\aaaa' LIKE '\aaaa'| is \keyword{FALSE}. + \item \verb|'aaaa' LIKE 'a@@a'| is \keyword{TRUE}. + \end{itemize} + +\end{description} + +\subsubsection{Logical operators} + + The logical operators produce a logical result. Except for the +\keyword{NOT} operator which takes one logical operand (e.g., \keytext{NOT op}), +they take two logical operands (e.g., \keytext{op1 XOR op2}). + + The evaluation of the \keyword{NOT} operator is given in table~\ref{tab:not}. + +\begin{table} +\centering +\caption{The NOT logical operator} \label{tab:not} +\begin{tabular}{|c|c|} \hline +Operand value & Result value \\ \hline +\keyword{TRUE} & \keyword{FALSE} \\ +\keyword{UNKNOWN} & \keyword{UNKNOWN} \\ +\keyword{FALSE} & \keyword{TRUE} \\ \hline +\end{tabular} +\end{table} + + The evaluation of the \keyword{AND}, \keyword{OR} and \keyword{XOR} operators +is given in table~\ref{tab:andorxor}. + +\begin{table} +\centering +\caption{The AND, OR and XOR logical operators} +\label{tab:andorxor} +\begin{tabular}{|c|c||c|c|c|} \hline +Op1 & Op2 & Op1 \keyword{AND} Op2 & Op1 \keyword{OR} Op2 & Op1 \keyword{XOR} Op2 \\ \hline +\keyword{TRUE} & \keyword{TRUE} & \keyword{TRUE} & \keyword{TRUE} & \keyword{FALSE} \\ +\keyword{TRUE} & \keyword{UNKNOWN} & \keyword{UNKNOWN} & \keyword{TRUE} & \keyword{UNKNOWN} \\ +\keyword{TRUE} & \keyword{FALSE} & \keyword{FALSE} & \keyword{TRUE} & \keyword{TRUE} \\ +\keyword{UNKNOWN} & \keyword{TRUE} & \keyword{UNKNOWN} & \keyword{TRUE} & \keyword{UNKNOWN} \\ +\keyword{UNKNOWN} & \keyword{UNKNOWN} & \keyword{UNKNOWN} & \keyword{UNKNOWN} & \keyword{UNKNOWN} \\ +\keyword{UNKNOWN} & \keyword{FALSE} & \keyword{FALSE} & \keyword{UNKNOWN} & \keyword{UNKNOWN} \\ +\keyword{FALSE} & \keyword{TRUE} & \keyword{FALSE} & \keyword{TRUE} & \keyword{TRUE} \\ +\keyword{FALSE} & \keyword{UNKNOWN} & \keyword{FALSE} & \keyword{UNKNOWN} & \keyword{UNKNOWN} \\ +\keyword{FALSE} & \keyword{FALSE} & \keyword{FALSE} & \keyword{FALSE} & \keyword{FALSE} \\ \hline +\end{tabular} +\end{table} + +\subsubsection{Miscellaneous} + +\begin{description} + +\item[Function call] A function may be called without the result necessarily +being assigned to a variable. If \keytext{fun} is a function with two +arguments (for simplicitly integer arguments) and returning a logical +value, then +\begin{code} +\begin{verbatim} +log := fun(i1, i2); +fun(i3, 24*i4); +\end{verbatim} +\end{code} +are both legitimate calls. + + +\item[Dot operator] The dot operator is used to access an attribute from an +entity. If \keytext{ent} is an \keyword{ENTITY} type with an attribute +\keytext{att}, then \keytext{ent.attr} evaluates to the value of the +\keytext{attr} attribute within the \keytext{ent}. + +\item[String operators] \mbox{} \\ + The \verb|+| operator takes two strings as +its operands and evaluates to the string that is the concatenation of its +operands. For example: +\begin{code} +\begin{verbatim} +str1 := 'string1'; +str2 := 'string2'; +str1 := str1 + str2; +-- str1 = 'string1string2' is TRUE +\end{verbatim} +\end{code} + + The substring operator \verb|[i1:i2]| is a postfix operator that when +applied to a string, evalutes to the string whose characters are composed +of the \verb|i1|'th through the \verb|i2|'th characters, inclusively, +of its operand. Note that \verb|i2| must be greater than or equal to +\verb|i1|, and both must be within the limits of the number of characters +in the string. For example: +\begin{code} +\begin{verbatim} +str1 := 'string'; +str2 := str1[2:4]; +str1 := str1 + str2; +-- str1 = 'tristring' is TRUE +\end{verbatim} +\end{code} + +\item[Aggregate operators] \mbox{} \\ + The index operator \verb|[i]| is a postfix operator that can be applied +to an aggregate operand; the expression evaluates to the value of the +aggregate at the index position. For example, if \keytext{lagg} is a +list of integers: +\begin{code} +\begin{verbatim} +insert(lagg, 20, 0); +insert(lagg, 40, 0); +insert(lagg, 60, 0); +insert(lagg, 80, 0); +-- lagg[2] = 60 is TRUE +\end{verbatim} +\end{code} + +\item[Interval expression] \mbox{} \\ + An \emph{interval expression} is a \keyword{LOGICAL} expression +consisting of three operands and two operators. It has the form: +\begin{code} +\begin{verbatim} +{ low op1 test op2 high } +\end{verbatim} +\end{code} +where \keytext{op1} and \keytext{op2} are either of the two relational +operators \verb|<| or \verb|<=|, and \keytext{low}, \keytext{test} and +\keytext{high} are expressions of the same type. The interval expression +is equivalent to: +\begin{code} +\begin{verbatim} +((low op1 test) AND (test op2 high)) +\end{verbatim} +\end{code} +The value of the interval expression is given by +\begin{enumerate} +\item If any operand is indeterminate, then it evauates to \keyword{UNKNOWN}. +\item If either of the logical relationships evaluates to \keyword{FALSE}, + then it evauates to \keyword{FALSE}. +\item If both logical relationships evalute to \keyword{TRUE}, + then it evauates to \keyword{TRUE}. +\item Otherwise it evaluates to \keyword{UNKNOWN}. +\end{enumerate} +For example: +\begin{code} +\begin{verbatim} +i := 10; +{1 <= i < 20} -- is TRUE +{1 <= i < 10} -- is FALSE +i := ?; +{1 <= i < 10} -- is UNKNOWN +\end{verbatim} +\end{code} + + +\end{description} + + +\subsection{Built in procedures and functions} + +\subsubsection{Procedures} + + The following procedures are an integral part of \ExpressA. They are +shown as signatures to inidicate the data types of the formal parameters. +For convenience, \keytext{GENERIC} is used to indicate any type. + +\begin{itemize} +\item \keytext{INSERT (VAR L:LIST OF GENERIC; E:GENERIC; P:INTEGER)} \\ + \keyword{INSERT} inserts the element \keytext{E} into a list +\keytext{L} at position \keytext{P}. The insertion follows the existing +element at \keytext{P}, so that if \keytext{P=0}, \keytext{E} will +become the first element. + +\item \keytext{REMOVE (VAR L:LIST OF GENERIC; P:INTEGER)} \\ + \keyword{REMOVE} modifies the list \keytext{L} by deleting the +element at position \keytext{P}. + +\item \keytext{SYSTEM (V:STRING)} \\ + \keyword{SYSTEM} passes the string \keytext{V} to the operating system. +This is typically used to get the operating system to perform some action. + +\item \keytext{ READ(VAR V1, V2,...:GENERIC)}, \keytext{READLN(VAR V1, V2,...:GENERIC)} \\ + These two procedures are similar to the Pascal procedures of the same + name and put data from standard input into the variable(s) + \keytext{V1}, etc. + + The argument is a comma-seperated list of variables. The variables may be + of different types, but the types are limited to + \keyword{INTEGER}, + \keyword{REAL}, + \keyword{LOGICAL}, and + \keyword{STRING}. + The procedure gets the next value of the variable's type from standard input + and assigns it to the variable. An integer is recognised as a set of digits, + optinally preceeded by a sign. A real is in either decimal or scientific + notation (e.g., \verb|12.34| or \verb|1.234e1|). A logical is \verb|TRUE|, + \verb|FALSE| or \verb|UNKNOWN| (case independent, so \verb|TRUE| could also + be \verb|tRuE|). A string is + any non-empty set of characters ended by white space (e.g., \verb*|string | + is one string but \verb*|ball of str8 string | is four strings). The difference + between \keyword{READ} and \keyword{READLN} is that the former performs the + actions described above, while the latter will discard any remaining characters + in the input line after processing its arguments. + + +\item \keytext{ WRITE(format)}, \keytext{WRITELN(format)} \\ + These two procedures are similar to the Pascal procedures of the same name. + They write data to standard output. + + The \keytext{format} consists of a comma-seperated list of variables with + optional spacing specifications. The variable types may be + \keyword{INTEGER}, + \keyword{REAL}, + \keyword{LOGICAL}, or + \keyword{STRING}. + The \keyword{LOGICAL} and \keyword{STRING} types take no spacing declarations. + An \keyword{INTEGER} variable can take one optional space specification which + is an integer number specifying the minimum field width for printing the value + (e.g., \keytext{int:6} to specify a minimum field width of 6 characters). + A \keyword{REAL} variable can take two optional space specifications. The + first is the field width and the second is the number of digits to be printed + (e.g., \keytext{r:10:5} for printing with a field width of 10 characters + and to a pecision of 5 digits). For example: +\begin{code} +\begin{verbatim} +BEGIN_LOCAL + int : INTEGER; + r : REAL; + log : LOGICAL; + str : STRING; +END_LOCAL; + int := 23; + r := 23.0; + log := true; + str := 'This is a string.'; +WRITE('Example', int, r:10:5, ' ', log, ' ', str); +\end{verbatim} +\end{code} +will produce: +\begin{code} +\begin{verbatim} +Example 23 23.000 TRUE This is a string. +\end{verbatim} +\end{code} + + The difference between \keyword{WRITE} and \keyword{WRITELN} is that the latter + will end the output line after it has output the values of its arguments. + (\keyword{WRITELN} need take no arguments, in which case it justs ends the current + output line). + +\item \keytext{ PRINT(format)}, \keytext{PRINTLN(format)} \\ + These \keyword{PRINT} procedures are the same as the + \keyword{WRITE} procedures, except that they send the data + to the current \lx{} output destination. + +\end{itemize} + +\subsubsection{Functions} + + The following functions are supplied as part of \ExpressA. They are +exhibited as signatures to show the formal parameters. For convenience, +\keytext{NUMBER} is being used to denote either an \keyword{INTEGER} or a +\keyword{REAL} number. + +\begin{itemize} +\item \keytext{ABS (V:NUMBER) : NUMBER;} \\ + \keyword{ABS} returns the absolute value of its argument. +\item \keytext{COS (V:NUMBER) : REAL;} \\ + Returns the cosine of an an angle specified in radians. +\item \keytext{EOF () : LOGICAL;} \\ + Returns \keyword{TRUE} if the next character from standard input + is `end-of-file', otherwise it returns \keyword{FALSE}. +\item \keytext{EOLN () : LOGICAL;} \\ + Returns \keyword{TRUE} if the next character from standard input + is `end-of-line', otherwise it returns \keyword{FALSE}. +\item \keytext{EXISTS (V:GENERIC) : LOGICAL;} \\ + The function \keyword{EXISTS} returns \keyword{FALSE} if its + argument is indeterminate or does not exist, otherwise it returns + \keyword{TRUE}. +\item \keytext{EXP (V:NUMBER) : REAL;} \\ + Returns $e$ (the base of natural logarithms (\keyword{CONST\_E})) + raised to the power of \keytext{V}. +\item \keytext{HIBOUND (V:AGGREGATE OF GENERIC) : INTEGER;} \\ + \keyword{HIBOUND} returns the declared upper index of an \keyword{ARRAY} + or the declared upper bound of a + \keyword{BAG}, \keyword{LIST} or \keyword{SET}. +\item \keytext{HIINDEX (V:AGGREGATE OF GENERIC) : INTEGER;} \\ + \keyword{HIINDEX} returns the declared upper index of an \keyword{ARRAY} + or the number of elements in a + \keyword{BAG}, \keyword{LIST} or \keyword{SET}. +\item \keytext{LENGTH (V:STRING) : INTEGER;} \\ + Returns the number of characters in its argument. +\item \keytext{LOBOUND (V:AGGREGATE OF GENERIC) : INTEGER;} \\ + \keyword{LOBOUND} returns the declared lower index of an \keyword{ARRAY} + or the declared lower bound of a + \keyword{BAG}, \keyword{LIST} or \keyword{SET}. +\item \keytext{LOG (V:NUMBER) : REAL;} \\ + Returns the natural logarithm of its argument. +\item \keytext{LOG2 (V:NUMBER) : REAL;} \\ + Returns the base 2 logarithm of its argument. +\item \keytext{LOG10 (V:NUMBER) : REAL;} \\ + Returns the base 10 logarithm of its argument. +\item \keytext{LOINDEX (V:AGGREGATE OF GENERIC) : INTEGER;} \\ + \keyword{LOINDEX} returns the declared lower index of an \keyword{ARRAY} + or the value 1 for a + \keyword{BAG}, \keyword{LIST} or \keyword{SET}. + + The \keytext{..INDEX} functions are useful for iterating over + aggregates. For example, if \keytext{lagg} is a list of integer, + then all the elements can be printed out as a comma-seperated + list enclosed in parentheses by: +\begin{code} +\begin{verbatim} +writeln; +write('lagg = ('); +REPEAT i := LOINDEX(lagg) TO HIINDEX(lagg); + IF (i = HIINDEX(lagg)) THEN write(lagg[i]:1); + ELSE write(lagg[i]:1, ', '); + END_IF; +END_REPEAT; +writeln(')'); +\end{verbatim} +\end{code} +\item \keytext{NVL (V:GENERIC; SUBS:GENERIC) : GENERIC;} \\ + If the argument \keytext{V} exists then it is returned, otherwise + the argument \keytext{SUBS} is returned. Both arguments must be + of the same type. +\item \keytext{ODD (V:INTEGER) : LOGICAL;} \\ + Returns \keyword{TRUE} or \keyword{FALSE} depending on whether or not + its argument is odd or even. +\item \keytext{REXPR (V:STRING; E:STRING) : LOGICAL;} \\ + This function tests whether the \keytext{V} string parameter + matches a regular expression \keytext{E}. \keyword{REXPR} + returns \keyword{TRUE} if there is a match, \keyword{FALSE} + if there is not a match, or \keyword{UNKNOWN} if the regular + expression is ill-formed. + + In the regular expression, most characters stand for themselves, + but \verb|\| can be used to escape any of the meta-characters. + \begin{itemize} + \item The meta-characters \keytext{(} and \keytext{)} are used for + grouping sub-expressions. + \item \verb?|? between expressions means one or the other. + \item \keytext{+} following an expression means match one or more times. + \item \keytext{*} following an expression means match zero or more times. + \item \keytext{?} following an expression means match zero or one times. + \item \verb|[...]| is an expression indicating that any of the enclosed + characters are acceptable. + \item \verb|[^...]| is an expression indicating that any characters + except those enclosed are acceptable. + \item Within a bracket expression a range of characters can be + specified by providing the first and last with a seperating hyphen. + For instance, \keytext{[a-zA-Z]} will match any alphabetic character. + \end{itemize} + + Some examples: + \begin{itemize} + \item \verb|[a-zA-Z]+| match one or more letters. + \item \verb|[0-9]+.[0-9]+([eE][\-\+]?[0-9]+)?| match a floating + point number \\ + (e.g., \verb|1.23e-27| or \verb|0.987|) + \item \verb|[a-zA-Z][0-9a-zA-Z_]*| match an \ExpressA{} variable. + \item \verb|[^0-9a-zA-Z]| match anything except letters or digits. + \item \verb?(I|i)(F|f)? case insensitive match for the word \verb|IF|. + \end{itemize} + +\item \keytext{ROUND (V:NUMBER) : INTEGER;} \\ + Returns the nearest integer to its argument value. +\item \keytext{SIN (V:NUMBER) : REAL;} \\ + Returns the sine of an an angle specified in radians. +\item \keytext{SIZEOF (V:AGGREGATE OF GENERIC) : INTEGER;} \\ + \keyword{SIZEOF} returns the number of elements in its argument. + When \keytext{V} is an \keyword{ARRAY} this is the declared number + of elements. When \keytext{V} is a + \keyword{BAG}, \keyword{LIST} or \keyword{SET} this is the actual + number of elements. +\item \keytext{SQRT (V:NUMBER) : REAL;} \\ + Returns the square root of its argument. +\item \keytext{TAN (V:NUMBER) : REAL;} \\ + Returns the tangent of an an angle specified in radians. +\item \keytext{TRUNC (V:NUMBER) : INTEGER;} \\ + Chops off any decimal part of its argument, returning the corresponding + integer value. + +\end{itemize} + + +\subsection{Source level debugger} \label{sec:sld} + + The \ExpressA{} interpreter includes a source level debugger for +use when your code appears to be misbehaving. When in operation the +debugger will prompt for a command to be entered. It understands +the following commands. + +\begin{itemize} +\item \keytext{} Continue processing. +\item \keyword{break} \keytext{} Place a breakpoint at the statement + on line \keytext{}. +\item \keyword{break} Print the line numbers of all the breakpoints. +\item \keyword{unbreak} \keytext{} Remove the breakpoint from line + \keytext{}. +\item \keyword{unbreak} Remove all breakpoints. +\item \keyword{trace} Turn on statement tracing. +\item \keyword{untrace} Turn off statement tracing. +\item \keyword{entry} Turn on tracing of entry to procedures and functions. +\item \keyword{unentry} Turn off entry tracing. +\item \keyword{exit} Turn on tracing of exits from procedures and functions. +\item \keyword{unexit} Turn off exit tracing. +\item \keyword{traceall} Turn on all tracing. +\item \keyword{untraceall} Turn off all tracing. +\item \keyword{stack} Turn on display of the runtime stack accesses. +\item \keyword{unstack} Turn off stack display. +\item \keyword{step} Turn on single-stepping. +\item \keyword{unstep} Turn off single stepping. +\item \keyword{fetch} \keytext{} Print data fetches for + \keytext{}. +\item \keyword{store} \keytext{} Print data stores for + \keytext{}. +\item \keyword{watch} \keytext{} Print both data fetches and + stores for \keytext{}. +\item \keyword{watch} Print the names of all variables being watched. +\item \keyword{unwatch} \keytext{} Remove the watch from + \keytext{}. +\item \keyword{unwatch} Remove all watches. +\item \keyword{show} \keytext{} Print the value of + the \ExpressA{} expresion \keytext{}. The variables + in the expression must have been declared in the \ExpressA{} code. + For example: +\begin{code} +\begin{verbatim} +show (23.0 + LOG(num))/(PI*r**2) +\end{verbatim} +\end{code} +\item \keyword{assign} \keytext{} Assign the value + of \keytext{} to the \ExpressA{} variable \keytext{}. + For example: +\begin{code} +\begin{verbatim} +assign num := SIN(theta/300.0) +\end{verbatim} +\end{code} +\item \keyword{where} Print the current line number and the text of the + next statement to be executed. +\item \keyword{kill} Terminate the execution of the \lx{} program. +\end{itemize} + +\subsection{Example \ExpressA{} code} + + The following demonstrates most of the functionality of \ExpressA. +Most of this is not particularly interesting, except possibly for the +algorithms for calculating the date of Easter and for generating +magic squares. + +\begin{code} +\begin{verbatim} + c= fun.ct Test of CODE ltx2x + +CODE_SETUP= + ENTITY ent; + attr1, attr3 : INTEGER; + attr2 : STRING; + END_ENTITY; + + TYPE joe = INTEGER; + END_TYPE; + + TYPE colour = ENUMERATION OF (red, blue, green); + END_TYPE; + + +PROCEDURE easter; +(* calculates the date of Easter for the present year + The algorithm can be applied to any year between + 1900 and 2099 inclusive, but if so, then the year + should be checked to ensure that it is within this range. *) + LOCAL + n, a, b, m, q, w : INTEGER; + day : INTEGER; + month : STRING; + END_LOCAL; + + n := THE_YEAR - 1900; + a := n MOD 19; + b := (7*a + 1) DIV 19; + m := (11*a + 4 - b) MOD 29; + q := n DIV 4; + w := (n + q + 31 - m) MOD 7; + day := 25 - m - w; + month := 'April'; + IF (day < 1) THEN + month := 'March'; + day := day + 31; + END_IF; + writeln('In ', THE_YEAR:1, ' Easter is on ', month, day:3); +END_PROCEDURE; + + +FUNCTION magic_square(order:INTEGER): LOGICAL; +(* calculates magic squares from order 1 through 15. + The order must be an odd number. *) + LOCAL + row, col, num : INTEGER; + sqr_order : INTEGER; + magic : ARRAY[1:15] OF ARRAY[1:15] OF INTEGER; + END_LOCAL; + + IF (order > 15) THEN -- only squares up to order 15 + RETURN(FALSE); + ELSE + IF (order < 1) THEN -- squares have at least one entry + RETURN(FALSE); + ELSE + IF (NOT ODD(order)) THEN -- squares are odd + RETURN(FALSE); + END_IF; + END_IF; + END_IF; + + sqr_order := order**2; + row := 1; + col := (order + 1) DIV 2; + REPEAT num := 1 TO sqr_order; + magic[row][col] := num; + IF ((num MOD order) <> 0) THEN + IF (row = 1) THEN row := order; ELSE row := row - 1; END_IF; + IF (col = order) THEN col := 1; ELSE col := col + 1; END_IF; + ELSE + IF (num <> sqr_order) THEN row := row + 1; END_IF; + END_IF; + END_REPEAT; + + writeln(Magic square of order ',order:2); + REPEAT row := 1 TO order; + REPEAT col := 1 TO order; + write(magic[row][col]:4); + END_REPEAT; + writeln; + END_REPEAT; + writeln; + + RETURN(TRUE); +END_FUNCTION; + +FUNCTION month(mnum:INTEGER) : STRING; +(* Given an integer representing the month in a year, + returns the name of the month. *) +LOCAL + str : STRING; +END_LOCAL; + + CASE mnum OF + 1 : str := 'January'; + 2 : str := 'February'; + 3 : str := 'March'; + 4 : str := 'April'; + 5 : str := 'May'; + 6 : str := 'June'; + 7 : str := 'July'; + 8 : str := 'August'; + 9 : str := 'September'; + 10 : str := 'October'; + 11 : str := 'November'; + 12 : str := 'December'; + OTHERWISE : str := ''; + END_CASE; +RETURN(str); +END_FUNCTION; + + LOCAL + a : array[1:3] of integer; + lagg : list [0:5] of integer; + a23 : array[1:2] of array[1:3] of integer; + i, n : integer; + s1, s2 : string; + b : logical; + r1, r2 : real; + nega : array[-3:-1] of integer; + posa : array[3:5] of integer; + j : joe; + ex : ent; + END_LOCAL; + + -- start with a massive compound statement + BEGIN + + writeln; + println; + + (* write today's date *) + writeln('Today is ', THE_DAY:1, ' ', month(THE_MONTH), ' ', THE_YEAR:1); + writeln; + + (* The user might be interested in Easter *) + easter; + writeln; + + (* Call some math functions *) + r1 := PI/4; + writeln('r1 = PI/4 (0.78539...)', r1); + writeln('cos(r1) (0.70710...)', cos(r1)); + writeln('sin(r1) (0.70710...)', sin(r1)); + writeln('tan(r1) (1.0)', tan(r1)); + + r1 := CONST_E; + writeln('r1 = CONST_E (2.7182...)', r1); + writeln('log(4.5) (1.50407...)', log(4.5)); + writeln('log2(8) (3.0)', log2(8)); + writeln('log10(10) (1.0)', log10(10)); + + r2 := exp(10); + writeln('exp(10) (2.203...e4)', r2); + + r2 := sqrt(121); + writeln('sqrt(121) (11.0)', r2); + + (* populate and print some arrays *) + writeln; + posa[3] := 10; + posa[4] := 20; + posa[5] := 30; + REPEAT i := LOINDEX(posa) TO HIINDEX(posa); + writeln('posa[', i:1, '] = ', posa[i]); + END_REPEAT; + + writeln; + nega[-3] := 1; + nega[-2] := 2; + nega[-1] := 3; + REPEAT i := LOINDEX(nega) TO HIINDEX(nega); + writeln('nega[', i:1, '] = ', nega[i]); + END_REPEAT; + + (* Do some things with a list *) + + -- check the initial size (should be empty) + i := SIZEOF(lagg); + writeln('no. of els in lagg = ', i); + + -- insert elements at the front + INSERT(lagg, 10, 0); + i := SIZEOF(lagg); + writeln('no. of els in lagg = ', i); + INSERT(lagg, 20, 0); + writeln('no. of els in lagg = ', SIZEOF(lagg)); + + -- print some of the elements + i := lagg[1]; + writeln('first in lagg = ', i); + writeln('lagg[2] = ', lagg[2]); + + -- check if a value in in the list + b := 10 IN lagg; + writeln(b); -- should be TRUE + b := 30 IN lagg; + writeln(b); -- should be FALSE + + -- write all the elements + REPEAT i := LOINDEX(lagg) TO HIINDEX(lagg); + writeln('lagg[', i:1, '] = ', lagg[i]); + println('lagg[', i:1, '] = ', lagg[i]); + END_REPEAT; + + (* see what happens with an indeterminate value *) + b := FALSE; + b := ?; + writeln(b); + println(b); + (* Some more attempts with indeterminate *) + i := 2; + n := 3*i; + writeln(i, n); -- should be 2 6 + n := 3*?; + writeln(i, n); -- should be 2 ? + i := ?; + n := 3*i; + writeln(i, n); -- should be ? ? + +END; -- end of compound statement + -- but we can have individual statements + + + (* Try to provide some excitement by making a magic square *) + writeln; + write('Enter an odd number between 1 and 15: '); + readln(n); + IF NOT magic_square(n) THEN + writeln('I did not like your number which was ', n:1); + writeln('If you get it right next time, something magic will happen.'); + write('Enter an odd number between 1 and 15: '); + readln(n); + magic_square(n); + END_IF; + + + (* Try a couple of REPEAT statements *) + writeln('Test REPEAT (should print -2)'); + i := -2; + REPEAT UNTIL i = 0; + writeln(i); + println(i); + ESCAPE; + i := i + 1; + END_REPEAT; + + writeln('Test REPEAT (should print 3, 2, 1)'); + REPEAT i := 3 TO 1 BY -1; + writeln(i); + END_REPEAT; + + + (* Try the LIKE operator *) + writeln('Test LIKE'); + writeln(('A' LIKE 'A')); -- should be TRUE + writeln(('A' LIKE 'b')); -- should be FALSE + writeln(('Page 407' LIKE '$###')); -- should be TRUE + writeln(('Page 23' LIKE '$###')); -- should be FALSE + + + (* Try the REXPR function *) + writeln('Test rexpr'); + writeln(rexpr('A', 'A')); -- should be TRUE + writeln(rexpr('A', 'b')); -- should be FALSE + writeln(rexpr('Page 407', '[a-zA-Z]+\ [0-9]+')); -- should be TRUE + writeln(rexpr('Page 23', '[a-zA-Z]+\ [0-9]')); -- should be FALSE + + + (* Try an ARRAY OF ARRAY *) + a23[1][1] := 11; + a23[1][2] := 12; + a23[1][3] := 13; + a23[2][1] := 21; + a23[2][2] := 22; + a23[2][3] := 23; + + writeln('Test REPEAT (should be 1 1 11, 1 2 12, 1 3 13, 2 1 21, 2 2 22 etc)'); + REPEAT n := 1 TO 2; + REPEAT i := 1 TO 3; + writeln(n, i, a23[n][i]); + END_REPEAT; + END_REPEAT; + + + (* do some simple string operations *) + s1 := 'string'; + writeln(s1); -- should be string + s2 := s1[2:4]; + writeln(s2); -- should be tri + b := s1 <> s2; + writeln(b); -- should be TRUE + writeln(s2 + s1); -- should be tristring + + + (* Assign and print to a user-defined type *) + j := 33; + writeln(j*3); -- should be 99 + + (* Do something with a variable of type ENTITY */ + ex.attr1 := 33; + ex.attr2 := 'The attribute named attr2'; + ex.attr3 := ex.attr1/3; + writeln('ex.attr1 should be 33 and is: ', ex.attr1); + writeln('ex.attr2 is: ', ex.attr2); + writeln('ex.attr3 should be 11 and is: ', ex.attr3); + +END_CODE +\end{verbatim} +\end{code} + +\section{Specifying a {\tt SPECIAL\_} command} \label{sec:special} + + This section gives some hints on how to specify a \LaTeX\ command that +requires some special processing. The faint-hearted should skip this. It is +assumed that the implementor will have knowledge of \LaTeX, C programming, +and lex and +YACC style lexer and parser generator systems. + + There are two ways of defining \verb|SPECIAL_| kinds of commands though +neither is particularly simple. The easiest is by what is termed the +{\em coding} method. This involves modifying the standard actions. The +more complicated means is by the {\em grammar} method, which involves extending +the production grammar and, typically, also coding new kinds of actions. + + The process of specifying one of the \verb|SPECIAL_| kinds of command +actions is: +\begin{itemize} +\item Seriously question the need for the special command. One is only required if + the standard actions cannot be coerced into serving the needs of the command + processing and/or the command grammar is not supported by the \lx\ system. +\item Design the required entry for the \ctab. +\item Decide whether the coding or the grammar method is to be used for + extending \lx. + \begin{description} + \item[Coding method] Modify the actions in \file{l2xusrlb.c}, + and possibly + add new functions in \file{l2xusrlb.c} and \file{l2xusrlb.h}. + + \item[Grammar method] Extend the grammar in \file{l2x.y}. Typically it + be necessary to add new functions to the user-defined + library \file{l2xusrlb} as well. + \end{description} +\item Compile the modified \lx\ system. A \verb|make| file for this is given + in Appendix~\ref{sec:install}. +\item Test the extensions and debug the program. +\end{itemize} + + The \verb|l2xlib| has many functions that may be of use in this process. + Some of these are indicated below. + +\begin{itemize} +\item \verb|char *strsave(char s[])| saves a string somewhere +\item \verb|void myprint(char s[])| writes a string to the output medium. Its + particular action is controlled by the \verb|set_print| and + \verb|reset_print| functions, as well as the \verb|-p| option. +\item \verb|void verbatim_print(char s[])| like \verb|myprint|, + writes a string to the output medium. Its actions are controlled + by the current print mode, and newlines are obeyed (i.e., it ignores + any pretty-printing option). +\item \verb|void yyerror(char s[])| used by the lexer and parser to print + an error message string. +\item \verb|void warning(char s[])| writes a warning message string. +\item \verb|void do_newline()| used within the lexer to set internal variables + whenever a newline is encountered in the input. +\item \verb|void initialise_sysbuf()| initialises the system supplied string + buffer. +\item \verb|void print_sysbuf()| writes the content of the system string buffer + to the output file. +\item \verb|void copy_sysbuf(char s[])| copies the contents of the system + string buffer to the user-supplied string. It is the user's responsibility + to ensure that the string is big enough. +\item \verb|void set_print(PSTRWC pswitch)| controls the action of \verb|myprint|, + \verb|print_newline| and \verb|verbatim_print|. If the input argument is + \verb|p_default_print| + then the print functions should write to the output file; this is the + default behavior. If the + argument is \verb|p_no_print|, then no writing occurs. If the argument + is \verb|p_print_to_sysbuf|, then the print functions write to the system + string buffer. +\item \verb|void reset_print()| resets the behavior of the print functions. This + function should always be used after a call to \verb|set_print|. +\item \verb|int lookup_entry(char s[], int kind)| returns the location + within the \ctab\ of the + command name given in \verb|s| of the command type given in \verb|kind|. + If \verb|kind| is \verb|DONT_CARE| then the position of the first occurrence + of \verb|s| is returned. +\item \verb|void get_env_name(char s[])| extracts the name of a \LaTeX\ + environment from \verb|s|, which is assumed to have the form + \verb|\something { environment }|. The name of the environment is put + into the global string \verb|env_name|. +\item \verb|PSENTRY get_mode_sym(int loc)| returns a pointer to the + symbol table entry at position \verb|loc| in the \ctab{} + for the current mode. +\item \verb|int command_type(int loc)| returns the system defined + kind of command at location + \verb|loc| in the \ctab. +\item \verb|int get_user_type(int loc)| returns the user input (\verb|TYPE=|) + kind of command at location + \verb|loc| in the \ctab. +\item \verb|PSTRWC get_t(PSENTRY loc)| returns a pointer to the + \verb|START_TAG=| specification for symbol entry \verb|loc|. + There are similar functions for other tagging specifications. +\item \verb|PSTRWC get_tag_t(PSENTRY loc, int n)| returns a pointer + to the \verb|START_TAG_n| specification for the \verb|n|'th + argument for symbol entry \verb|loc|. There are similar + functions for other argument tagging specifications. +\item \verb|PSTRWC get_param_print(PSENTRY loc, int n)| returns a + pointer to the print control specification for the + \verb|n|'th required argument for symbol entry \verb|loc|. + There are similar functions for other print controls. +\item \verb|int get_level(PSENTRY loc)| returns the \verb|SECTIONING_LEVEL=| + value for symbol entry \verb|loc|. +\end{itemize} + + The process of specifying a \verb|SPECIAL_| is best described via +an example. + +\subsection{Example} + + Assume that there is a `non-standard' \LaTeX\ command +which has one required argument. When this command is processed by \LaTeX\ its +effect is to start a new section in a document entitled +{\em Normative References}. Some boilerplate text is then typeset (specified +within the definition of the command). This boilerplate includes two +instances of the text from the argument of the command. Finally, a +{\tt description} +list environment is started. + + In \LaTeX\ terms, this command could have been defined as: +\begin{code} +\begin{verbatim} +\newcommand{\XXspecial}[1]{\section{Normative References} + Some boilerplate text with #1 + in the middle. Now there is + some more boilerplate with #1 + in the middle of it. + \begin{description} } +\end{verbatim} +\end{code} + + For the purposes of the example, it is desired to replace the occurrence +of the \verb|\XXspecial| command by the `normal' section heading for the +output tagged style, and also print out the boilerplate text including +the argument text in the right places. The start of the list environment has +also to be taken into account. The \verb|\item| optional argument text is +to be enclosed in parentheses, with a dash before the main text. +These requirements are not something that can +be currently accomplished with the standard \lx\ system. + + To make the requirements more concrete, if the input \LaTeX\ source +includes: +\begin{code} +\begin{verbatim} +.... +\XXspecial{REQ PARAM TEXT} + +\item[Ref 1] Text 1. +\item[Ref 2] Text 2. +\end{description} +.... +\end{verbatim} +\end{code} +then the desired output is to look like: +\begin{code} +\begin{verbatim} +.... + + + + +Normative References + +Some boilerplate text with REQ PARAM TEXT +in the middle. Now there is +some more boilerplate with REQ PARAM TEXT +in the middle of it. + + (Ref 1) -- Text 1. + (Ref 2) -- Text 2. +.... +\end{verbatim} +\end{code} + + + Now, let's write a specification for the \ctab, which we will do in pieces, +starting with the sectioning tags. In this tagging style, end tags for sections +take the form \keytext{\ET{div.1}}, and start tags the form \keytext{\ST{div.1}}. +The titles of sections are enclosed between \keytext{\ST{heading}} and +\keytext{\ET{heading}} tags. We also +want some newlines in the output to set things off. If \verb|?| is used as the +escape character, then we can specify for the sectioning tagging: +\begin{latexonly} +\begin{code} +\begin{verbatim} +SECTIONING_LEVEL= SECT +START_TAG= "?n?n?n" + STRING: "Normative References?n" +END_TAG= "?n" +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +SECTIONING\_LEVEL= SECT +START\_TAG= "?n?n\ST{div.1}?n" + STRING: "\ST{heading}Normative References\ET{heading}?n" +END\_TAG= "?n\ET{div.1}" +\end{htmlverbatim} + + There is one required argument and no optional arguments, so we need: +\begin{code} +\begin{verbatim} +REQPARAMS= 1 +\end{verbatim} +\end{code} + + The \LaTeX\ command also starts off a \verb|description| environment, so we have +to set the tags for the \verb|\item| commands that will follow. This is done by: +\begin{code} +\begin{verbatim} +START_ITEM= "?n" +START_ITEM_PARAM= " (" +END_ITEM_PARAM= ") -- " +\end{verbatim} +\end{code} + + Most of the work is now completed though we still have to give the command name, +decide what sort of \verb|SPECIAL_| it will be and set the \verb|SPECIAL_TOKEN| +value. None of the provided \verb|SPECIAL_| types exactly fit this entry as it is +a mixture of sectioning and list environment, so we will just call it a +\verb|SPECIAL_COMMAND| type. +To summarize, the effective state of the \ctab\ entry is: +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= SPECIAL_COMMAND +C= NAME= to be specified +C= SPECIAL_TOKEN= to be specified + SECTIONING_LEVEL= SECT + START_TAG= "?n?n?n" + STRING: "Normative References?n" + END_TAG= "?n" + REQPARAMS= 1 + START_ITEM= "?n" + START_ITEM_PARAM= " (" + END_ITEM_PARAM= ") -- " +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= SPECIAL\_COMMAND +C= NAME= to be specified +C= SPECIAL\_TOKEN= to be specified + SECTIONING\_LEVEL= SECT + START\_TAG= "?n?n\ST{div.1}?n" + STRING: "\ST{heading}Normative References\ET{heading}?n" + END\_TAG= "?n\ET{div.1}" + REQPARAMS= 1 + START\_ITEM= "?n" + START\_ITEM\_PARAM= " (" + END\_ITEM\_PARAM= ") -- " +END\_TYPE +\end{htmlverbatim} + + For pedagogical purposes, this special will be implemented using both the +grammar and code methods, and the command names used will be \verb|\GRAMMspecial| +and \verb|\CODEspecial| respectively. + +\subsubsection{Grammar method implementation} + + The command name for this implementation will be \verb|\GRAMMspecial|. + + The grammar method requires changes to the grammar specified in \file{l2x.y}. + +\begin{enumerate} +\item A new token has to be defined, call it \verb|GRAMMSPECIAL|, in the first +part of the file. There is a slot for this under the comment \verb|/* specials */|. +An integer number, greater than or equal to 10,000 (ten thousand) and less than +32,768 ($2^{15}$), has to be +associated with this token.\footnote{The upper limit of $(2^{15}-1)$ is +set by the bison processor.} + Further, this number must not be the same as any other +number associated with any other token. Let us use +the maximum number 32,767. The relevant portion of \file{l2x.y} will look like +\begin{latexonly} +\begin{code} +\begin{verbatim} + /* specials */ +%token /* other specials here */ +%token GRAMMSPECIAL 32767 + /* precedences */ +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} + /* specials */ +\%token \ST{pos} /* other specials here */ +\%token \ST{pos} GRAMMSPECIAL 32767 + /* precedences */ +\end{htmlverbatim} +This number is used for communication within the \lx\ system, and is the number +set as the value of the \verb|SPECIAL_TOKEN| in the \ctab. We can now finalize +the \ctab\ entry as: +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= SPECIAL_COMMAND +NAME= \GRAMMspecial +SPECIAL_TOKEN= 32767 + SECTIONING_LEVEL= SECT + START_TAG= "?n?n?n" + STRING: "Normative References?n" + END_TAG= "?n" + REQPARAMS= 1 + START_ITEM= "?n" + START_ITEM_PARAM= " (" + END_ITEM_PARAM= ") -- " +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= SPECIAL\_COMMAND +NAME= \verb|\GRAMMspecial| +SPECIAL\_TOKEN= 32767 + SECTIONING\_LEVEL= SECT + START\_TAG= "?n?n\ST{div.1}?n" + STRING: "\ST{heading}Normative References\ET{heading}?n" + END\_TAG= "?n\ET{div.1}" + REQPARAMS= 1 + START\_ITEM= "?n" + START\_ITEM\_PARAM= " (" + END\_ITEM\_PARAM= ") -- " +END\_TYPE +\end{htmlverbatim} + +\item A new production, or productions, has to be added to the grammar. There is +a place for this at the end of the rules section in the file, under the predefined +production \verb|l2xSpecials|. Let us call our new production \verb|GrammSpecial|, +and add it as: +\begin{code} +\begin{verbatim} +l2xSpecials: ASpecial + | AnotherSpecial + | GrammSpecial + ; +\end{verbatim} +\end{code} +where the \verb|ASpecial| and \verb|AnotherSpecial| are pre-existing specials. + +\item The production now has to be defined, specifying the expected syntax +and required actions. This looks like: +\begin{code} +\begin{verbatim} +GrammSpecial: GRAMMSPECIAL + { + start_section($1); + myprint(get_t($1)); + myprint(get_tag_t($1,1)); + initialise_sysbuf(); + set_print(p_print_to_sysbuf); + } + ReqParam + { + initialise_string(grammbuf); + copy_sysbuf(grammbuf); + reset_print(); + prwboiler1(); + print_sysbuf(); + prwboiler2(); + myprint(grammbuf); + prwboiler3(); + start_list($1); + } + ; +\end{verbatim} +\end{code} + The actions are enclosed in braces and are defined in terms of +C code. + + Once the parser has been given the \verb|GRAMMSPECIAL| token from the lexer, +it will attempt to +perform the actions within the first set of braces. The first of these, +\verb|start_section($1)|, is the \lx\ action for starting a sectioning command. +Basically, this deals with any closing of prior sections of the document and +remembering the closing tag for this section. +The next two actions +print the start tags for the command and its required argument, +taking the strings from the \ctab. +\verb|initialise_sysbuf()| initializes the +system string buffer ready for new input. Then the print control is set so +that any output will be directed into the system string buffer rather +than the output +file. This finishes the first set of actions. + + The production grammar for the required argument comes next. If this +is incorrect, the parser automatically gives an (uninformative) error message. +Otherwise, the last set of actions are done. At this point, the text +of the required argument will be contained in the system string buffer. +This is then copied to a temporary buffer \verb|grammbuf|, that we have yet +to define, by calling +\verb|copy_sysbuf(grammbuf)| having first made sure that this buffer has +been cleared of any previous contents (the \verb|initialise_string(grammbuf)| +action). The printing control must now be reset (\verb|reset_print()|), or +things might get corrupted later. A function \verb|prwboiler1()| is called to +print the first part of the boilerplate text, followed by printing the contents +of the system buffer by the action \verb|print_sysbuf()| (remember that this should +contain the text of the required argument). The second part of the boilerplate +is written by the function \verb|prwboiler2()|. Just for pedagogical purposes, +the required argument text is written out using the text stored in the temporary +buffer (\verb|myprint(grammbuf)|) rather than from the system buffer. The penultimate +action is the printing of the last piece of boilerplate. + + The final action --- \verb|start_list($1)| --- is the standard \lx\ action +at the start of a list environment. This remembers the various tags for the list +items to follow. + + A character buffer, \verb|grammbuf|, is now defined in the initial +section of the \file{l2x.y} file, as: +\begin{code} +\begin{verbatim} +char grammbuf[80]; +\end{verbatim} +\end{code} +which is intended to be large enough to hold the text of the required +argument of the command. + + This completes the changes to the grammar file. + +\item The three functions called out in the above actions for printing +the boilerplate are coded and placed in the user library file +\file{l2xusrlb.c} and are also added to \file{l2xusrlb.h}. Here is +the relevant code as it would appear in \file{l2xusrlb.c}. +\begin{code} +\begin{verbatim} + /* demonstration string definition */ + +STRING boiler_string_3 = "\nin the middle of it.\n\n"; + + /* demonstration functions */ + +/* PRWBOILER1 print some demonstration boilerplate */ +void prwboiler1() +{ + myprint("\nSome boilerplate text with "); +} /* end PRWBOILER1 */ + +/* PRWBOILER2 print some demonstration boilerplate */ +void prwboiler2() +{ + myprint("\nin the middle. Now there is\n"); + myprint("some more boilerplate with "); +} /* end PRWBOILER2 */ + +/* PRWBOILER3 yet more demonstration boilerplate */ +void prwboiler3() +{ + myprint(boiler_string_3); +} /* end PRWBOILER1 */ +\end{verbatim} +\end{code} + +\item The system is recompiled, using \verb|make|, and tested on some example +\LaTeX\ files. + +\end{enumerate} + + + +\subsubsection{Code method implementation} + + This method `merely' requires extending the standard actions to +account for the new requirements. First, however, we must complete +the definition of the \ctab\ entry. We will call the new +command \verb|\CODEspecial|. Also a unique value has to be assigned +to the \verb|SPECIAL_TOKEN|. This must have a value greater than or +equal to 50,000 (fifty thousand). We will use a value 59,999. Later this +value is used within the action code to identify the special. +The \ctab\ entry is thus: +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= SPECIAL_COMMAND +NAME= \CODEspecial +SPECIAL_TOKEN= 59999 + SECTIONING_LEVEL= SECT + START_TAG= "?n?n?n" + STRING: "Normative References?n" + END_TAG= "?n" + REQPARAMS= 1 + START_ITEM= "?n" + START_ITEM_PARAM= " (" + END_ITEM_PARAM= ") -- " +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= SPECIAL\_COMMAND +NAME= \verb|\CODEspecial| +SPECIAL\_TOKEN= 59999 + SECTIONING\_LEVEL= SECT + START\_TAG= "?n?n\ST{div.1}?n" + STRING: "\ST{heading}Normative References\ET{heading}?n" + END\_TAG= "?n\ET{div.1}" + REQPARAMS= 1 + START\_ITEM= "?n" + START\_ITEM\_PARAM= " (" + END\_ITEM\_PARAM= ") -- " +END\_TYPE +\end{htmlverbatim} +which only differs from that for the grammar implemented special in the +\verb|SPECIAL_TOKEN=| and the \verb|NAME=| values. + + Before proceeding further, some explanation of the internals of +the \lx\ system is in order. + +\begin{description} +\item[Command table entry] Internally, an array of C {\tt struct}s +is used for storing the data corresponding to the \ctab. The {\tt struct} +is fully +defined in file \file{l2xcom.h}, and type {\tt PSENTRY} is a +pointer to an instance of the {\tt struct}. There is an entry in +the internal \ctab{} for each command. Where a command specification +is mode-dependent, then the entries for this are stored as a list (the +\ctab{} array is actually an array of lists of command specifications, +one list per command). + +For the purposes at hand, only a few +of the elements are of concern; these are \verb|kind|, \verb|parse_kind| +and \verb|special_token|. The element \verb|kind| contains an identifier +of the \verb|TYPE=| value; that is, the type of the command as specified +by the user. The element \verb|special_token| contains the +\verb|SPECIAL_TOKEN=| value. The \verb|parse_kind| element contains +an identifier of the type of command as assigned internally by \lx. +This last identifier is generated by the table processing code +in \verb|l2xlib.c| and corresponds to one of the token values +acceptable to the parser. + +\item[The lexer] The lexer reads the source \LaTeX\ file, looking for +\LaTeX\ commands (essentially anything starting with a backslash). Each +time it finds a command it looks it up in the command table array, and +sends its parser token value (the \verb|parse_kind| value) and the command +table array position to the parser. + +\item[The parser] Given a token from the lexer, the parser finds the +appropriate grammar production and performs the specified actions. It +is able to access command information through having the command table +position. + +\item[The grammar] The grammar used for the \LaTeX\ general commands (and +environments) is actually very simple --- the complexity is reserved for the +lexer and the actions. At the grammar level, no distinction is made +between a command and an environment. There are a total of 19 different +command types (tokens), which fall into a smaller number of groups. +\begin{enumerate} +\item A command with no arguments. +\item A command with just a single optional argument. +\item Commands with a final optional argument and between 1 and 8 required + arguments. +\item Commands with between 1 and 8 required arguments. In this case + it is always assumed that there might be an initial optional + argument. +\item A command with 9 required arguments. +\end{enumerate} +Note that this partitioning is based solely on the number of required +arguments and the position (if any is declared) of an optional +argument. + + For example, if a command/environment is specified in the \ctab\ as +having one required argument and no optional arguments, then this will +be treated as a command with possibly an initial optional argument and +one required argument. The grammar for this is: +\begin{code} +\begin{verbatim} +l2xComm1: COMMAND_1 + { + start_with_opt($1); + } + OptParam + { + action_opt_first($1); + } + ReqParam + { + action_last_p($1,1); + } + ; +\end{verbatim} +\end{code} +where the words in all upper case are grammar tokens, and words in mixed +case are other grammar productions. The actions are enclosed between braces. +The \verb|$1| is the position of the command in the command table array. + +\item[Actions] The standard actions are contained in file \file{l2xacts.c}. +Within the code for each standard action, provision is made for +calling +action code for specials. All the functions have the same +general structure. Here, for instance, is the code for the standard +action that is called between the start of a command and a first optional +argument. +\begin{code} +\begin{verbatim} +/* START_WITH_OPT start action for command with optional param */ +void start_with_opt(pos) +int pos; /* position of command in table */ +{ + int user_kind; /* user-specified command type */ + + user_kind = get_user_type(pos); + + switch(user_kind) { + case TEX_CHAR: /* the general, non-specials */ + case CHAR_COMMAND: + case COMMAND: + case BEGIN_ENV: + case END_ENV: + case BEGIN_LIST_ENV: + case END_LIST_ENV: + case SECTIONING: + start_it(pos); /* command start action */ + default_start_with_opt(pos); /* start optional param */ + break; + case SPECIAL: /* the specials */ + case SPECIAL_BEGIN_ENV: + case SPECIAL_END_ENV: + case SPECIAL_BEGIN_LIST: + case SPECIAL_END_LIST: + case SPECIAL_COMMAND: + case SPECIAL_SECTIONING: + special_start_with_opt(pos); + break; + default: /* should not be here! */ + warning("(start_with_opt) Unrecognized command type"); + break; + } /* end switch on user_kind */ +} /* end START_WITH_OPT */ +\end{verbatim} +\end{code} + + The special actions code is in file \verb|l2xusrlib.c|. The code +for these all follow the same general pattern. For example, here is +the code implementing the special action between the start of a +command and a first optional argument. +\begin{code} +\begin{verbatim} +/* SPECIAL_START_WITH_OPT special start for command with opt param */ +void special_start_with_opt(pos) +int pos; /* command position in table */ +{ + int special_kind; /* user-specified special token */ + + special_kind = get_special_token(pos); + + switch(special_kind) { + /* additional cases for specials added here */ + + /* end of cases for specials */ + default: /* should not be here! */ + warning("(special_start_with_opt) Unrecognized SPECIAL"); + tdebug_str_int("SPECIAL_TOKEN =",special_kind); + break; + } /* end of switch on user_kind */ +} /* end SPECIAL_START_WITH_OPT */ +\end{verbatim} +\end{code} +Note that the code as provided just issues a warning message. + + +\end{description} + + + With this background, we will now go on with the example. + +\begin{enumerate} +\item Decide on how the \lx\ system will translate your command/environment +description into its internal grammar command type. In this case it +will translate into a command with possibly an initial optional argument +and one required argument. + +\item Examine the grammar for the command and hence determine which standard +actions will be called. In this case there are three of these, namely +\verb|start_with_opt|, \verb|action_opt_first| and \verb|action_last_p|. +These are the actions that might require modification. + +\item Determine what actions are required for your special. Conceptually +replace the standard actions in the grammar by your actions. Then determine +how these should be incorporated into the special action code in +\verb|l2xusrlb|. In plain +language, the grammar and conceptual actions for the example are: +\begin{code} +\begin{verbatim} +l2xComm1: COMMAND_1 + { + start of as a sectioning command + ignore the optional argument as there isn't one + } + OptParam + { + finish processing the non-existent optional + get ready to store the argument text in a buffer + } + ReqParam + { + print the boilerplate and argument text + start the description list + } + ; +\end{verbatim} +\end{code} +Note that this is essentially the same as we did for the grammar +implementation for \verb|\GRAMMspecial|, except that there is the additional +optional argument to be dealt with. + +\item Modify the requisite special action code. + + In the example, three standard actions have to be modified. Here is +the modification to \verb|special_start_with_opt|: +\begin{code} +\begin{verbatim} +/* SPECIAL_START_WITH_OPT special start for command with opt param */ +void special_start_with_opt(pos) +int pos; /* command position in table */ +{ + int special_kind; /* user-specified special token */ + + special_kind = get_special_token(pos); + + switch(special_kind) { + /* additional cases for specials added here */ + case 59999: /* example coded special */ + codespecial_start(pos); + default_start_with_opt(pos); + break; + + /* end of cases for specials */ + default: /* should not be here! */ + warning("(special_start_with_opt) Unrecognized SPECIAL"); + tdebug_str_int("SPECIAL_TOKEN =",special_kind); + break; + } /* end of switch on user_kind */ +} /* end SPECIAL_START_WITH_OPT */ +\end{verbatim} +\end{code} +The addition is done by adding a new \verb|case 59999:| together with +appropriate code. The number 59999 is that corresponding to the +value for \verb|SPECIAL_TOKEN=| in the command table specification +of \verb|\CODEspecial|. The function \verb|codespecial_start| is to +be written, while \verb|default_start_with_opt| is an \lx\ defined +function which initiates processing of an initial optional argument. + + Similarly, here is the modification to \verb|special_action_opt_first|: +\begin{code} +\begin{verbatim} + /* additional cases for specials added here */ + case 59999: /* example coded special */ + default_end_start_opt(pos); + codespecial_p1(pos); + break; + + /* end of cases for specials */ +\end{verbatim} +\end{code} +where \verb|codespecial_p1| is to be written and \verb|default_end_start_opt| +is the standard \lx\ action at the end of an initial optional argument. + +Finally, here is the modification to \verb|special_action_last_p|: +\begin{code} +\begin{verbatim} +/* SPECIAL_ACTION_LAST_P action after last req argument */ +void special_action_last_p(pos,p) +int pos; /* position of command in table */ +int p; /* number of last argument */ +{ + int special_kind; /* user-specified special token */ + + special_kind = get_special_token(pos); + + switch(special_kind) { + /* additional cases for specials added here */ + case 59999: /* example coded special */ + if (p == 1) { /* has only one req param */ + codespecial_end(pos); + } + break; + + /* end of cases for specials */ + /* stuff deleted to save space */ +\end{verbatim} +\end{code} + +\item Code the functions for the new actions. + + Code for these functions should be put into file \verb|l2xusrlb.c| +and file \verb|l2xusrlb.h| modified accordingly. + + Here is the code for the three \verb|codespecial_| functions. +\begin{code} +\begin{verbatim} +char codebuf[80]; /* a string buffer */ + +/* CODESPECIAL_START actions for start of CODEspecial command */ +void codespecial_start(pos) +int pos; /* command table position */ +{ + start_section(pos); /* do start of sectioning */ + myprint(get_t(pos)); /* print start tag */ +} /* end CODESPECIAL_START */ + +/* CODESPECIAL_P1 actions at start of CODEspecial param 1 */ +void codespecial_p1(pos) +int pos; /* command table position */ +{ + myprint(get_tag_t(pos,1)); /* print 1st param start tag */ + initialise_sysbuf(); /* clear system string buffer */ + set_print(p_print_to_sysbuf); /* put arg text into sys buffer */ +} /* end CODESPECIAL_P1 */ + +/* CODESPECIAL_END actions at end of CODEspecial command */ +void codespecial_end(pos) +int pos; /* command table position */ +{ + initialise_string(codebuf); /* clear this string buffer */ + copy_sysbuf(codebuf); /* copy sys buffer into codebuf */ + reset_print(); /* normal printing */ + prwboiler1(); /* print some boilerplate */ + print_sysbuf(); /* print system buffer */ + prwboiler2(); /* print more boilerplate */ + myprint(codebuf); /* print codebuff */ + prwboiler3(); /* print yet more boilerplate */ + start_list(pos); /* start a list environment */ +} /* end CODESPECIAL_END */ +\end{verbatim} +\end{code} +Note that these actions are almost identical to those that were used +within the grammar when implementing the \verb|\GRAMMspecial| command. + +\item Compile the modified system and test it on example \LaTeX\ files. + +\end{enumerate} + +\subsection{Notes} + +\begin{enumerate} +\item Installation of a \keyword{SPECIAL\_} can be limited to making changes + to the parser (file \verb|l2x.y|) and/or the user library + (files \verb|l2xusrlb.c| and \verb|l2xusrlb.h|). + It should not be necessary to touch any other part of the system. + +\item Changes to \file{l2x.y} will necessitate executing the parser generator + on this file and + system compilation. Changes to the other files will only necessitate + compilation. + +\item Always use the \keytext{myprint}, \keytext{verbatim\_print} + or \keytext{print\_sysbuf} functions for + printing because they incorporate the print control + capability. + +\item The printing in the above example is trivial. However, it is good practice + to define printed output separately from the parser. It makes for easier + maintenance. If, for example the boilerplate above was several thousand + characters, it might have been an idea to store the text in a file, or + files, and then have the boilerplate printing functions read from + the file(s). + If the text is in a state of flux this could be a good design decision + in any case, as changing the text would only involve modifying the + text file(s) and avoid recompilation of \lx. +\end{enumerate} + +\subsubsection{An updated method} + + The above descriptions of installing a \verb|SPECIAL_| command were +written for the original release of the \lx{} system, which did not +have the input and output specification facilities currently available +within a \ctab. Below is given a possible \ctab{} entry using these +facilities. +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= SPECIAL_COMMAND +NAME= \THIRDspecial + C= SPECIAL_TOKEN= set the appropriate number + SECTIONING_LEVEL= SECT + START_TAG= "?n?n?n" + STRING: "Normative References?n" + RESET_SYSBUF: + END_TAG= "?n" + REQPARAMS= 1 + PRINT_P1= TO_SYSBUF + END_TAG_1= + STRING: "?nSome boilerplate text with " + SOURCE: SYSBUF + STRING: "?nin the middle. Now there is?n" + STRING: "some more boilerplate with " + SOURCE: SYSBUF + STRING: "?nin the middle of it.?n" + START_ITEM= "?n" + START_ITEM_PARAM= " (" + END_ITEM_PARAM= ") -- " +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= SPECIAL\_COMMAND +NAME= \THIRDspecial + C= SPECIAL\_TOKEN= set the appropriate number + SECTIONING\_LEVEL= SECT + START\_TAG= "?n?n\ST{div.1}?n" + STRING: "\ST{heading}Normative References\ET{heading}?n" + RESET\_SYSBUF: + END\_TAG= "?n\ET{div.1}" + REQPARAMS= 1 + PRINT\_P1= TO\_SYSBUF + END\_TAG\_1= + STRING: "?nSome boilerplate text with " + SOURCE: SYSBUF + STRING: "?nin the middle. Now there is?n" + STRING: "some more boilerplate with " + SOURCE: SYSBUF + STRING: "?nin the middle of it.?n" + START\_ITEM= "?n" + START\_ITEM\_PARAM= " (" + END\_ITEM\_PARAM= ") -- " +END\_TYPE +\end{htmlverbatim} +The actual implementation of this as either a grammar special or a code +special is left as an exercise for the reader. Basically it involves +the deletion of the specific print action and buffer code because this is now +handled automatically via the \ctab{} specification. + + +\clearpage +\appendix +\section{Example \protect\ctab\ file for de-\TeX ing} \label{sec:detexing} + + This appendix provides the skeleton of a \ctab\ file that could be used for +de-\TeX ing a \LaTeX\ document. + +\begin{code} +\begin{verbatim} +C= detex.ct command table file for ltx2x to deTeX source + +C= -----------------------------------escape sequences + +C= don't use default here as it may clash with command name output +ESCAPE_CHAR= ? +C= keep tye default vaues for the rest + +C= ----------------------------------- the built in commands +TYPE= BEGIN_DOCUMENT +END_TYPE + +TYPE= END_DOCUMENT +END_TYPE + +TYPE= BEGIN_VERB +END_TYPE + +TYPE= END_VERB +END_TYPE + +TYPE= BEGIN_VERBATIM + START_TAG= "?n" +END_TYPE + +TYPE= END_VERBATIM + START_TAG= "?n" +END_TYPE + +TYPE= BEGIN_DOLLAR +END_TYPE + +TYPE= END_DOLLAR +END_TYPE + +TYPE= SLASH_SPACE + START_TAG= " " +END_TYPE + +TYPE= OTHER_COMMAND + PRINT_CONTROL= NO_PRINT +END_TYPE + +TYPE= OTHER_BEGIN + PRINT_CONTROL= NO_PRINT +END_TYPE + +TYPE= OTHER_END + PRINT_CONTROL= NO_PRINT +END_TYPE + +C= throw away naked braces +TYPE= LBRACE +END_TYPE + +TYPE= RBRACE +END_TYPE + +C= Pretty printing will probably be applied. Indent start of paragraphs +TYPE= PARAGRAPH + START_TAG= "?n?n " +END_TYPE + +C= -------------------------------------(La)TeX special characters + +C= hash (for use in \def s ) +TYPE= TEX_CHAR +NAME= # +END_TYPE + +C= ampersand (tabular column delimiter, replace by some spaces) +TYPE= TEX_CHAR +NAME= & + START_TAG= " " +END_TYPE + +C= twiddle (unbreakable space) +TYPE= TEX_CHAR +NAME= ~ + START_TAG= " " +END_TYPE + +C= underscore (math subscript) +TYPE= TEX_CHAR +NAME= _ + START_TAG= "_" +END_TYPE + +C= caret (math superscript) +TYPE= TEX_CHAR +NAME= ^ + START_TAG= "^" +END_TYPE + +C= at +TYPE= TEX_CHAR +NAME= @ + START_TAG= "@" +END_TYPE + +C= ------------------------- default single character commands +C= (replace by appropriate character) + +C= LaTeX start a new line +TYPE= CHAR_COMMAND +NAME= \\ + START_TAG= "?n" +END_TYPE + +C= small space +TYPE= CHAR_COMMAND + NAME= \, +START_TAG= " " +END_TYPE + +C= end of sentence space +TYPE= CHAR_COMMAND +NAME= \@ + START_TAG= " " +END_TYPE + +C= hash +TYPE= CHAR_COMMAND +NAME= \# + START_TAG= "#" +END_TYPE + +C= dollar +TYPE= CHAR_COMMAND +NAME= \$ + START_TAG= "$" +END_TYPE + +C= ampersand +TYPE= CHAR_COMMAND +NAME= \& + START_TAG= "&" +END_TYPE + +C= underscore +TYPE= CHAR_COMMAND +NAME= \_ + START_TAG= "_" +END_TYPE + +C= percent +TYPE= CHAR_COMMAND +NAME= \% + START_TAG= "%" +END_TYPE + +C= left brace +TYPE= CHAR_COMMAND +NAME= \{ + START_TAG= "{" +END_TYPE + +C= right brace +TYPE= CHAR_COMMAND +NAME= \} + START_TAG= "}" +END_TYPE + +C= optional hyphenation +TYPE= CHAR_COMMAND +NAME= \- + START_TAG= "" +END_TYPE + +C= ----------------------------- General LaTeX + +TYPE= COMMAND +NAME= \caption + START_TAG= "?n CAPTION: " + OPT_PARAM= FIRST + PRINT_OPT= NO_PRINT + REQPARAMS= 1 +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= itemize + START_TAG= "?n" + START_ITEM= "?n o " +END_TYPE + +TYPE= END_LIST_ENV +NAME= itemize + START_TAG= "?n" +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= enumerate + START_TAG= "?n" + START_ITEM= "?n -- " +END_TYPE + +TYPE= END_LIST_ENV +NAME= enumerate + START_TAG= "?n" +END_TYPE + +TYPE= BEGIN_LIST_ENV +NAME= description + START_TAG= "?n" + START_ITEM= "?n " + END_ITEM_PARAM= " : " +END_TYPE + +TYPE= END_LIST_ENV + NAME= description +START_TAG= "?n" +END_TYPE + +C= replace \footnote with parenthesized text +TYPE= COMMAND +NAME= \footnote + START_TAG= " (" + END_TAG= ") " + OPT_PARAM= FIRST + PRINT_OPT= NO_PRINT + REQPARAMS= 1 +END_TYPE + +C= ----------------------- sectioning (keep headers only) + +C= repeat for all the other sectioning commands +TYPE= SECTIONING +NAME= \section + SECTIONING_LEVEL= SECT + START_TAG= "?n?n" + OPT_PARAM= FIRST + PRINT_OPT= NO_PRINT + REQPARAMS= 1 + END_TAG_1= "?n?n" +END_TYPE + +C= repeat for all the other starred sectioning commands +TYPE= SECTIONING +NAME= \section* + SECTIONING_LEVEL= SECT + START_TAG= "?n?n" + REQPARAMS= 1 + END_TAG_1= "?n?n" +END_TYPE + +C= and whatever else is interesting +END_CTFILE= +\end{verbatim} +\end{code} + +\section{LaTeX to HTML translation} \label{sec:htmling} + + The \ctab{} file \file{l2h.ct} contains a set of commands that +enable simple \LaTeX{} documents to be translated into HTML tagged +documents for display using a World Wide Web browser. At a minumum +this \ctab{} can be used for conversion of the \LaTeX{} source of +this manual. It can also handle some very simple mathematics but not +pictures.\footnote{HTML itself cannot handle pictures directly (i.e., +there is no equivalent to the \LaTeX{} \keytext{picture} environment), +and can only handle simple mathematics.} The specification +for the HTML tags was taken from Musciano and Kennedy~\cite{MUSCIANO96}. + + Generally speaking and subject to the above limitations, +a \LaTeX{} document can be translated +to HTML without the document having been planned for this purpose, +with one exception. +The exception is that a new \LaTeX{} command should be used in the +document preamble. +I have called this \verb|\mltitle| and its purpose to to define +the contents of the header for the HTML text. The definition of this command +is: +\begin{verbatim} +\newcommand{\mltitle}[1]{} +\end{verbatim} +That is, as far as \LaTeX{} is concerned, the argument to the command is +thrown away and is a non-event. As far as the \file{l2h.ct} \ctab{} is concerned +the argument is the header title. As an example, this manual starts with: +\begin{verbatim} +... +\mltitle{LaTeX to X translator} +\begin{document} +\title{\lx: A \LaTeX{} to X Auto-tagger} +... +\end{verbatim} +which gets converted into: +\begin{latexonly} +\begin{verbatim} + + +LaTeX to X translator + + + +

+ LTX2X: A LaTeX to X Auto-tagger +

+... +\end{verbatim} +\end{latexonly} +\begin{htmlverbatim} + + +LaTeX to X translator\ET{title} +\ET{head} +<body> + +<h1 align=center> + LTX2X: A LaTeX to X Auto-tagger +\ET{h1} +... +\end{htmlverbatim} +If the \verb|\mltitle| command is not used, then the effect is to have +an empty \ST{title} in the \ST{head} of the HTML document. + + + Several aspects of the design of \file{l2h.ct} in the context of +the conversion of typical \LaTeX{} documents have been discussed +as examples in the body of the manual. However, there are some aspects +specific to the translation of this document should be mentioned. +These stem from the fact that HTML has no tags corresponding to +to the \LaTeX{} \verb|\verb| command or \verb|verbatim| environment which +switch off the meanings of special characters. + + HTML treats the characters \LT, \GT, \Amp{} and \HASH{} specially. +Within a \ST{pre}...\ET{pre} the browser honours the line breaks +but does not switch off the meanings of the special characters. In \LaTeX{}, +the \verb|\verb| command switches off all special characters but prohibits +any line breaking. The \verb|verbatim| environment both honours line breaks +and switches off all special characters. The difficulty with this particular +document is that I want to show author-formatted HTML source, and that is not +easly possible, unlike using the \LaTeX{} \verb|verbatim| environment for +showing user-formatted \LaTeX{} source. + + The problem was solved through the use of two \LaTeX{} environments. +The first of these is \keytext{latexonly} which is used for input that is +to be processed normally by \LaTeX{} but which is to be totally ignored +by \lx. The other environment is \keytext{htmlverbatim} which is used +for input that is to be totally ignored by \LaTeX{} but which is to be +processed by \lx{} into an HTML \ST{pre} environment. + + A package file has been written which provides some addtional +commands and environments. +\begin{latexonly} +\begin{code} +\begin{verbatim} +% ltx2html.sty --- Some useful commands and environments when using +% ltx2x to convert from LaTeX to HTML tagging. +% +% Author: Peter Wilson August 1996 +% +\ProvidesPackage{ltx2html}[1996/08/29 ltx2x HTMLing] +\RequirePackage{html} % the package file for the Perl program + % latex2html + +% The document title for the WWW browser. +% If used, must be placed in the preamble. +\newcommand{\mltitle}[1]{} + +% argument is for processing by LaTeX only +\providecommand{\latex}[1]{#1} + +% argument is for HTML processing only +\providecommand{\html}[1]{} + +% print argument as an SGML/HTML start tag +\newcommand{\ST}[1]{\texttt{<#1>}} + +% print argument as an SGML/HTML end tag +\newcommand{\ET}[1]{\texttt{</#1>}} + +% print HTML special characters +\newcommand{\Amp}{\&} +\newcommand{\GT}{\texttt{>}} +\newcommand{\LT}{\texttt{<}} +\newcommand{\HASH}{\#} + +% treat contents as a LaTeX comment but +% translate contents into an HTML "verbatim" environment +% Use as: \begin{htmlverbatim} ... \end{htmlverbatim} +\excludecomment{htmlverbatim} + +\endinput +\end{verbatim} +\end{code} +\end{latexonly} + +\begin{htmlverbatim} +% ltx2html.sty --- Some useful commands and environments when using +% ltx2x to convert from LaTeX to HTML tagging. +% +% Author: Peter Wilson August 1996 +% +\verb|\ProvidesPackage{ltx2html}[1996/08/29 ltx2x HTMLing]| +\verb|\RequirePackage{html} % the package file for the Perl program| + \% latex2html + +\% The document title for the WWW browser. +\% If used, must be placed in the preamble. +\verb|\newcommand{\mltitle}[1]{}| + +\% argument is for processing by LaTeX only +\verb|\providecommand{\latex}[1]|\{\HASH{}1\} + +\% argument is for HTML processing only +\verb|\providecommand{\html}[1]{}| + +\% print argument as an SGML/HTML start tag +\verb|\newcommand{\ST}|[1]\{\ST{\HASH{}1}\} + +\% print argument as an SGML/HTML end tag +\verb|\newcommand{\ET}|[1]\{\ET{\HASH{}1}\} + +\% print HTML special characters +\verb|\newcommand{\Amp}|\{\Amp\} +\verb|\newcommand{\GT}|\{\GT\} +\verb|\newcommand{\LT}|\{\LT\} +\verb|\newcommand{\HASH}|\{\HASH\} + +\% treat contents as a LaTeX comment but +\% translate contents into an HTML "verbatim" environment +\verb|% Use as: \begin{htmlverbatim} ... \end{htmlverbatim}| +\verb|\excludecomment{htmlverbatim}| + +\verb|\endinput| +\end{htmlverbatim} + + The \ctab{} entries for some of these are: +\begin{latexonly} +\begin{code} +\begin{verbatim} +TYPE= COMMAND +NAME= \Amp + START_TAG= "&" +END_TYPE + +TYPE= COMMAND +NAME= \GT + START_TAG= ">" +END_TYPE + +TYPE= COMMAND +NAME= \LT + START_TAG= "<" +END_TYPE + +TYPE= COMMAND +NAME= \HASH + START_TAG= "#" +END_TYPE + +TYPE= COMMAND +NAME= \ST + START_TAG= "<" + END_TAG= ">" + REQPARAMS= 1 +END_TYPE + +TYPE= COMMAND +NAME= \ET + START_TAG= "</" + END_TAG= ">" + REQPARAMS= 1 +END_TYPE +\end{verbatim} +\end{code} +\end{latexonly} +\begin{htmlverbatim} +TYPE= COMMAND +NAME= \Amp + START\_TAG= "\Amp{}amp;" +END\_TYPE + +TYPE= COMMAND +NAME= \GT + START\_TAG= "\Amp{}gt;" +END\_TYPE + +TYPE= COMMAND +NAME= \LT + START\_TAG= "\Amp{}lt;" +END\_TYPE + +TYPE= COMMAND +NAME= \HASH + START\_TAG= "\Amp\HASH035;" +END\_TYPE + +TYPE= COMMAND +NAME= \verb|\ST| + START\_TAG= "\Amp{}lt;" + END\_TAG= "\Amp{}gt;" + REQPARAMS= 1 +END\_TYPE + +TYPE= COMMAND +NAME= \verb|\ET| + START\_TAG= "\Amp{}lt;/" + END\_TAG= "\Amp{}gt;" + REQPARAMS= 1 +END\_TYPE +\end{htmlverbatim} + + Finally, as an example, this is how some of the prior example text +could be +written in the source of this document. +\begin{latexonly} +\begin{verbatim} +\begin{latexonly} +\begin{verbatim} +<html> +<head> +<title>LaTeX to X translator + + + +

+ LTX2X: A LaTeX to X Auto-tagger +

+... +\end{verbatim} +\verb|\end{verbatim}| \\ +\verb.\end{latexonly}. +\end{latexonly} +\begin{latexonly} +\begin{verbatim} + +\begin{htmlverbatim} + + +LaTeX to X translator\ET{title} +\ET{head} +<body> + +<h1 align=center> + LTX2X: A LaTeX to X Auto-tagger +\ET{h1} +... +\end{htmlverbatim} +\end{verbatim} +\end{latexonly} + +\begin{htmlverbatim} +\verb|\begin{latexonly}| +\verb|\begin{verbatim}| +<html> +<head> +<title>LaTeX to X translator + + + +

+ LTX2X: A LaTeX to X Auto-tagger +

+... +\verb|\end{verbatim}| +\verb|\end{latexonly}| + +\verb|\begin{htmlverbatim}| + + +LaTeX to X translator\verb|\ET{title}| +\verb|\ET{head}| +<body> + +<h1 align=center> +<title>LaTeX to X translator\verb|\ET{title}| +\verb|\ET{head}| +\verb|...| +\verb|\end{htmlverbatim}| +\end{htmlverbatim} + + Reading the \LaTeX{} source of this document will reveal some +other details. Admittedly the problem was compounded by the fact +that this document contains demonstrations of both \LaTeX{} and +HTML commands which will be processed through both \LaTeX{} and HTML +browsers, thus a modicum of care is required to appropriately +process both sets of special characters. + + +\section{Known limitations} \label{sec:limitations} + + \lx\ does not do everything that it might (and probably never will). +The following are some of the things that it does not do. + +\begin{itemize} +\item It does not understand the \LaTeX\ \verb|\input| or \verb|\include| + commands --- + it just reads the source file as given. It may be useful to pre-process the + source file through a program that will automatically incorporate included + files into a \LaTeX\ root file~\cite{PRW94b}. + +\item The \verb|\newcommand| and friends do not readily + fit into the command patterns that + \lx\ can deal with. In particular, if it comes across a \verb|\newcommand| + specification for a command that is specified in the \ctab, interesting + results might occur (for example, all the following output could be thrown + away if the command takes any arguments). + + For instance, if the document and the \ctab\ contain: +\begin{code} +\begin{verbatim} +\newcommand{\lx}{LTX2X} +.... +The \lx\ program ... + +TYPE= COMMAND +NAME= \lx + START_TAG= "LTX2X" +END_TYPE +\end{verbatim} +\end{code} + then there is usually no problem. On the other hand, if the document and + the \ctab\ contain: +\begin{code} +\begin{verbatim} +\newcommand{\fd}[1]{\texttt{#1}} +.... +where \fd{InputFile} is the name ... + +TYPE= COMMAND +NAME= \fd + REQPARAMS= 1 +END_TYPE +\end{verbatim} +\end{code} + then there may be a problem, which might be as `minor' as \lx\ reporting + a parse error when it has reached \verb|\newcommand{\fd}| in the input + file and then carrying on, or it may be more serious. + +\item There is a slight problem with optional arguments. \lx\ always takes the + first close bracket (\verb|]|) after the opening bracket as signalling + the end of the argument text. This occurs even if the close bracket + is enclosed in braces (i.e. \verb|{]}|). Opening brackets within optional + argument text are handled correctly. + +\item It cannot sensibly handle \LaTeX{} + constructs of the form \verb|{\em emph text}|. + That is, except for command arguments, it does not recognize + \verb|{...}| as a grouping construct, so cannot successfully + tag the end of the \verb|emph text| in the example. On the other + hand, if constructs like \verb|\emph{emph text}| or + \verb|\begin{em}emph text\end{em}| are used instead, start and end + tags can be generated, given appropriate specifications in the + \ctab. + +\item It assumes that all commands that take arguments are written so + that each argument is enclosed in braces. For example, the + superscripting command should be written as \verb|^{2}| and not + as \verb|^2|. Similarly, accent commands should be written as + \verb|\={o}| rather than \verb|\=o|, and so on. + +\item There has not been time to test all aspects of the \ExpressA{} + interpreter. It is possible that this may not perform quite + as advertised. In particular dynamic aggregates have not been fully + implemented. For example: +\begin{code} +\begin{verbatim} +LIST OF INTEGER; +\end{verbatim} +\end{code} + appears to be handled correctly. More complicated constructs involving + dynamic aggregates, such as +\begin{code} +\begin{verbatim} +ARRAY [1:7] OF LIST OF ARRAY [-21:21] OF INTEGER; +\end{verbatim} +\end{code} + have not been tested. It is improbable that \keyword{BAG} will + work; the status of \keyword{SET} is similar and additionally + the uniqueness test for set membership has not been implemented. +\item No doubt other limitations will come to light as \lx\ gets more use. + On the other + hand, \lx{} has been able to handle a broader range of cases than + it was designed to address. + + +\end{itemize} + + +\section{Command table summary} \label{sec:summary} + + This section summarizes the commands and specifications available +for defining a \ctab. + +\subsection{Special print characters} + + The combination of an escape character and another character can be used to +specify certain non-visible characters within a tag string. The commands are +given in Table~\ref{tab:spc}. + +\begin{table}[htbp] +\centering +\caption{Special print character commands.} \label{tab:spc} +\begin{tabular}{|l|c|} \hline +Command & Default \\ \hline +\keyword{AUDIBLE\_ALERT\_CHAR=} & \verb|a| \\ +\keyword{BACKSPACE\_CHAR=} & \verb|b| \\ +\keyword{CARRIAGE\_RETURN\_CHAR=} & \verb|r| \\ +\keyword{ESCAPE\_CHAR=} & \verb|\| \\ +\keyword{FORMFEED\_CHAR=} & \verb|f| \\ +\keyword{HEX\_CHAR=} & \verb|x| \\ +\keyword{HORIZONTAL\_TAB\_CHAR=} & \verb|t| \\ +\keyword{NEWLINE\_CHAR=} & \verb|n| \\ +\keyword{VERTICAL\_TAB\_CHAR=} & \verb|v| \\ \hline +\end{tabular} +\end{table} + + These commands take one character as their value. If any commands are not +specified, then the default value is used. These commands, if used, must be +at the beginning of the \ctab\ before any \keyword{TYPE=} commands, +although their ordering is not significant among themselves. + +\subsection{\ExpressA{} code initialization} + + The keyword \keyword{CODE\_SETUP=} indicates that the following part +of the \ctab, up until the \keyword{END\_CODE} keyword, contains +\ExpressA{} code declarations and/or statements. If used, this block +must come before any of the \keyword{TYPE=} commands. + +\subsection{Comments and file inclusion} + + A comment within a \ctab\ file is any line starting with \keyword{C= }. + + A file can be included within another \ctab\ file with the command line +\begin{verbatim} +INCLUDE= FileName +\end{verbatim} +where \keytext{FileName} is the name of the file to be included. The +\keyword{INCLUDE=} +command cannot appear between the command pair \keyword{TYPE=} and its following +\keyword{END\_TYPE}. + + The end of a \ctab\ file is either the physical end of the file or +the command \keyword{END\_CTFILE=}, whichever occurs first. + +\subsection{Command types} + + All command type specifications have the general form: +\begin{verbatim} +TYPE= CommandType +NAME= CommandName + C= a possibly empty list of mode-independent commands + C= possibly sets of mode-dependent commands +END_TYPE +\end{verbatim} +where \keytext{CommandType} is a keyword identifying the kind of command being +specified and \keytext{CommandName} is the identifier of a \LaTeX{} command +or environment. The potential set of commands that can be used between the +\keyword{TYPE=} +and \keyword{END\_TYPE} commands depends on the kind of command being specified, +but the special print character commands, Table~\ref{tab:spc}, +and the \keyword{INCLUDE=} command cannot +appear within a type specification. All command specifications, except +for the built in command types (see Table~\ref{tab:rct}), +must include at least a \keyword{NAME=} command. +The ordering of commands within a type +specification is not significant. The ordering of type specifications within +a \ctab\ file is not significant. + + The \keyword{NAME=} command takes as its value the name of a \LaTeX\ command or +environment. The name must be written exactly as it would appear in a \LaTeX\ +source file. That is, \verb|\command| for any command except \verb|\begin{}| +or \verb|\end{}|, and as \verb|env| for an +environment begun as \verb|\begin{env}| or ended by \verb|\end{env}|. + +\subsubsection{Built in command types} + + Table~\ref{tab:rct} lists the keywords for the built in command types. + +\begin{table}[htbp] +\centering +\caption{Built in command type keywords.} \label{tab:rct} +\begin{tabular}{|l|c|} \hline +Keyword & \LaTeX\ command \\ \hline +\keyword{BEGIN\_DOCUMENT} & \verb|\begin{document}| \\ +\keyword{BEGIN\_DOLLAR} & \verb|$| at start of in-text math \\ +\keyword{BEGIN\_VERB} & \verb|\verb| or \verb|\verb*| and its following character \\ +\keyword{BEGIN\_VERBATIM} & \verb|\begin{verbatim}| or \verb|\begin{verbatim*}| \\ +\keyword{END\_DOCUMENT} & \verb|\end{document}| \\ +\keyword{END\_DOLLAR} & \verb|$| at end of in-text math \\ +\keyword{END\_VERB} & the ending character for \verb|\verb| or \verb|\verb*| \\ +\keyword{END\_VERBATIM} & \verb|\end{verbatim}| or \verb|\end{verbatim*}| \\ +\keyword{LBRACE} & \verb|{| \\ +\keyword{OTHER\_BEGIN} & of the form \verb|\begin{env}| not specified elsewhere \\ +\keyword{OTHER\_COMMAND} & of the form \verb|\comm| not specified elsewhere \\ +\keyword{OTHER\_END} & of the form \verb|\end{env}| not specified elsewhere \\ +\keyword{PARAGRAPH} & blank source line \\ +\keyword{RBRACE} & \verb|}| \\ +\keyword{SLASH\_SPACE} & \verb*|\ | \\ \hline +\end{tabular} +\end{table} + + The built in command type specifications can only sensibly use two kinds +of actions --- +those specified at the start of the command (e.g., \keyword{PC\_AT\_START=} +and \keyword{START\_TAG=}) and/or actions at the end of the command +(e.g., \keyword{PC\_AT\_END} and \keyword{END\_TAG=}). +The \keyword{NAME=} command must not be used. + + The \keyword{OTHER\_} types are an exception to the above, in that they can include +the command line \keyword{PRINT\_CONTROL= NO\_PRINT}. + + \lx\ checks the command table for the presence of these required types. If one +or more have not been specified, then they are automatically added to the command table +with default values (e.g. empty strings) for the tags, and a warning message is +printed giving the default value(s). + +\subsubsection{Optional command types} + + For discussion purposes, the optional command types have been tabulated +in different categories. The basic distinction between these categories is +the sets of commands that are permissible within the command specification. + + At a minimum, all the specifications must include a \keyword{NAME=} command +and must not contain any \keyword{PRINT\_CONTROL=} or \keyword{INCLUDE=} commands +or the special +print character commands listed in Table~\ref{tab:spc}. + + + The keywords for the general command types are given Table~\ref{tab:gct}. + +\begin{table}[htbp] +\centering +\caption{General command type keywords.} \label{tab:gct} +\begin{tabular}{|l|c|} \hline +Keyword & \LaTeX\ command form \\ \hline +\keyword{TEX\_CHAR} & \LaTeX\ special characters (except \verb|{ } $|) \\ +\keyword{CHAR\_COMMAND} & \verb|\c|, where \verb|c| is non-alphabetic \\ +\keyword{COMMAND} & \verb|\command| except for sectioning or picture commands \\ +\keyword{BEGIN\_ENV} & \verb|\begin{env}| except for \verb|\item| lists \\ +\keyword{END\_ENV} & \verb|\end{env}| except for \verb|\item| lists \\ +\keyword{VCOMMAND} & a \verb|\verb|-like command \\ +\keyword{BEGIN\_VENV} & start of a \verb|verbatim|-like environment \\ +\keyword{END\_VENV} & end of a \verb|verbatim|-like environment \\ \hline +\end{tabular} +\end{table} + + A general command type specification can include any of the tagging and print +option commands. They cannot contain a \keyword{SECTION\_LEVEL=} command, nor can +they contain any of the \keyword{\_ITEM\_} commands. + + The keywords for the specific command types are given in Table~\ref{tab:sct}. + +\begin{table}[htbp] +\centering +\caption{Specific command type keywords.} \label{tab:sct} +\begin{tabular}{|l|c|} \hline +Keyword & \LaTeX\ command form \\ \hline +\keyword{BEGIN\_LIST\_ENV} & \verb|\begin{env}| for \verb|\item| lists \\ +\keyword{BEGIN\_PICTURE\_CC} & \verb|\begin{pic}()()| \\ +\keyword{END\_LIST\_ENV} & \verb|\end{env}| for \verb|\item| lists \\ +\keyword{END\_PICTURE} & \verb|\end{pic}| \\ +\keyword{PICTURE\_CCPP} & \verb|\pic()(){}{}| \\ +\keyword{PICTURE\_CO} & \verb|\pic()[]| \\ +\keyword{PICTURE\_COP} & \verb|\pic()[]{}| \\ +\keyword{PICTURE\_CP} & \verb|\pic(){}| \\ +\keyword{PICTURE\_OCC} & \verb|\pic[]()()| \\ +\keyword{PICTURE\_OCCC} & \verb|\pic[]()()()| \\ +\keyword{PICTURE\_OCO} & \verb|\pic[]()[]| \\ +\keyword{PICTURE\_PCOP} & \verb|\pic{}()[]{}| \\ +\keyword{SECTIONING} & \verb|\command| for a document section \\ +\keyword{COMMAND\_OOP} & \verb|\com[][]{}| \\ +\keyword{COMMAND\_OOOPP} & \verb|\com[][][]{}{}| \\ +\keyword{COMMAND\_OPO} & \verb|\com[]{}[]| \\ +\keyword{COMMAND\_POOOP} & \verb|\com{}[][][]{}| \\ +\keyword{COMMAND\_POOP} & \verb|\com{}[][]{}| \\ +\keyword{COMMAND\_POOPP} & \verb|\com{}[][]{}{}| \\ \hline +\end{tabular} +\end{table} + + A \keyword{BEGIN\_LIST\_ENV} specification should include at least a +\keyword{START\_ITEM=} command. The other \keyword{\_ITEM\_} commands +are optional. +Other commands follow the rules for the general command types. + + The potential commands for the \keyword{\_PICTURE\_} commands are the same as +for the general commands, with the exception that commands related to optional +argument processing are not available for use. + + A \keyword{SECTIONING} command specification must include a +\keyword{SECTIONING\_LEVEL=} +command. Other commands follow the rules for the general command types. + + The keywords for the special command types are given in +Table~\ref{tab:specct}. + +\begin{table}[htbp] +\centering +\caption{Special command type keywords.} \label{tab:specct} +\begin{tabular}{|l|c|} \hline +Keyword & \LaTeX\ command form \\ \hline +\keyword{SPECIAL} & reserved for possible future use \\ +\keyword{SPECIAL\_BEGIN\_ENV} & \verb|\begin{env}| except for \verb|\item| lists \\ +\keyword{SPECIAL\_BEGIN\_LIST} & \verb|\begin{env}| for \verb|\item| lists \\ +\keyword{SPECIAL\_COMMAND} & \verb|\command| \\ +\keyword{SPECIAL\_END\_ENV} & \verb|\end{env}| except for \verb|\item| lists \\ +\keyword{SPECIAL\_END\_LIST} & \verb|\end{env}| for \verb|\item| lists \\ +\keyword{SPECIAL\_SECTIONING} & \verb|\command| for a document section \\ \hline +\end{tabular} +\end{table} + + Apart from the general restrictions on the allowed commands within +a specification, there are no restrictions on the commands that can be +included within the specification of a \keyword{SPECIAL\_} command. It is up +to the creator of the special to decide what is appropriate. However, +each \keyword{SPECIAL\_} specification must include the command +\begin{verbatim} +SPECIAL_TOKEN= N +\end{verbatim} +where \keytext{N} is an integer number (with $10000 \leq N \leq 32767$ for a +grammar special, or $N > 50000$ for a code special) that has been specified +within \lx\ as being identified with the grammar and actions corresponding to the +value of the \keyword{NAME=} command for the \keyword{SPECIAL\_}. + +\subsection{Tag specification commands} + +\subsubsection{Arguments} + + The commands relating to the specification of \LaTeX\ command arguments +are given in Table~\ref{tab:param}. + +\begin{table}[htbp] +\centering +\caption{Argument commands.} \label{tab:param} +\begin{tabular}{|l|c|} \hline +Command & Value \\ \hline +\keyword{OPT\_PARAM=} & \keyword{FIRST} or \keyword{LAST} \\ +\keyword{REQPARAMS=} & Integer. The number of required arguments \\ \hline +\end{tabular} +\end{table} + + The \keyword{OPT\_PARAM=} command specifies that the \LaTeX\ command takes one +optional argument and it is the \keyword{FIRST} or \keyword{LAST} in the argument +list. + + The \keyword{REQPARAMS=} command specifies that the \LaTeX\ command has +\verb|Integer| number of required arguments. \verb|Integer| must be between +one and nine\footnote{Or eight if \keyword{OPT\_PARAM=} is specified.} inclusive. + + Absence of these commands implies that the relevant \LaTeX\ command has +no arguments of the unspecified kind. + +\subsubsection{Tag actions} + + The commands for specifying the tag actions are summarized in +Table~\ref{tab:tag}. +The \keyword{\_ITEM\_} commands can only be used within a +\keyword{BEGIN\_LIST\_ENV} or a \keyword{SPECIAL\_} command specification. + +\begin{table}[htbp] +\centering +\caption{Tag commands.} \label{tab:tag} +\begin{tabular}{|l|c|} \hline +Command & Application \\ \hline +\keyword{END\_ITEM=} & actions after \verb|\item| text \\ +\keyword{END\_ITEM\_PARAM=} & actions after \verb|\item| optional argument \\ +\keyword{END\_OPT=} & actions after optional argument \\ +\keyword{END\_TAG=} & actions after all arguments processed \\ +\keyword{END\_TAG\_n=} & actions after n'th required argument \\ +\keyword{START\_ITEM=} & actions before \verb|\item| \\ +\keyword{START\_ITEM\_PARAM=} & actions before \verb|\item| optional argument \\ +\keyword{START\_OPT=} & actions before optional argument \\ +\keyword{START\_TAG=} & actions at start of command \\ +\keyword{START\_TAG\_n=} & actions before n'th required argument \\ \hline +\end{tabular} +\end{table} + + + + Each of these commands can specify a list of actions to be performed; +typically this is just to print a text string. A string is any set of +characters enclosed in double +quote marks. The string can include any special printing characters. The +text string starts immediately after the first double quote and ends immediately +before the last double quote. The string cannot include a physical linebreak +within the \ctab\ file. If the first action is to print a string then the +string may be placed on the same line as the keyword. + + The actions are listed one per line and are performed in the order they +are listed. Table~\ref{tab:tagaction} lists the action commands. + +\begin{table}[htbp] +\centering +\caption{Tag actions.} \label{tab:tagaction} +\begin{tabular}{|l|l|l|} \hline +Keyword & Value & Application \\ \hline +\keyword{STRING:} & text string & Print the string \\ +\keyword{SOURCE:} & \keyword{BUFFER} \keytext{num} & Print the contents of + buffer number \keytext{num} \\ +\keyword{SOURCE:} & \keyword{FILE} \keytext{name} & Print the contents of file +\keytext{name} \\ +\keyword{SOURCE:} & \keyword{SYSBUF} & Print the contents of the system buffer \\ +\keyword{RESET\_BUFFER:} & \keytext{num} & Reset the buffer \keytext{num} \\ +\keyword{RESET\_FILE:} & \keytext{name} & Reset the file \keytext{name} \\ +\keyword{RESET\_SYSBUF:} & & Reset the system buffer \\ +\keyword{SWITCH\_TO\_BUFFER:} & \keytext{num} & Print to buffer number \keytext{num} \\ +\keyword{SWITCH\_TO\_FILE:} & \keytext{name} & Print to file called \keytext{name} \\ +\keyword{SWITCH\_TO\_SYSBUF:} & & Print to the system buffer \\ +\keyword{SWITCH\_BACK:} & & Reset the print mode \\ +\keyword{SET\_MODE:} & \keytext{name} & Set the mode to \keytext{name} \\ +\keyword{RESET\_MODE:} & & Reset the mode to its prior value \\ +\keyword{CODE:} & & Start of a set of \ExpressA{} statements \\ \hline +\end{tabular} +\end{table} + +\subsubsection{Print control} + + The print control commands are summarized in Table~\ref{tab:print}. +These are used to set the print mode at the start and end of a command, and for +each argument. The exception is the \keyword{PRINT\_CONTROL=} command +which can only be used within an \keyword{OTHER\_} command type +specification, and which is the only print control that can be +specified for the \keyword{OTHER\_} commands. + +\begin{table}[htbp] +\centering +\caption{Print control commands.} \label{tab:print} +\begin{tabular}{|l|l|} \hline +Command & Application \\ \hline +\keyword{PRINT\_CONTROL=} & printing of \keyword{OTHER\_} commands \\ +\keyword{PC\_AT\_START=} & set printing at start of command \\ +\keyword{PC\_AT\_END=} & set printing at end of command \\ +\keyword{PRINT\_OPT=} & printing of optional argument \\ +\keyword{PRINT\_Pn=} & printing of n'th required argument \\ \hline +\end{tabular} +\end{table} + +The values that these commands may take are given in Table~\ref{tab:pcvalues}. +These direct where any print output is to be directed. The default is to +send all output the the file named as the output on the command line when +starting \lx. + +\begin{table}[htbp] +\centering +\caption{Print control values.} \label{tab:pcvalues} +\begin{tabular}{|l|l|} \hline +Value & Application \\ \hline +\keyword{NO\_PRINT} & Do not print at all \\ +\keyword{TO\_SYSBUF} & Print to the system buffer \\ +\keyword{TO\_BUFFER} \keytext{num} & Print to buffer number \keytext{num} \\ +\keyword{TO\_FILE} \keytext{name} & Print to file called \keytext{name} \\ +\keyword{NO\_OP} & Do not do any processing \\ +\keyword{RESET} & Reset the print mode \\ \hline +\end{tabular} +\end{table} + + \keyword{NO\_PRINT} and \keyword{NO\_OP} both produce no printed output. +However, in the \keyword{NO\_OP} case the lexer handles all the processing, +and effectively just ignores the source document text. In the \keyword{NO\_PRINT} +case, the source text is processed as normal, but the printing is directed +to a black hole. + + + +\subsubsection{Sectioning} + + + \keyword{SECTIONING} command specifications require a +\keyword{SECTIONING\_LEVEL=} +command. The values that this can take are listed in Table~\ref{tab:level}. + +\begin{table}[htbp] +\centering +\caption{Sectioning level values.} \label{tab:level} +\begin{tabular}{|l|l|} \hline +Value & Application \\ \hline +\keyword{PART} & sectioning equivalent to \verb|\part| \\ +\keyword{CHAPTER} & sectioning equivalent to \verb|\chapter| \\ +\keyword{SECT} & sectioning equivalent to \verb|\section| \\ +\keyword{SUBSECT} & sectioning equivalent to \verb|\subsection| \\ +\keyword{SUBSUBSECT} & sectioning equivalent to \verb|\subsubsection| \\ +\keyword{PARA} & sectioning equivalent to \verb|\paragraph| \\ +\keyword{SUBPARA} & sectioning equivalent to \verb|\subprargraph| \\ \hline +\end{tabular} +\end{table} + + A sectioning command specification uses the \keyword{END\_TAG=} text tag differently +from its use by any other specification. In this case, the tag is printed at +the closure of the text forming the body of the section of the document. A +document section is considered to be closed when it is followed by a higher +level sectioning command. The values in Table~\ref{tab:level} are listed +in decreasing level. That is, a section at level \keyword{CHAPTER} is at a higher +level than a section at level \keyword{PARA}. + +\begin{description} +\item[NOTE] For the use of writers of \keyword{SPECIAL\_} command specifications, +\keyword{SECTIONING\_LEVEL=} can be given some additional values. These are +\keyword{PARTm2} and \keyword{PARTm1} for levels respectively two and one higher +than \keyword{PART}, and \keyword{SUBPARAp1} and \keyword{SUBPARAp2} for levels respectively +one and two lower than \keyword{SUBPARA}. +\end{description} + +\section{System installation} \label{sec:install} + + This section describes how to install the \lx\ program and some of the +internal size limits within \lx. + + + The basic \lx\ system requires the following source files: +\begin{description} +\item[\file{l2x.l}] the lexer source. +\item[\file{l2x.y}] the parser source. +\item[\file{l2xlib.c}, \file{l2xlib.h}] main program and support functions. +\item[\file{l2xlibtc.h}] header file containing keywords and their + representations as strings. +\item[\file{l2xcom.h}] header file for all system components + (except for getopt, srchenv and the interpreter). +\item[\file{l2xacts.c}, \file{l2xacts.h}] standard action functions. +\item[\file{l2xusrlb.c}, \file{l2xusrlb.h}] special actions and user-defined functions. +\item[\file{strtypes.h}] header file with some type definitions. +\item[\file{getopt.c}, \file{getopt.h}] functions for handling command line + options~\cite[Chapter 6]{LIBES93}. +\item[\file{srchenv.c}, \file{srchenv.h}] functions for searching directories + for files~\cite[page 747]{HOLUB90}. +\end{description} + + The \ExpressA{} interpreter also requires the following files: +\begin{description} +\item[\file{l2xistup.c}] the interface between the main part of \lx{} + and the interpreter. +\item[\file{l2xicmon.h}] header file for the interface. +\item[\file{l2xirtne.c}, \file{l2xistd.c}, \file{l2xidecl.c}, + \file{l2xistmt.c}, \file{l2xiexpr.c}] the files that contain the code for + parsing \ExpressA. Respectively they deal with functions and procedures, + the built-in functions, declarations, statements, and expressions. +\item[\file{l2xiprse.h}] header file for parsing. +\item[\file{l2xixutl.c}, \file{l2xiexec.h}] utility routines + supporting the execution module and + for managing the interpreter's stack. +\item[\file{l2xixstd.c}, \file{l2xixstm.c}, \file{l2xixxpr.c}] functions for + executing the \ExpressA{} built in functions, statements and expressions. +\item[\file{l2xirexp.c}, \file{l2xirexpr.h}] general functions for processing + and executing regular expressions. +\item[\file{listsetc.c}, \file{listsetc.h}] general functions for processing + lists. +\item[\file{l2xiscan.c}, \file{l2xiscan.h}] lexing routines for the interpreter. +\item[\file{l2xisymt.c}, \file{l2xisymt.h}] routines for managing the + interpreter's symbol tables. +\item[\file{l2xidbug.c}] the source level debugger. +\item[\file{l2xierr.c}, \file{l2xierr.h}] \ExpressA{} language error handling + and diagnostic output for the user. +\item[\file{l2xiidbg.c}, \file{l2xiidbg.h}, \file{l2xisdcl.c}] diagnostics + for a developer of the interpreter. +\item[\file{licomsym.h}] general header file for the interpreter modules. +\item[\file{l2xidftc.h}, \file{l2xiertc.h}, \file{l2xisctc.h}, \file{l2xisftc.h}] +header files containing keywords and their representations as strings. +\end{description} + +The following files may be useful: +\begin{description} +\item[\file{man}] the manpage +\item[\file{printct.c}] a program to print and update \ctab{} files; +\item[\file{ltx2html.sty}] a \LaTeX{} package file to assist in retagging +a \LaTeX{} document to an HTML document. +\end{description} + + Essentially, installing \lx\ consists of processing the file \file{l2x.l} +through a lexer generator, processing the file \file{l2x.y} through a +parser generator, and then compiling the results together with the other +supplied source files. + + The lexer source file \file{l2x.l} and the parser source file +\file{l2x.y} have to be processed by flex (or equivalent) and bison +(or equivalent) respectively to generate C code. This code, together +with the code in the other source files must then be compiled +and linked to form the executable. + + The executable must then, after suitable testing, be moved to +its final place in your system and the manpage (file \file{man}) +also copied to its final position in your directory structure. + + Included in the \lx{} distribution are several \ctab{} files. One is +\file{detex.ct} which provides an example of commands for de-\TeX ing +a document.\footnote{You may wish to try using \file{detex.ct} on the +\LaTeX\ source of this document to see what the effect is. This can +also serve as a check on the system installation.} +Another is \file{remcom.ct} +which provides an example of commands to remove comments from a +\LaTeX\ document. The \ctab{} file \file{bye.ct} replaces a \LaTeX{} +document by "Goodbye document". +Another is \file{ltx2x.ct} which does nothing except try and include +another file named \file{ZiLcH}, which presumably is not on anyone's +system. Running \lx\ with this file will prompt for another name of a +file if it cannot find \file{ZiLcH}; enter an existing file (like \file{detex.ct}) +at the prompt.\footnote{This is one way of setting up \lx\ for interactive +specification of the desired \ctab\ file(s).} + + The \ctab{} file \file{l2h.ct} has proven to be adequate for converting +the \LaTeX{} source of this manual, and other \LaTeX{} documents without +pictures and only limited mathematics, into an ASCII file with HTML +tags instead. + + The file \file{fun.ct} contains some test code for the \ExpressA{} +interpreter. The contents are similar to the example shown at the end of +section~\ref{sec:expressa}. + +The \file{l2xusrlb} files are skeletons. The system does include +the functions and parser constructs for the \verb|\GRAMMspecial| and +\verb|\CODEspecial| commands used as examples previously. The last two +entries in \file{remcom.ct} are the specification of these, and the +implementation is as described previously. + +\subsection{Command table printing} + + The grammar of the \ctab{} has been changed slightly since the +initial release of \lx. The utility C program in \file{printct.c} may be used to: +\begin{itemize} +\item Pretty-print a \ctab; +\item Convert an original \ctab{} to one that conforms to the new grammar. +\end{itemize} + + The syntax for running \file{printct} is: +\begin{verbatim} +printct [-D dir_cat_char] [-P path_seperators] [-f table_file] [-t] +\end{verbatim} +where elements in square brackets are options. These options are identical +to the corresponding ones for \lx{} and are as follows: +\begin{description} +\item[{\tt -f}] By default, \file{printct} reads the \ctab\ from a file called + \file{ltx2x.ct}. If the required \ctab\ is in a file with another name this + option is used to change from the default file. For example, +\begin{verbatim} +> printct +\end{verbatim} +reads a \ctab\ from \verb|ltx2x.ct|, while +\begin{verbatim} +> printct -f detex.ct +\end{verbatim} +reads a \ctab\ from file \verb|detex.ct|. + +\item[{\tt -t}] This generates some diagnostics related to the processing of + the \ctab\ file. + +\item[{\tt -D}] The value of this option is the character that the operating system + uses to catenate directory names to form a path (see~\ref{sec:search}). + The default value is a + slash (i.e. \verb|/|). The default could be changed to a backslash, for example, + by \verb|-D \|. + +\item[{\tt -P}] The environment variable (see~\ref{sec:search}) + contains a list of directories (also known + as path names). In the operating system that I use, these are separated by + the colon (\verb|:|) character which, together with the semi-colon + and space characters, form + the \lx\ default separators. The path separator characters can be changed + with this option. + For example, \verb|-P :| will make the separators be a colon + or a space (space is automatically included in the separator list). +\end{description} + + \file{printct} only reads a single \ctab{} file and outputs the +pretty-printed and updated version to file \file{printct.lis}. It performs +a very limited amount of error checking and writes error messages and +statistics to the file \file{printct.err}. + + +\subsection{A {\tt make} file} + + + Here is a UNIX \file{make} file~\cite{ORAM91} for the \lx\ system. + +\begin{code} +\begin{verbatim} +# makefile for program ltx2x --- LaTeX to X autotagger +# +##################### Change the following for your setup +# The compiler +CC = cc + +# We use flex (or equivalent, but not lex) to generate the lexer +LEX = flex +# and the options +LEXFLAGS = -v + +# We use bison (or equivalent) to generate the parser +YACC = bison +# and the options +YACCFLAGS = -y -d -v + +# Libraries to be used +LIBS = -ly -ll -lm + +# The root directory for the installation (e.g., /usr/local ) +ROOTDIR = /proj/ltx/teTeX033 + +# Where to place the running code (e.g. /usr/local/bin ) +BINDIR = ${ROOTDIR}/bin + +# Where to place the manpage (e.g., /usr/local/man/man1 ) +MANEXT = 1 +MANDIR = ${ROOTDIR}/man/man${MANEXT} + +# Just in case you want to change the name of the binary +# (and then you should also change the man page and documentation). +# So, do not change this. +PROG = ltx2x + +# Where to place the user documentation (e.g., /usr/local/doc/ltx2x ) +DOCDIR = ${ROOTDIR}/doc/${PROG} + +# Where to place the example command tables (e.g., /usr/local/lib/config/ltx2x ) +CTDIR = ${ROOTDIR}/lib/config/${PROG} + +# The file copy command (copy but do not delete original) +COPY = cp + +# The file move command (move and delete original) +MOVE = mv + +# The file delete command +DELETE = rm + +# The make directory (hierarchy) command +MAKEDIR = mkdirhier + +# The stream editor command +SED = sed + +# Command to write to the terminal (stdout) +ECHO = echo + +################### You should not have to change anything after this + +# The source modules +L2XSRCS = l2xytab.c l2xlexyy.c l2xlib.c l2xacts.c l2xusrlb.c +getopt.c srchenv.c + +INTSRCS = l2xirtne.c l2xistd.c l2xidecl.c l2xistmt.c l2xiexpr.c +l2xiscan.c l2xisymt.c l2xierr.c l2xiidbg.c l2xistup.c l2xistm.c +l2xixxpr.c l2xixstd.c l2xidbug.c l2xisdcl.c l2xirexp.c listsetc.c + +# The object modules +L2XOBJS = l2xytab.o l2xlexyy.o l2xlib.o l2xacts.o l2xusrlb.o + getopt.o srchenv.o + +INTSRCS = l2xirtne.o l2xistd.o l2xidecl.o l2xistmt.o l2xiexpr.o +l2xiscan.o l2xisymt.o l2xierr.o l2xiidbg.o l2xistup.o l2xistm.o +l2xixxpr.o l2xixstd.o l2xidbug.o l2xisdcl.o l2xirexp.o listsetc.o + +OBJS = ${L2XOBJS} ${INTOBJS} + +# Link object code together into PROG +ltx2x : ${OBJS} + ${CC} -o ${PROG} ${OBJS} ${LIBS} + +# Compile C source code into object code +getopt.o : getopt.c getopt.h + ${CC} -c getopt.c +l2xytab.o : l2xytab.c l2xlib.h l2xusrlb.h l2xacts.h strtypes.h l2xcom.h + ${CC} -c l2xytab.c +l2xlexyy.o : l2xlexyy.c l2xytab.h l2xlib.h l2xusrlb.h l2xcom.h + ${CC} -c l2xlexyy.c +l2xlib.o : l2xlib.c getopt.h l2xytab.h strtypes.h l2xcom.h + ${CC} -c l2xlib.c +l2xusrlb.o : l2xusrlb.c l2xlib.h l2xytab.h strtypes.h l2xcom.h + ${CC} -c l2xusrlb.c +l2xacts.o : l2xacts.c l2xusrlb.h l2xlib.h l2xytab.h strtypes.h l2xcom.h + ${CC} -c l2xacts.c +srchenv.o : srchenv.c srchenv.h + ${CC} -c srchenv.c + +# Generate C code for parsing +l2xytab.c l2xytab.h: l2x.y + @ ${ECHO} "Expect 10 shift/reduce conflicts to be reported" + ${YACC} ${YACCFLAGS} l2x.y + ${MOVE} y.tab.c l2xytab.c + ${MOVE} y.tab.h l2xytab.h + +# Generate C code for lexing +l2xlexyy.c : l2x.l + ${LEX} ${LEXFLAGS} l2x.l + ${MOVE} lex.yy.c l2xlexyy.c + +# the interpreter modules + +# compiler flags for analyze and execute modules +ANLFLAG = -Danalyze +RUNFLAG = -Dtrace + +# interpreter header files +SOMEH = l2xicmon.h l2xierr.h l2xiscan.h l2xisymt.h licomsym.h l2xiidbg.h +MOSTH = ${SOMEH} l2xiprse.h +ALLH = ${MOSTH} l2xicpr.h l2xiexec.h + +# interpreter interface + +l2xistup.o : l2xistup.c ${ALLH} + ${CC} -c ${ANLFLAG} ${RUNFLAG} l2xistup.c + +# the parser module + +l2xirtne.o : l2xirtne.c ${ALLH} + ${CC} -c ${ANLFLAG} l2xirtne.c + +l2xistd.o : l2xistd.c ${MOSTH} + ${CC} -c ${ANLFLAG} ${RUNFLAG} l2xistup.c + +l2xistup.o : l2xistup.c ${ALLH} + ${CC} -c l2xistd.c + +l2xidecl.o : l2xidecl.c ${MOSTH} l2xicpr.h + ${CC} -c ${ANLFLAG} l2xisdecl.c + +l2xistmt.o : l2xistmt.c ${ALLH} + ${CC} -c ${ANLFLAG} l2xistmt.c + +l2xiexpr.o : l2xiexpr.c ${MOSTH} l2xicpr.h + ${CC} -c ${ANLFLAG} l2xiexpr.c + +# the scanner module + +l2xiscan.o : l2xiscan.c ${SOMEH} l2xicpr.h + ${CC} -c ${ANLFLAG} l2xiscan.c + +# symbol table module + +l2xisymt.o : l2xisymt.c l2xicmon.h l2xierr.h l2xisymt.h licomsym.h l2xiidbg.h + ${CC} -c l2xisymt.c + +# executor module + +l2xixutl.o : l2xixutl.c ${MOSTH} l2xiexec.h listsetc.h + ${CC} -c ${RUNFLAG} l2xixutl.c + +l2xixstm.o : l2xixstm.c ${MOSTH} l2xiexec.h listsetc.h + ${CC} -c ${RUNFLAG} l2xixstm.c + +l2xixxpr.o : l2xixxpr.c ${MOSTH} l2xiexec.h listsetc.h + ${CC} -c ${RUNFLAG} l2xixxpr.c + +l2xixstd.o : l2xixstd.c ${MOSTH} l2xiexec.h listsetc.h + ${CC} -c ${RUNFLAG} l2xixstd.c + +l2xidbug.o : l2xidbug.c ${SOMEH} l2xiexec.h listsetc.h + ${CC} -c ${RUNFLAG} l2xidbug.c + +# error and miscellaneous + +l2xisdcl.o : l2xisdcl.c ${SOMEH} + ${CC} -c ${ANLFLAG} ${RUNFLAG} l2xisdcl.c + +l2xiidbg.o : l2xiidbg.c ${SOMEH} l2xiexec.h + ${CC} -c l2xiidbg.c + +l2xirexp.o : l2xirexp.c l2xirexp.h + ${CC} -c l2xirexp.c + +listsetc.o : listsetc.c listsetc.h + ${CC} -c listsetc.c + +# only call make install if BINDIR has been set +install : ltx2x + ${MAKEDIR} ${BINDIR} + ${MOVE} ${PROG} ${BINDIR} + +# Edit the file man to replace DOCUMENTDIR by the actual directory +# where the user manual is to be placed, and CTDIR by the location +# of the example command table files. +# Then copy the manpage to the proper place +manpage : + ${SED} 's!DOCUMENTDIR!${DOCDIR}!; s!CTDIR!${CTDIR}!' man > tman + ${MAKEDIR} ${MANDIR} + ${COPY} tman ${MANDIR}/${PROG}.${MANEXT} + +# Copy the user manuals to the proper place +doc : + ${MAKEDIR} ${DOCDIR} + ${COPY} ltx2x.tex ${DOCDIR}/${PROG}.tex + ${COPY} ltx2x.ps ${DOCDIR}/${PROG}.ps + ${COPY} ltx2x.txt ${DOCDIR}/${PROG}.txt + ${COPY} ltx2x.html ${DOCDIR}/${PROG}.html + +# Copy the example command tables to their final location +ctables : + ${MAKEDIR} ${CTDIR} + ${COPY} ltx2x.ct ${CTDIR}/ltx2x.ct + ${COPY} detex.ct ${CTDIR}/detex.ct + ${COPY} remcom.ct ${CTDIR}/remcom.ct + ${COPY} l2h.ct ${CTDIR}/l2h.ct + ${COPY} bye.ct ${CTDIR}/bye.ct + ${COPY} fun.ct ${CTDIR}/fun.ct + +# Do almost everything except clean up +all : ltx2x install manpage doc ctables + +# call make clean to remove the object files, info from YACC, +# and the edited version of the manpage +clean : + ${DELETE} *.o + ${DELETE} y.output + ${DELETE} tman + +# Compile the command table printer +printct : printct.o getopt.o srchenv.o + ${CC} -o printct printct.o getopt.o srchenv.o + +printct.o : printct.c getopt.h strtypes.h l2xcom.h + ${CC} -c printct.c +\end{verbatim} +\end{code} + + If you use the above makefile then the first part should be edited +to reflect your system's configuration. You could do \verb|make all| +which should do everything for you, except the cleaning up. +A more conservative approach is recommended. First +just do \verb|make| which will generate the executable. This can then be +tested. When all is well do \verb|make install| and \verb|make manpage| +which will put the executable and the manpage into their final positions. +Finally, \verb|make clean| will remove the intermediate files generated +during the build process. + + The above \file{make} file uses flex as the lexer generator. You can use your +favorite one instead but it must, unlike lex, support exclusive start states. +Also, bison is used above as the parser generator. Again, you can use your +favorite one. As far as I am aware, there is nothing remarkable about the +grammar, except that during early development I exceeded the size limits +of yacc. The grammar has been simplified since then, so this may no longer +be a problem. \\ +NOTE: If bison is used it reports that there are 10 shift/reduce +conflicts. It appears that these can be safely ignored. + + One compilation problem has been noted by Uwe +Sassenberg\footnote{\texttt{<sassen@hal1.physik.uni-dortmund.de>}} +on AIX~3.2 and +IRIX~5.3 systems, but I could not reproduce it on a SunOS 4.1.3 system. This +is when the main procedure of \lx{} is processing the optional command +line arguments. For some reason it had difficulties with the C +\verb|EOF|. The symptom was that the program compiled but when it was +run +it sat there absorbing CPU cycles and doing nothing as it had got into +an infinite \verb|while| loop. The cure was to insert +the following line of code in file \file{l2xlib.c}: +\begin{verbatim} +main(argc,argv) +... + /* get command line optional parameters */ + opterr = 1; /* getopt prints errors if opterr is 1 */ + while (EOF != (optchar = + getopt(argc,argv, "l:ty:f:cp:wE:P:D:"))) { +/* insert this line of code: if (optchar == 255) break; end insert */ + switch(optchar) { +... +\end{verbatim} +This code line which you may need to insert is supplied as a comment in +the distributed source. + +\subsection{Limits and errors} + + The \lx\ system has some built-in limits which are defined in \file{l2xlib.c}. +The following is a listing of the relevant sizes. + +\begin{description} +\item[\keyword{CLAUSE\_STACK\_SIZE}] The maximum nesting depth of +document sectioning. This is set somewhat larger than the number of +standard \LaTeX\ sectioning command types. +(Default~10) + +\item[\keyword{EVERY\_N\_LINES}] Controls the frequency of printing +processed line numbers to the terminal. +(Default~100) + +\item[\keyword{LIST\_STACK\_SIZE}] The maximum nesting depth of list +environments. This is set somewhat larger than the standard \LaTeX\ nesting depth. +(Default~10) + +\item[\keyword{MAX\_BUFFER}] The maximum number of characters that can be held +in the system buffer, and also the maximum number of characters in a +pretty-printed output line. +(Default~2000) + +\item[\keyword{MAX\_CT\_STACK}] The maximum nesting depth for included +\ctab\ files. +(Default~20) + +\item[\keyword{MAX\_ERRORS}] The maximum number of non-fatal errors +discovered in \ctab\ processing or in source file processing before +\lx\ quits. +(Default~10) + +\item[\keyword{MAX\_LINE}] The maximum number of characters in a line of +a \LaTeX\ source file. +(Default~2000) + +\item[\keyword{MAX\_PRINT\_STACK}] The maximum nesting depth for print +control commands. +(Default~100) + +\item[\keyword{MAX\_TABLE\_ENTRIES}] The maximum number of +\keyword{TYPE} specifications in a \ctab\ (including the built in +type specifications). +(Default~1000) + +\item[\keyword{MAX\_TABLE\_LINE}] The maximum number of characters in a line in +a \ctab\ file. +(Default~254) + +\item[\keyword{MAX\_USER\_BUFFS}] The maximum number of user buffers. +(Default 20) + +\item[\keyword{MAX\_UBUFF\_LEN}] The maximum number of characters that can be +stored in a user buffer. +(Default 510) + +\item[\keyword{MAX\_USER\_FILES}] The maximum number of user files. +(Default 16) +\end{description} + + \lx{} prints out a summary of the program statistices at the end of +the \file{ltx2x.err} file. + If the limits are not suitable for your purposes, then they may be changed and +the system rebuilt. + + \lx\ can produce a variety of error and warning messages, for example +when any of the above limits are exceeded. Some of the messages are related +to command table processing, while others are related to \LaTeX\ document +processing. Both these kinds of messages are targeted to the normal +end user. There is another set of messages that are aimed at the implementor +of new \keyword{SPECIAL\_} commands. An implementor may also find some of the +debugging options useful if things really fall apart. + + +\subsection{Availability} + + Source code and documentation for \lx\ is available from the +NIST SOLIS (SC4 On-Line Information Service) system~\cite{RINAUDOT94} +in directory \\ +\file{/subject/sc4/editing/latex/programs/ltx2x}. \\ + SOLIS can be accessed by: +\begin{itemize} +\item Anonymous ftp to \file{ftp.cme.nist.gov} (\texttt{cd} to \file{/pub/subject/sc4...}) +\item URL \url{http://www.nist.gov/sc4} +\end{itemize} + + Any comments should be directed to \texttt{apde@cme.nist.gov}. + +\subsubsection{Copyright} + + Development of this software was funded by the United States Government +and is not subject to copyright. It was developed by the +Manufacturing Systems Integration Division (MSID) of the +Manufacturing Engineering Laboratory (MEL) of the +National Institute of Standards and Technology (NIST). + +\subsubsection{Disclaimer} + + There is no warranty for the \lx\ software. If the \lx\ software +is modified by someone else and passed on, NIST requests that the software's +recipients be notified that what they have is not what NIST distributed. + +\begin{description} +\item[Policies] \mbox{} +\begin{enumerate} +\item Anyone may copy and distribute verbatim copies of the + source code as received in any medium. +\item Anyone may modify your copy or copies of the \lx\ source + code or any portion of it, and copy and distribute such + modifications provided that all modifications are clearly + associated with the entity that performs the modifications. +\end{enumerate} + +\item[NO WARRANTY] \mbox{} + + NIST PROVIDES ABSOLUTELY NO WARRANTY. THE \lx\ SOFTWARE IS +PROVIDED `AS IS' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE +RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. +SHOULD ANY PORTION OF THE \lx\ SOFTWARE PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + IN NO EVENT WILL NIST BE LIABLE FOR DAMAGES, INCLUDING ANY +LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE +(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED +INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF +THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY NIST) +THE PROGRAMS, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY +OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. +\end{description} + + +\section{A grammar for the \ctab} \label{sec:ctabgrammar} + +\subsection{Notation} + + The syntactical constructs used correspond to a derivative of +the Wirth Syntax Notation (WSN)~\cite{WIRTH77}. The semantics of the +enclosing braces are: +\begin{itemize} +\item curly braces `\texttt{\{ \}}' indicate xero or more repetitions; +\item square brackets `\texttt{[ ]}' indicate an optional element; +\item parenthesis `\texttt{( )}' indicates a group; +\item vertical bar `\texttt{|}' indicates that exactly one of the + terms in the expression shall be chosen. +\end{itemize} + + Here is the grammar for WSN defined in itself. +\begin{code} +\begin{verbatim} +syntax = { production } . +production = identifier '=' expression '.' . +expression = term { '|' term } . +term = factor { factor } . +factor = identifier | literal | group | option | repetition . +identifier = character { character } . +literal = '''' character { character } '''' . +group = '(' expression ')' . +option = '[' expression ']' . +repetition = '{' expression '}' . +\end{verbatim} +\end{code} + + We also use the following shorthand notation for particular characters: +\begin{itemize} +\item \verb|\c| --- any printable character +\item \verb|\n| --- the end of line character(s) +\item \verb|eof| --- the end of file character(s) +\end{itemize} + +\subsection{Grammar} + + First, the keywords. Note that these are case insensitive. +\begin{code} +\begin{verbatim} +AudibleAlertChar = 'AUDIBLE_ALERT_CHAR=' . +BackspaceChar = 'BACKSPACE_CHAR=' . +BeginDocument = 'BEGIN_DOCUMENT' . +BeginDollar = 'BEGIN_DOLAR' . +BeginEnv = 'BEGIN_ENV' . +BeginListEnv = 'BEGIN_LIST_ENV' . +BeginPictureCc = 'BEGIN_PICTURE_CC' . +BeginVenv = 'BEGIN_VENV' . +BeginVerb = 'BEGIN_VERB' . +BeginVerbatim = 'BEGIN_VERBATIM' . +Buffer = 'BUFFER' . +CarriageReturnChar = 'CARRIAGE_RETURN_CHAR=' . +Chapter = 'CHAPTER' . +CharCommand = 'CHAR_COMMAND' . +Command = 'COMMAND' . +CommandOop = 'COMMAND_OOP' . +CommandOoopp = 'COMMAND_OOOPP' . +CommandOpo = 'COMMAND_OPO' . +CommandPooop = 'COMMAND_POOOP' . +CommandPoop = 'COMMAND_POOP' . +CommandPoopp = 'COMMAND_POOPP' . +Comment = 'C=' . +EndCtfile = 'END_CTFILE=' . +EndDocument = 'END_DOCUMENT' . +EndDollar = 'END_DOLAR' . +EndEnv = 'END_ENV' . +EndItem = 'END_ITEM=' . +EndItemParam = 'END_ITEM_PARAM=' . +EndListEnv = 'END_LIST_ENV' . +EndMode = 'END_MODE' . +EndOpt = 'END_OPT=' . +EndPicture = 'END_PICTURE' . +EndTag = 'END_TAG=' . +EndTag1 = 'END_TAG_1=' . +EndTag2 = 'END_TAG_2=' . +EndTag3 = 'END_TAG_3=' . +EndTag4 = 'END_TAG_4=' . +EndTag5 = 'END_TAG_5=' . +EndTag6 = 'END_TAG_6=' . +EndTag7 = 'END_TAG_7=' . +EndTag8 = 'END_TAG_8=' . +EndTag9 = 'END_TAG_9=' . +EndType = 'END_TYPE' . +EndVenv = 'END_VENV' . +EndVerb = 'END_VERB' . +EndVerbatim = 'END_VERBATIM' . +EscapeChar = 'ESCAPE_CHAR=' . +File = 'FILE' . +First = 'FIRST' . +FormfeedChar = 'FORMFEED_CHAR=' . +HexChar = 'HEX_CHAR=' . +HorizontalTabChar = 'HORIZONTAL_TAB_CHAR=' . +Include = 'INCLUDE=' . +InMode = 'IN_MODE=' . +Last = 'LAST' . +Lbrace = 'LBRACE' . +Name = 'NAME=' . +NewlineChar = 'NEWLINE_CHAR=' . +NoOp = 'NO_OP' . +NoPrint = 'NO_PRINT' . +OptParam = 'OPT_PARAM=' . +OtherBegin = 'OTHER_BEGIN' . +OtherCommand = 'OTHER_COMMAND' . +OtherEnd = 'OTHER_END' . +Para = 'PARA' . +Paragraph = 'PARAGRAPH' . +Part = 'PART' . +Partm1 = 'PARTm1' . +Partm2 = 'PARTm2' . +PcAtEnd = 'PC_AT_END=' . +PcAtStart = 'PC_AT_START=' . +PictureCcpp = 'PICTURE_CCPP' . +PictureCo = 'PICTURE_CO' . +PictureCop = 'PICTURE_COP' . +PictureCp = 'PICTURE_CP' . +PictureOcc = 'PICTURE_OCC' . +PictureOccc = 'PICTURE_OCCC' . +PictureOco = 'PICTURE_OCO' . +PicturePcop = 'PICTURE_PCOP' . +PrintControl = 'PRINT_CONTROL=' . +PrintP1 = 'PRINT_P1=' . +PrintP2 = 'PRINT_P2=' . +PrintP3 = 'PRINT_P3=' . +PrintP4 = 'PRINT_P4=' . +PrintP5 = 'PRINT_P5=' . +PrintP6 = 'PRINT_P6=' . +PrintP7 = 'PRINT_P7=' . +PrintP8 = 'PRINT_P8=' . +PrintP9 = 'PRINT_P9=' . +PrintOpt = 'PRINT_OPT=' . +Rbrace = 'RBRACE' . +Reqparams = 'REQPARAMS=' . +Reset = 'RESET' . +ResetBuffer = 'RESET_BUFFER:' . +ResetMode = 'RESET_MODE:' . +Sect = 'SECT' . +Sectioning = 'SECTIONING' . +SectioningLevel = 'SECTIONING_LEVEL=' . +SetMode = 'SET_MODE:' . +SlashSpace = 'SLASH_SPACE' . +Source = 'SOURCE:' . +Special = 'SPECIAL' . +SpecialBeginEnv = 'SPECIAL_BEGIN_ENV' . +SpecialBeginList = 'SPECIAL_BEGIN_LIST' . +SpecialCommand = 'SPECIAL_COMMAND' . +SpecialEndEnv = 'SPECIAL_END_ENV' . +SpecialEndList = 'SPECIAL_END_LIST' . +SpecialSectioning = 'SPECIAL_SECTIONING' . +StartItem = 'START_ITEM=' . +StartItemParam = 'START_ITEM_PARAM=' . +StartOpt = 'START_OPT=' . +StartTag = 'START_TAG=' . +StartTag1 = 'START_TAG_1=' . +StartTag2 = 'START_TAG_2=' . +StartTag3 = 'START_TAG_3=' . +StartTag4 = 'START_TAG_4=' . +StartTag5 = 'START_TAG_5=' . +StartTag6 = 'START_TAG_6=' . +StartTag7 = 'START_TAG_7=' . +StartTag8 = 'START_TAG_8=' . +StartTag9 = 'START_TAG_9=' . +String = 'STRING:' . +SubPara = 'SUBPARA' . +SubParap1 = 'SUBPARAp1' . +SubParap2 = 'SUBPARAp2' . +SubSect = 'SUBSECT' . +SubSubSect = 'SUBSUBSECT' . +SwitchBack = 'SWITCH_BACL: ' . +SwitchToBuffer = 'SWITCH_TO_BUFFER: ' . +SwitchToFile = 'SWITCH_TO_FILE: ' . +SwitchToSysbuf = 'SWITCH_TO_SYSBUF: ' . +Sysbuf = 'SYSBUF' . +TexChar = 'TEX_CHAR' . +ToBuffer = 'TO_BUFFER' . +ToFile = 'TO_FILE' . +ToSysbuf = 'TO_SYSBUF' . +Type = 'TYPE=' . +Vcommand = 'VCOMMAND' . +VerticalTabChar = 'VERTICAL_TAB_CHAR=' . +\end{verbatim} +\end{code} + +Some utility productions. +\begin{code} +\begin{verbatim} +latex_id = \c { \c } . +name = \c { \c } . +text = '"' { \c } '"' . +Eol = \n . +digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' . +integer = digit { digit } . +ct_file_name = name . +file_id = name . +buffer_id = integer . +mode_id = name . +\end{verbatim} +\end{code} + +The starting production. +\begin{code} +\begin{verbatim} +table = [ special_chars ] { specification | inclusion | comment } eof . +\end{verbatim} +\end{code} + +Productions for \keytext{inclusion} and \keytext{comment} and \keytext{eof}. +\begin{code} +\begin{verbatim} +inclusion = Include ct_file_name Eol . +comment = Comment { \c } Eol . +eof = EndCtfile { \c } Eol . +\end{verbatim} +\end{code} + +Productions for \keytext{special\_chars}. +\begin{code} +\begin{verbatim} +special_chars = [ escape ] [ alert ] [ backspace ] [ return ] [ feed ] + [ hex ] [ htab ] [ newline ] [ vtab ] { comment } . +escape = EscapeChar \c Eol Eol . +alert = AudibleAlertChar \c Eol . +backspace = BackspaceChar \c Eol . +return = CarriageReturnChar \c Eol . +feed = FormfeedChar \c Eol . +hex = HexChar \c Eol . +htab = HorizontalTabChar \c Eol . +newline = NewlineChar \c Eol . +vtab = VerticalTabChar \c Eol . +\end{verbatim} +\end{code} + + + +Productions for \keytext{specification}. +\begin{code} +\begin{verbatim} +specification = built_in | normal | list | section | special | picture | odd . +built_in = (Type built_in_type Eol) [ built_in_body ] end_type . +end_type = EndType Eol . +built_in_type = BeginDocument | BeginDollar | BeginVerb | BeginVerbatim | + EndDocument | EndDollar | EndVerb | EndVerbatim | + Lbrace | OtherBegin | OtherCommand | OtherEnd | + Paragraph | Rbrace | SlashSpace . +normal = (Type normal_type Eol) type_name [ normal_body ] end_type . +type_name = Name latex_id Eol . +normal_type = BeginEnv | BeginVenv | CharCommand | Command | + EndEnv | EndVenv | TexChar | Vcommand . +list = (Type list_type Eol) type_name [ list_body ] end_type . +list_type = BeginListEnv | EndListEnv . +section = (Type Sectioning Eol) type_name [ section_body ] end_type . +special = (Type special_type Eol) type_name [ special_body ] end_type . +special_type = Special | SpecialBeginEnv | SpecialBeginList | + SpecialCommand | SpecialEndEnv | SpecialEndList | + SpecialSectioning . +picture = (Type picture_type Eol) type_name [ picture_body ] end_type . +picture_type = BeginPictureCc | EndPicture | PictureCcpp | PictureCo | + PictureCop | PictureCp | PictureOcc | + PictureOccc | PictureOco | PicturePcop . +odd = (Type odd_type Eol) type_name [ odd_body ] end_type . +odd_type = CommandOop | CommandOoopp | CommandOpo | + CommandPooop | CommandPoop | CommandPoopp . +\end{verbatim} +\end{code} + +The \keytext{X\_body} productions. +\begin{code} +\begin{verbatim} +built_in_body = [ basic_body ] + { start_mode [ basic_body ] end_mode } . +start_mode = InMode mode_id Eol . +end_mode = EndMode Eol . +normal_body = [ basic_norm_body ] + { start_mode [ basic_norm_body ] end_mode } . +sect_body = [ basic_sect_body ] + { start_mode [ basic_sect_body ] end_mode } . +list_body = [ basic_list_body ] + { start_mode [ basic_list_body ] end_mode } . +picture_body = [ basic_defarg_body ] + { start_mode [ basic_defarg_body ] end_mode } . +odd_body = [ basic_defarg_body ] + { start_mode [ basic_defarg_body ] end_mode } . +special_body = [ basic_special_body ] + { start_mode [ basic_special_body ] end_mode } . +\end{verbatim} +\end{code} + + +Note: the ordering of the components of the following +\keytext{basic\_X\_body} productions is immaterial. +\begin{code} +\begin{verbatim} +basic_body = [ start_it ] [ end_it ] . +basic_norm_body = [ basic_body ] [ no_req_arg ] [ opt_arg_pos ] + { arg_print } { arg_action } . +basic_sect_body = sect_level [ basic_norm_body ] . +sect_level = SectioningLevel div_level Eol . +div_level = Chapter | Para | Part | Partm1 | Partm2 | Sect | Subpara | + Subparap1 | Subparap2 | Subsect | Subsubsect . +basic_defarg_body = [ basic_body ] { arg_print } { arg_action } . +basic_list_body = [ basic_norm_body ] { item_action } . +basic_special_body = [ sect_level ] [ basic_list_body ] . +no_req_arg = Reqparams integer Eol . +opt_arg_pos = OptParam ( First | Last ) Eol . +\end{verbatim} +\end{code} + +The \keytext{start\_it} and \keytext{end\_it} productions. +\begin{code} +\begin{verbatim} +start_it = [ start_print ] [start_action ] . +start_print = PcAtStart ( basic_pc_kind | Reset ) Eol . +basic_pc_kind = NoPrint | ToSysbuf | print_to_buffer | print_to_file . +print_to_buffer = ToBuffer buffer_id . +print_to_file = ToFile file_id . +start_action = StartTag [ text ] Eol { tag_action } . +tag_action = ( String text | + Source ( Sysbuf | user_buffer | user_file ) | + ResetBuffer buffer_id | + ResetFile file_id | + ResetSysbuf | + SwitchToBuffer buffer_id | + SwitchToFile file_id | + SwitchToSysbuf | + SwitchBack | + SetMode mode_id | + ResetMode ) + Eol . +user_buffer = Buffer buffer_id . +user_file = File file_id . +end_it = [ end_print ] [ end_action ] . +end_print = PcAtEnd (basic_pc_kind | Reset) Eol . +end_action = EndTag [ text ] Eol { tag_action } . +\end{verbatim} +\end{code} + +The \keytext{arg\_print} productions. +\begin{code} +\begin{verbatim} +arg_print = print_arg_kind (basic_pc_kind | NoOp ) Eol . +print_arg_kind = PrintOpt | PrintP1 | PrintP2 | PrintP3 | PrintP4 | + PrintP5 | PrintP6 | PrintP7 | PrintP8 | PrintP9 . +\end{verbatim} +\end{code} + +The \keytext{arg\_action} productions. +\begin{code} +\begin{verbatim} +arg_action = arg_tag_kind [ text ] Eol { tag_action } . +arg_tag_kind = EndOpt | EndTag1 | EndTag2 | EndTag3 | EndTag4 | + EndTag5 | EndTag6 | EndTag7 | EndTag8 | EndTag9 | + StartOpt | StartTag1 | StartTag2 | StartTag3 | StartTag4 | + StartTag5 | StartTag6 | StartTag7 | StartTag8 | StartTag9 . +\end{verbatim} +\end{code} + +The \keytext{item\_action} productions. +\begin{code} +\begin{verbatim} +item_action = item_tag_kind [ text ] Eol { tag_action } . +item_tag_kind = EndItem | EndItemParam | StartItem | StartItemParam . +\end{verbatim} +\end{code} + + The parser in \lx{} for the \ctab{} is very simple. For each \keyword{TYPE=} +in the \ctab{} it creates a \keytext{struct} to hold the specification +data. If any type is multiply defined, then which one will be finally used +is somewhat random because of the sorting and searching algorithms employed +internally. No checks are made for multiply defined entries. + + Each command in the \ctab{} starts on a seperate line. + The parser reads only as much of a table line as is necessary to parse that +line according to the first token that it finds on the line. The data in +each line after parsing is added to the current \keytext{struct} for the +\LaTeX{} command. +If any of the command lines within an entry are multiply defined, +then the latest one will overwrite any earlier ones. + + This line-based parsing means that effectively anything between the +end of the required data on the line is ignored by the parser, and so could +be treated as a comment. There is no guarantee that this behaviour will +be maintained in future releases of \lx. + +\section{A grammar for \ExpressA} \label{sec:expgrammar} + + The same WSN notation is used for the grammar for \ExpressA{} as +for the \ctab{} grammar. + + First the keywords. Note that these are case insensitive. Also +not all of the keywords have been used in this implementation +of \ExpressA; those that have not been used are reserved for the +future. + +\begin{code} +\begin{verbatim} + ABS = 'abs' . + ABSTRACT = 'abstract' . + ACOS = 'acos' . + AGGREGATE = 'aggregate' . + ALIAS = 'alias' . + AND = 'and' . + ANDOR = 'andor' . + ARRAY = 'array' . + AS = 'as' . + ASIN = 'asin' . +\end{verbatim} + +\begin{verbatim} + ATAN = 'atan' . + BAG = 'bag' . + BEGIN = 'begin' . + BINARY = 'binary' . + BLENGTH = 'blength' . + BOOLEAN = 'boolean' . + BY = 'by' . + CALL = 'call' . + CASE = 'case' . + CONSTANT = 'constant' . +\end{verbatim} + +\begin{verbatim} + CONST_E = 'const_e' . + CONTEXT = 'context' . + COS = 'cos' . + CRITERIA = 'criteria' . + DERIVE = 'derive' . + DIV = 'div' . + ELSE = 'else' . + END = 'end' . + END_ALIAS = 'end_alias' . + END_CALL = 'end_call' . +\end{verbatim} + +\begin{verbatim} + END_CASE = 'end_case' . + END_CODE = 'end_code' . + END_CONSTANT = 'end_constant' . + END_CONTEXT = 'end_context' . + END_CRITERIA = 'end_criteria' . + END_ENTITY = 'end_entity' . + END_FUNCTION = 'end_function' . + END_IF = 'end_if' . + END_LOCAL = 'end_local' . + END_MODEL = 'end_model' . +\end{verbatim} + +\begin{verbatim} + END_NOTES = 'end_notes' . + END_OBJECTIVE = 'end_objective' . + END_PARAMETER = 'end_parameter' . + END_PROCEDURE = 'end_procedure' . + END_PURPOSE = 'end_purpose' . + END_REALIZATION = 'end_realization' . + END_REFERENCES = 'end_references' . + END_REPEAT = 'end_repeat' . + END_RULE = 'end_rule' . + END_SCHEMA = 'end_schema' . +\end{verbatim} + +\begin{verbatim} + END_SCHEMA_DATA = 'end_schema_data' . + END_TEST_CASE = 'end_test_case' . + END_TYPE = 'end_type' . + ENTITY = 'entity' . + ENUMERATION = 'enumeration' . + EOF = 'eof' . + EOLN = 'eoln' . + ESCAPE = 'escape' . + EXISTS = 'exists' . + EXP = 'exp' . + FALSE = 'false' . +\end{verbatim} + +\begin{verbatim} + FIXED = 'fixed' . + FOR = 'for' . + FORMAT = 'format' . + FROM = 'from' . + FUNCTION = 'function' . + GENERIC = 'generic' . + HIBOUND = 'hibound' . + HIINDEX = 'hiindex' . + IF = 'if' . + IMPORT = 'import' . +\end{verbatim} + +\begin{verbatim} + IN = 'in' . + INSERT = 'insert' . + INTEGER = 'integer' . + INVERSE = 'inverse' . + LENGTH = 'length' . + LIKE = 'like' . + LIST = 'list' . + LOBOUND = 'lobound' . + LOINDEX = 'loindex' . + LOCAL = 'local' . +\end{verbatim} + +\begin{verbatim} + LOG = 'log' . + LOG10 = 'log10' . + LOG2 = 'log2' . + LOGICAL = 'logical' . + MOD = 'mod' . + MODEL = 'model' . + NOT = 'not' . + NOTES = 'notes' . + NUMBER = 'number' . + NVL = 'nvl' . +\end{verbatim} + +\begin{verbatim} + OBJECTIVE = 'objective' . + ODD = 'odd' . + OF = 'of' . + ONEOF = 'oneof' . + OPTIONAL = 'optional' . + OR = 'or' . + ORD = 'ord' . + OTHERWISE = 'otherwise' . + PARAMETERi = 'parameter' . + PI = 'pi' . +\end{verbatim} + +\begin{verbatim} + PRED = 'pred' . + PROCEDURE = 'procedure' . + PURPOSE = 'purpose' . + QUERY = 'query' . + READ = 'read' . + READLN = 'readln' . + REAL = 'real' . + REALIZATION = 'realization' . + REFERENCE = 'reference' . + REFERENCES = 'references' . +\end{verbatim} + +\begin{verbatim} + REMOVE = 'remove' . + REPEAT = 'repeat' . + RETURN = 'return' . + REXPR = 'rexpr' . + ROLESOF = 'rolesof' . + ROUND = 'round' . + RULE = 'rule . + SCHEMA = 'schema' . + SCHEMA_DATA = 'schema_data' . + SELECT = 'select' . +\end{verbatim} + +\begin{verbatim} + SELF = 'self' . + SET = 'set' . + SIN = 'sin' . + SIZEOF = 'sizeof' . + SKIP = 'skip' . + SQRT = 'sqrt' . + STRING = 'string' . + SUBOF = 'subof' . + SUBTYPE = 'subtype' . + SUCC = 'succ' . +\end{verbatim} + +\begin{verbatim} + SUPERTYPE = 'supertype' . + SUPOF = 'supof' . + SYSTEM = 'system' . + TAN = 'tan' . + TEST_CASE = 'test_case' . + THE_DAY = 'the_day' . + THE_MONTH = 'the_month' . + THE_YEAR = 'the_year' . + THEN = 'then' . + TO = 'to' . +\end{verbatim} + +\begin{verbatim} + TRUE = 'true' . + TRUNC = 'trunc' . + TYPE = 'type' . + TYPEOF = 'typeof' . + UNIQUE = 'unique' . + UNKNOWN = 'unknown' . + UNTIL = 'until' . + USE = 'use' . + USEDIN = 'usedin' . + USING = 'using' . +\end{verbatim} + +\begin{verbatim} + VALUE = 'value' . + VALUE_IN = 'value_in' . + VALUE_UNIQUE = 'value_unique' . + VAR = 'var' . + WHERE = 'where' . + WHILE = 'while' . + WITH = 'with' . + WRITE = 'write' . + WRITELN = 'writeln' . + XOR = 'xor' . +\end{verbatim} +\end{code} + +The following rules define various classes of characters which are used in +constructing the tokens. + +\begin{code} +\begin{verbatim} + digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' . + digits = digit { digit } . + letter = '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' . + lparen_not_star = '(' not_star . + not_lparen_star = not_paren_star | ')' . + not_paren_star = letter | digit | not_paren_star_special . + not_paren_star_quote_special = '!' | '"' | '#' | '$' | '%' | '&' | '+' | + ',' | '-' | '.' | '/' | ':' | ';' | '<' | '=' | '>' | '?' | + '@' | '[' | '\' | ']' | '^' | '_' | '`' | '{' | '|' | '}' | + '~' . + not_paren_star_special = not_paren_star_quote_special | '''' . + not_quote = not_paren_star_quote_special | letter | digit | '(' | ')' | '*' . + not_rparen = not_paren_star | '*' | '(' . +\end{verbatim} + +\begin{verbatim} + not_star = not_paren_star | '(' | ')' . + octet = hex_digit hex_digit . + special = not_paren_star_quote_special | '(' | ')' | '*' | '''' . + star_not_rparen = '*' not_rparen . +\end{verbatim} +\end{code} + + + The following rules specify how certain combinations of characters are +interpreted as lexical elements within the language. + +\begin{code} +\begin{verbatim} + integer_literal = digits . + real_literal = digits '.' [ digits ] [ 'e' [ sign ] digits ] . + simple_id = letter { letter | digit | '_' } . + simple_string_literal = \q { ( \q \q ) | not_quote | \s | \o } \q . +\end{verbatim} +\end{code} + +The following rules specify the syntax of comments in \ExpressA. + + +\begin{code} +\begin{verbatim} + embedded_remark = '(*' { not_lparen_star | lparen_not_star | + star_not_rparen | embedded_remark } '*)' . + remark = embedded_remark | tail_remark . + tail_remark = '--' { \a | \s | \o } \n . +\end{verbatim} +\end{code} + + +The following rules represent identifiers which are known to have a particular +meaning (i.e., to be declared elsewhere as types or functions, etc.). + + + +\begin{code} +\begin{verbatim} + attribute_ref = attribute_id . + constant_ref = constant_id . + entity_ref = entity_id . + enumeration_ref = enumeration_id . + function_ref = function_id . + parameter_ref = parameter_id . + procedure_ref = procedure_id . + type_ref = type_id . + variable_ref = variable_id . +\end{verbatim} +\end{code} + + + + The following rules specify how the previous lexical elements may be +combined into constructs of \ExpressA. White space and/or remark(s) may appear +between any two tokens in these rules. The primary syntax rule for \ExpressA{} +is \verb|express_a|. + + + +\begin{code} +\begin{verbatim} + actual_parameter_list = '(' parameter { ',' parameter } ')' . + add_like_op = '+' | '-' | OR | XOR . + aggregation_types = array_type | bag_type | list_type | set_type . + algorithm_head = { declaration } [ local_decl ] . + array_type = ARRAY bound_spec OF base_type . + assignment_stmt = general_ref { qualifier } ':=' expression ';' . + attribute_decl = attribute_id . + attribute_id = simple_id . + attribute_qualifier = '.' attribute_ref . + bag_type = BAG [ bound_spec ] OF base_type . +\end{verbatim} + +\begin{verbatim} + base_type = aggregation_types | simple_types | named_types . + boolean_type = BOOLEAN . + bound_1 = numeric_expression . + bound_2 = numeric_expression . + bound_spec = '[' bound_1 ':' bound_2 ']' . + built_in_constant = CONST_E | PI | THE_DAY | THE_MONTH | THE_YEAR | '?' . + built_in_function = ABS | COS | EOF | EOLN | EXISTS | EXP | + HIBOUND | HIINDEX | LENGTH | LOBOUND | LOINDEX | + LOG | LOG2 | LOG10 | NVL | ODD | ORD | PRED | + REXPR | ROUND | SIN | SIZEOF | + SQRT | SUCC | TAN | TRUNC . + built_in_procedure = INSERT | PRINT | PRINTLN | READ | READLN | REMOVE | + SYSTEM | WRITE | WRITELN . + case_action = case_label { ',' case_label } ':' stmt . + case_label = expression . +\end{verbatim} + +\begin{verbatim} + case_stmt = CASE selector OF { case_action } [ OTHERWISE ':' stmt ] + END_CASE ';' . + compound_stmt = BEGIN stmt { stmt } END ';' . + constant_factor = built_in_constant . + constructed_types = enumeration_type . + declaration = entity_decl | function_decl | procedure_decl | type_decl . + entity_body = { explicit_attr } . + entity_decl = entity_head entity_body END_ENTITY ';' . + entity_head = ENTITY entity_id ';' . + entity_id = simple_id . + enum_id = simple_id . +\end{verbatim} + +\begin{verbatim} + enumeration_reference = enum_id . + enumeration_type = ENUMERATION OF '(' enum_id { ',' enum_id } ')' . + escape_stmt = ESCAPE ';' . + explicit_attr = attribute_decl { ',' attribute_decl } ':' base_type ';' . + express_a = { declaration } [ local_decl ] { stmt } END_CODE . + expression = simple_expression [ rel_op_extended simple_expression ] . + factor = simple_factor [ '**' simple_factor ] . + formal_parameter = parameter_id { ',' parameter_id } ':' parameter_type . + function_call = ( built_in_function | function_ref ) + [ actual_parameter_list ] . + function_decl = function_head [ algorithm_head ] stmt { stmt } + END_FUNCTION ';' . +\end{verbatim} + +\begin{verbatim} + function_head = FUNCTION function_id [ '(' formal_parameter + { ';' formal_parameter } ')' ] ':' parameter_type ';' . + function_id = simple_id . + generalized_types = general_aggregation_types . + general_aggregation_types = general_array_type | general_bag_type | + general_list_type | general_set_type . + general_array_type = ARRAY [ bound_spec ] OF parameter_type . + general_bag_type = BAG [ bound_spec ] OF parameter_type . + general_list_type = LIST [ bound_spec ] OF parameter_type . + general_ref = parameter_ref | variable_ref . + general_set_type = SET [ bound_spec ] OF parameter_type . + if_stmt = IF logical_expression THEN stmt { stmt } [ ELSE stmt { stmt } ] + END_IF ';' . +\end{verbatim} + +\begin{verbatim} + increment = numeric_expression . + increment_control = variable_id ':=' bound_1 TO bound_2 [ BY increment ] . + index = numeric_expression . + index_1 = index . + index_2 = index . + index_qualifier = '[' index_1 [ ':' index_2 ] ']' . + integer_type = INTEGER . + interval = '{' interval_low interval_op interval_item interval_op + interval_high '}' . + interval_high = simple_expression . + interval_item = simple_expression . +\end{verbatim} + +\begin{verbatim} + interval_low = simple_expression . + interval_op = '<' | '<=' . + list_type = LIST [ bound_spec ] OF base_type . + literal = integer_literal | logical_literal | real_literal | + string_literal . + local_decl = LOCAL local_variable { local_variable } END_LOCAL ';' . + local_variable = variable_id { ',' variable_id } ':' parameter_type ';' . + logical_expression = expression . + logical_literal = FALSE | TRUE | UNKNOWN . + logical_type = LOGICAL . + multiplication_like_op = '*' | '/' | DIV | MOD | AND | '||' . +\end{verbatim} + +\begin{verbatim} + named_types = entity_ref | type_ref . + null_stmt = ';' . + numeric_expression = simple_expression . + parameter = expression . + parameter_id = simple_id . + parameter_type = generalized_types | named_types | simple_types . + population = entity_ref . + primary = literal | ( qualifiable_factor { qualifier } ) . + procedure_call_stmt = ( built_in_procedure | procedure_ref ) + [ actual_parameter_list ] ';' . + procedure_decl = procedure_head [ algorithm_head ] { stmt } END_PROCEDURE ';' . +\end{verbatim} + +\begin{verbatim} + procedure_head = PROCEDURE procedure_id [ '(' [ VAR ] formal_parameter + { ';' [ VAR ] formal_parameter } ')' ] ';' . + procedure_id = simple_id . + qualifiable_factor = attribute_ref | constant_factor | function_call | + general_ref | population . + qualifier = attribute_qualifier | index_qualifier . + real_type = REAL . + referenced_attribute = attribute_ref | qualified_attribute . + rel_op = '<' | '>' | '<=' | '>=' | '<>' | '=' | ':<>:' | ':=:' . + rel_op_extended = rel_op | IN | LIKE . + repeat_control = [ increment_control ] [ while_control ] [ until_control ] . + repeat_stmt = REPEAT repeat_control ';' stmt { stmt } END_REPEAT ';' . +\end{verbatim} + +\begin{verbatim} + return_stmt = RETURN [ '(' expression ')' ] ';' . + selector = expression . + set_type = SET [ bound_spec ] OF base_type . + sign = '+' | '-' . + simple_expression = term { add_like_op term } . + simple_factor = enumeration_reference | interval | + ( [ unary_op ] ( '(' expression ')' | primary ) ) . + simple_types = integer_type | logical_type | real_type | string_type . + skip_stmt = SKIP ';' . + stmt = assignment_stmt | case_stmt | compound_stmt | escape_stmt | + if_stmt | null_stmt | procedure_call_stmt | repeat_stmt | return_stmt | + skip_stmt . + string_literal = simple_string_literal . +\end{verbatim} + +\begin{verbatim} + string_type = STRING . + term = factor { multiplication_like_op factor } . + type_decl = TYPE type_id '=' underlying_type ';' END_TYPE ';' . + type_id = simple_id . + unary_op = '+' | '-' | NOT . + underlying_type = constructed_types | aggregation_types | simple_types | + type_ref . + until_control = UNTIL logical_expression . + variable_id = simple_id . + while_control = WHILE logical_expression . +\end{verbatim} +\end{code} + + + + +\addcontentsline{toc}{section}{References} +%\bibliography{refs,prw} + +\begin{thebibliography}{10} + +\bibitem{LAMPORT94} +Leslie Lamport. +\newblock {\em LaTeX: A Document Preparation System}. +\newblock Addison-Wesley Publishing Company, second edition, 1994. + +\bibitem{KNUTH84a} +Donald~E. Knuth. +\newblock {\em The TeXbook}. +\newblock Addison-Wesley Publishing Company, 1984. + +\bibitem{STEPIS} +ISO 10303. +\newblock {\em Industrial automation systems and integration --- Product data + representation and exchange}, 1994. + +\bibitem{GOLDFARB90} +C.~A. Goldfarb. +\newblock {\em The SGML Handbook}. +\newblock Oxford University Press, 1990. +\newblock (Edited and with a foreword by Yuri Rubinsky). + +\bibitem{MUSCIANO96} +Chuck Musciano and Bill Kennedy. +\newblock {\em {HTML --- The Definitive Guide}}. +\newblock O'Reilly \& Associates, Inc., 1996. + +\bibitem{KERNIGHAN88} +Brian~W. Kernighan and Dennis~M. Ritchie. +\newblock {\em The C Programming Language}. +\newblock Prentice Hall, second edition, 1988. + +\bibitem{EBOOK} +Douglas~A. Schenck and Peter~R. Wilson. +\newblock {\em Information Modeling the EXPRESS Way}. +\newblock Oxford University Press (ISBN 0-19-308714-3), 1994. + +\bibitem{EXPRESSIS} +ISO 10303-11:1994. +\newblock {\em Industrial automation systems and integration --- Product data + representation and exchange --- Part 11: Description methods: The EXPRESS + language reference manual}, 1994. + +\bibitem{LEVINE92} +John~R. Levine, Tony Mason, and Doug Brown. +\newblock {\em lex \& yacc}. +\newblock O'Reilly \& Associates, Inc., second edition, 1992. + +\bibitem{LESK75} +M.~E. Lesk and E.~Schmidt. +\newblock `{LEX --- A Lexical Analyser Generator}'. +\newblock In {\em UNIX Programmer's Manual 2}. AT\&T Bell Laboratories, Murray + Hill, NJ, 1975. + +\bibitem{JOHNSON75} +S.~C. Johnson. +\newblock {\em YACC --- Yet Another Compiler Compiler}. +\newblock C S Technical Report 32, Bell Telephone Laboratories, Murray Hill, + NJ, 1975. + +\bibitem{EXPRESSITR} +ISO/TR 10303-12:1997. +\newblock {\em Industrial automation systems and integration --- Product data + representation and exchange --- Part 12: Description method: The EXPRESS-I + language reference manual}, 1997. + +\bibitem{PRW94b} +Peter~R. Wilson. +\newblock {\em `{FLaTTeN: A Program to Flatten LaTeX Source Files}'}. +\newblock NIST, Gaithersburg, MD 20899, December 1994. +\newblock (In draft). + +\bibitem{LIBES93} +Don Libes. +\newblock {\em Obfuscated C and Other Mysteries}. +\newblock John Wiley \& Sons, Inc., 1993. + +\bibitem{HOLUB90} +A.~I. Holub. +\newblock {\em Compiler Design in C}. +\newblock Prentice-Hall, Inc., 1990. + +\bibitem{ORAM91} +Andrew Oram and Steve Talbott. +\newblock {\em Managing Projects with make}. +\newblock O'Reilly \& Associates, Inc., second edition, 1991. + +\bibitem{RINAUDOT94} +Gaylen~R. Rinaudot. +\newblock {\em {The IGES/PDES Organization STEP On-Line Information Service}}. +\newblock NISTIR 5511, NIST, Gaithersburg, MD 20899, October 1994. + +\bibitem{WIRTH77} +N.~Wirth. +\newblock `{What Can We Do About the Unnecessary Diversity of Notation for + Syntactic Definitions?}'. +\newblock {\em Communications of the ACM}, 20(11):822--823, November 1977. + +\bibitem{MAKR91} +Ronald Mak. +\newblock {\em Writing Compilers \& Interpreters --- An Applied Approach}. +\newblock John Wiley \& Sons, Inc., 1991. + +\end{thebibliography} + + + +\end{document} -- cgit v1.2.3