% LAST EDIT: Tue Sep  3 15:37:48 1996 by Peter Pepper (basti!pepper) 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Example}

The use of this style is illustrated by the following example.

\begin{opal}[fn]
STRUCTURE Example
-----
IMPORT Nat ONLY nat:\SORT
                0~1~2~-~=
       String COMPLETELY
-----
FUN fib: nat -> nat             \- the Fibonnacci function
DEF fib(n) ==
    IF n=0~\/
       n=1    THEN 1       -- termination
              ELSE fib(n-1) + fib(n-2)
    FI
FUN fib: string -> string     \- for I/O
DEF fib(s) == (fib(s!))  -- overloading
\end{opal}

In order to obtain this text you have to write


\begin{verbatim}\begin{opal}[fn]
STRUCTURE Example
-----
IMPORT Nat ONLY nat:\SORT
                0~1~2~-~=
       String COMPLETELY
-----
FUN fib: nat -> nat             \- the Fibonnacci function
DEF fib(n) ==
    IF n=0~\/
       n=1    THEN 1       -- termination
              ELSE fib(n-1) + fib(n-2)
    FI
FUN fib: string -> string     \- for I/O
DEF fib(s) == (fib(s!))  -- overloading
\end{opal}\end{verbatim}






\subsection*{How does the style work?}

The style essentially provides an environment
\verb+\begin{opal}+\ldots\verb+\end{opal}+ within which program layouting
is supported. The layout itself is determined by way of the \Opal keywords
and the basic commands \verb+\[+, \verb+\&+, and \verb+\]+ (see below).

The style \texttt{opal2x.sty} is based on three other styles (which can
also be used independently). The overall dependency relationship is
illustrated by the following diagram (which also points out that styles for
other languages could be as easily defined).

\begin{center}
\unitlength0.5em
\begin{picture}(50,40)

\put(-1,30){\dashbox{1}(12,10)[t]{\vrule width0pt height2.2ex slang.sty}}
\put(19,30){\framebox(12,10)[t]{\vrule width0pt height2.2ex opal2x.sty}}
\put(39,30){\dashbox{1}(12,10)[t]{\vrule width0pt height2.2ex C$^{++}$.sty}}

\put(09,15){\framebox(12,10)[t]{\vrule width0pt height2.2ex basicprog.sty}}
\put(29,15){\framebox(12,10)[t]{\vrule width0pt height2.2ex symbols.sty}}

\put(19,00){\framebox(12,10)[t]{\vrule width0pt height2.2ex scanner.sty}}

\dottedline{0.5}(04,30)(13,25)
\drawline(25,30)(15,25)
\dottedline{0.5}(44,30)(17,25)

\dottedline{0.5}(06,30)(33,25)
\drawline(25,30)(35,25)
\dottedline{0.5}(46,30)(37,25)

\drawline(15,15)(24,10)
\drawline(35,15)(26,10)

\end{picture}
\end{center}

An essential feature of the style is the \emph{scanner}. It recognizes
identifiers, keywords, etc.~in \texttt{program} environments. Above all, it
allows to use `fancy commands' for having more readable input (such as
\verb+<=>+ for \(<=>\)).


\subsection*{Loading the style(s)}

The styles are loaded by

\quad\verb+\usepackage[ams,suppress]{opal2x}+

\quad\verb+\usepackage{basicprog}+

\quad\verb+\usepackage[ams,suppress]{symbols}+

\quad\verb+\usepackage{scanner}+

\emph{Note}: Loading any of the styles automatically also loads the styles
on which it depends. Hence it suffices to load \texttt{opal2x.sty}.

The \emph{options} have the following effect:
\begin{itemize}
  \item When \texttt{ams} is given, the style \texttt{amssymb} is
    automatically loaded.
  \item When \texttt{suppress} is given, the special symbols (see
    Table~\ref{tab:SpecialSymbols}) are prepared, but not yet defined. So
    the user can define them at some suitable point in the text, in
    particular also locally in certain environments.
\end{itemize}

{\small \emph{Note}: There may be problems, when the style is loaded after
  \texttt{[german]babel} due to conflicting macro declarations (but most of
  these problems appear to be solved).}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\clearpage

\section{The \texttt{opal} and \texttt{program} Environments}

The \texttt{opal} environment and the \texttt{program} environment are
written in the same form using the same optional arguments.

\begin{verbatim}
\begin{opal}[pcfn]
   ...
\end{opal}
\end{verbatim}

\begin{verbatim}
\begin{program}[pcfn]
   ...
\end{program}
\end{verbatim}

The \texttt{opal} environment actually creates a \texttt{program}
environment after introducing a number of \Opal-specific definitions
(keywords etc.).

The optional arguments --- which can be given in any selection and order%
\footnote{\ldots but not all combinations make sense}
--- have the following effects:

\begin{center}
\begin{tabular}[h]{|l|l|}
\hline
p[lain]    & No special options apply. (This is the default.)\cr
c[enter]   & The program is centered on the page.\cr
f[ramed]   & The program is framed.\cr
n[umbered] & Line numbers are automatically generated.\cr
\hline
\end{tabular}
\end{center}


\subsection{Customization}

A number of commands can be used to customize the appearance of the
style. They can be redefined arbitrarily often in the text.

\begin{itemize}
  \item \verb+\ProgramWidth{...}+ sets the width of programs. The
    default is \verb+\textwidth+.
  \item \verb+\ProgramLeftIndent{...}+ sets the left indentation of programs;
    default \verb+\parindent+.
  \item \verb+\ProgramRightIndent{...}+: Analogous; default is \verb+0pt+.
  \item \verb+\ProgramInnerIndent{...}+ determines the indentation of main
    keywords (such as \KeyWord{fun}) relative to top keywords (such as
    \KeyWord{signature}). The default is \verb+1em+.
  \item \verb+\ProgramSkip{...}+ determines the vertical distance of programs
    from the surrounding text. The default is \verb+\parskip+.
  \item \verb+\EmptyLineSkip{...}+ sets the amount of vertical space that is
    effected by an empty input line (see section~\ref{sec:Additional}).
\end{itemize}

Finally, the user can insert his own definitions into \texttt{program} and
\texttt{opal} environments by means of the commands

\begin{itemize}
  \item \verb+\renewcommand{\ProgramPrelude}{...}+
  \item \verb+\renewcommand{\OpalPrelude}{...}+
\end{itemize}

\verb+\ProgramPrelude+ is executed at the beginning of the \texttt{program}
environment --- in analogy to \verb+\everymath+ for math mode. And
\verb+\OpalPrelude+ is in addition executed at the beginning of
\texttt{opal} environments.


\subsection{Embedded programs}

Whereas the \texttt{program} environment is comparable to displayed math,
there is also an \texttt{embeddedProgram} environment that is comparable to
normal math mode. This environment is provided by

\quad\verb+\begin{embeddedProgram} ... \end{embeddedProgram}+

or by its shorthand form

\quad\verb+\(...\)+

which both can be written in the middle of a text in order to obtain the
special features of programs (such as keywords and special symbols).  Of
course, the layout commands are not meaningful here.

In analogy to the \texttt{program} environment, one can also introduce
private definitions at the beginning of \texttt{embedded programs} by using

\quad\verb+\renewcommand{\EmbeddedProgramPrelude}{...}+





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Layout commands}

In the \texttt{program} and \texttt{opal} environments programs can be
typeset by using two kinds of commands.

\begin{itemize}
  \item The \emph{basic commands} leave full control of the layout to the
    user (at the cost of less readable input).
  \item The \emph{keyword-oriented commands} employ a bunch of heuristics
    for automatic layout generation.%
    \footnote{As always, heuristics don't work satisfactorily in all
      circumstances. Then it is possible to combine the advanced layout
      features with the basic commands.}
\end{itemize}




\subsection{Basic layout commands}

The design philosophy of the style \texttt{basicprog.sty} is to provide a
very small set of basic layout commands, on which all other commands (see
later on) can be based.

Essentially, a program environment consists of \emph{nested tabular
environments}%
\footnote{We use the \LaTeX~terminology here, even though we actually
  create \TeX~ halign commands here}%
. The main problem is that in programs the following arrangement of boxes
is quite typical:

\begin{center}
\unitlength0.6mm
\begin{picture}(45,30)
   \put(00,15){\framebox(20,15){}}
   \put(20,10){\framebox(15,07){}}
   \put(35,00){\framebox(10,12){}}
\end{picture}
\end{center}
Unfortunately, this kind of layout is not provided by \TeX, and therefore a
lot of calculations are necessary in order to achieve the desired
effect. These calculations are effected by the following commands.

\begin{itemize}
  \item \verb=\[= %\]
    \quad opens a new tabular environment.
  
  \item \verb=\&=
    \quad separates two columns.
    
  \item \verb=\]=
    \quad closes a tabular environment.

\end{itemize}

Between any two of these commands \TeX~ is in math mode.



\subsection{Keyword-oriented layout commands}

The heuristic layouting should be controlled by commands that correspond to
keywords in the underlying language (such as \`def', \`if', \`then',
etc.). These are usually introduced by language-specific styles such as
\texttt{opal2x.sty}.
The style \texttt{basicprog.sty} only provides means for introducing such
special commands in other styles.  



\subsubsection*{The keywords of \texttt{opal2x.sty}}

Within the \texttt{opal} environment every \Opal keyword such as
\`SIGNATURE', \`DEF', \`IF', \`AS', etc. actually is a \TeX~command%
\footnote{Note that \emph{no} backslash is needed! This is made possible by
  the scanner described in Section \ref{sec:Scanner}.} %
that not only produces the keyword but also generates basic layout commands
according to certain heuristics.

Tables~\ref{tab:KeyWords} and \ref{tab:KeyWords2} list all keyword-oriented
layout commands defined in \texttt{opal2x.sty} together with the commands,
by which they are generated.

\emph{Note 1}: All these keyword-oriented layout commands can be combined
with the primitive commands \verb+\[+, \verb+\&+, \verb+\]+, \verb+\-+,
\verb+\%+ etc.

\emph{Note 2}: Together with any ``fancy'' layout command (such as
e.g.~\texttt{IF}) the style also generates a standard \LaTeX~command (such as
\verb+\IF+) that merely creates the corresponding keyword.%

\emph{Note 3}: Between any two of these commands \TeX~ is in math mode.



\subsubsection*{The keyword-generating commands of \texttt{basicprog.sty}}

Table~\ref{tab:NewKeywords} lists the commands through which
layout-defining keywords can be introduced.



\begin{itemize}
  \item For instance, \verb+\BeginKeyWord{IF}+ has the following effects:
  \begin{itemize}
    \item It creates a ``fancy command'' \verb+IF+ (recognized by the
      scanner) that embodies a certain layout heuristics including the
      keyword \`if'.
    \item In addition, it also creates a command \verb+\IF+ that represents
      the plain keyword \`if'.
  \end{itemize}
\end{itemize}

The following list illustrates these commands by way of characteristic
examples.

\begin{itemize}
  \item \verb+\TopKeyWord{STRUCTURE}+.
    
    This command first closes all open tabular environments. The rest is
    equivalent to \verb+\[\STRUCTURE~\[+. %\]

  \item \verb+\MainKeyWord{DEF}+.
    
    This command first closes all open tabular environments. The rest is
    equivalent to \verb+\[...\DEF~\[+. (The \ldots~indicate that here a  %\]
    space of size \verb+\ProgramInnerIndent+ is inserted.)

  \item \verb+\FollowKeyWord{ONLY}+.
    
    This is essentially equivalent to \verb+\&~\ONLY~\&\[+.  %\]

  \item \verb+\BeginKeyWord{LET}+.
    
    This is essentially equivalent to \verb+\[~\LET~\&\[+.   %\]

  \item \verb+\IfLikeKeyWord{IF}+.
    
    This is essentially equivalent to \verb+\[~\IF~\&\[+.   %\]

  \item \verb+\ThenLikeKeyWord{THEN}+.
    
    This is essentially equivalent to \verb+\]~\&\THEN~\&\[+.   %\]

  \item \verb+\ElseLikeKeyWord{ELSE}+.
    
    This is essentially equivalent to \verb+\]\&~\ELSE~\&\[+.   %\]

  \item \verb+\EndKeyWord{FI}+.
    
    This is essentially equivalent to \verb+\]~\FI~\]+.

  \item \verb+\PlainKeyWord{AS}+.
    
    This is essentially equivalent to \verb+~\AS~+.

\end{itemize}

\emph{Note 1}: Most of these keywords generate slightly different layouts,
when they appear as the first element on a new line.

\emph{Note 2}: All of these keywords can be provided with an optional
argument that determines the width of its keyword. For instance
\begin{itemize}
  \item \verb+\BeginKeyWord[1em]{OTHERWISE}+
\end{itemize}
shortens the keyword to the length 1em. This way, the keyword doesn't spoil
the layout by creating huge gaps after the corresponding \texttt{IF}s.

\emph{Note 3}: The \verb+\IfLikeKeyWord+ uses some special heuristics to
cope with the layout of \Opal's special \`IF'-sequences.





\subsection{Empty Lines, Rules, and Shrinking Boxes}
\label{sec:Additional}

A number of commands can be used to customize the appearance of programs.

\begin{itemize}
  \item \verb+\Break+ enables a page break at this point.
    
    \emph{Note}: The \verb=\Break= command automatically closes all open
    tabular environments! Therefore it is only meaningful between top or
    main keywords (see below). \verb+\Break+ should be on a line of its own.

  \item \textbf{Empty lines} in the input of a program do \emph{not} really
    create an empty line in the output, but rather only a larger
    vertical space between the two surrounding lines. The size of this
    space can be set by the macro \verb+\EmptyLineSpace{...}+ (default is
    \verb+.6\baselineskip+).

    If one really wants an empty line, one must write ``invisible'' texts
    such as \verb+~+ or \verb+{ }+. (In this case the empty line will also
    be included in the automatic numbering, if this feature is set for the
    program.) 

  \item \verb=\Rule= draws a horizontal line accross the program ---
    provided that the frame option is on.

    \emph{Note}: The \verb+\Rule+ command has essentially the same
    properties as the \verb+\Break+ command!
    
  \item \verb+-----+ (5 dashes\footnote{Note that the scanner is employed
      to recognize this symbol.}) is equivalent to \verb+\Rule+.

  \item \verb=\0= sets the width of the following tabular environment to
    zero. That is, you write \verb=\0\[...= in order to obtain a piece of
    program that does (almost) not affect the layout of the surrounding
    program.

  \item \verb+\Shrink{...}+ sets its argument text into a box of width
    zero. (The argument must not include tabular stuff like \verb+\[+,
    \verb+\&+, \verb+\]+, or related commands.)
\end{itemize}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Comments and Line Numbers}

The \texttt{program} and \texttt{opal} environments provide features for
aligning comments and for adding line numbers.


\subsubsection*{Comments}

Two kinds of comments are recognized (by the scanner). They reach from
the start symbol to the end of the line.


\begin{description}
  \item[\TeX~comments] are started -- by default -- by the command
    \verb=\TeXCmnt=. This possibility is provided, because the symbol
    \verb=%= is a normal character in many programming languages.

    \TeX~comments are -- as usual -- completely ignored, including the end
    of line.

    The style \texttt{opal2x.sty} introduces the symbol \verb=\%= as the
    start symbol for \TeX~comments (see below).
    
  \item[Program comments] are started -- by default -- by the symbol
    \verb=\Cmnt=. They turn everything until (but excluding) the end of
    line into a comment, designated by the command \verb=\@Cmnt=. This
    command can be redefined by other styles in order to customize the
    layout of comments.

    The scanner is switched \emph{off} inside these comments!

    However, if \verb=\ActivateMathScan= is switched on, then the scanner
    is reactivated, whenever \verb=$...$= occurs in the comment.
                                                    
    The style \texttt{opal2x.sty} introduces the symbol \verb=\-= as start
    symbol for program comments (see below).

\end{description}
 

The following commands can be used to create these (different kinds of)
comments.

\begin{itemize}
  \item \verb+\%+ starts a \TeX~comment%
    \footnote{This is necessary, because the symbol \% is needed as a normal
      character in most programming languages.} %
    (that includes the end of the line and thus can be used to write
    several input lines for one output line).
    
  \item \verb+\-+ starts an \emph{aligned program comment} (that reaches to
    the end of the line). The printed comment symbol is `\texttt{--}'.

  \item \verb+\UaCmnt+ starts an unaligned program comment. (This command
    is usually not used itself, but equivated to special symbols, such as
    \verb+--+ in \texttt{opal2x.sty}.)

    Unfortunately, the unaligned comments don't work as nicely as aligned
    comments.%
    \footnote{This has technical reasons related to internal constraints of
      the scanner.} %
    Above all, it may happen that spaces don't show (see ``trouble
    shooting'').

  \item \verb+--+ starts an \emph{unaligned} program comment in
    \texttt{opal} environments.
\end{itemize}

Customizing the appearance of program comments is possible throught the
following command.

\begin{itemize}
  \item \verb+\renewcommand{\Comment}[1]{...}+ defines the appearance of
    comments; The default is \verb+\textit{#1}+.
\end{itemize}


\subsubsection*{Line numbers}

There are two ways for obtaining line numbers. Either one sets the option
`\texttt{[n]}' for the \texttt{program} or \texttt{opal} environment; then
all lines are consecutively numbered. Or one uses the following command in
order to achieve selective numbering.

\begin{itemize}
  \item \verb+\lnr+ is written at the end of those lines that shall be
    numbered.  (\emph{Note}: The \verb=\lnr= command has to appear
    \emph{before} the comment.)
    
    The \verb+\lnr+ command has no effect, when the option \verb+[n]+ is
    given.
\end{itemize}

Customizing of the appearance of line numbers is possible by the two
commands

\begin{itemize}
  \item \verb+\renewcommand{\Number}[1]{...}+ defines the appearance of
    the line numbers. The default is \verb+\texttt{\footnotesize#1}+.
  \item \verb+\NumberWidth{...}+ defines the width of the line numbers. The
    default is \texttt{2em}.
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Spaces}

\emph{Spaces are ignored}. (More precisely: They obey the rules of
the \TeX\ mathematics mode.) If you want a \emph{hard space}, you can write
`\verb=~='. That is, \verb=f~1~y= produces \texttt{f~1~y}.

For convenience, there is one \emph{exception} to this rule: If two
identifiers are separated by spaces, then a hard space is generated between
them. For example, \verb+f x y+ produces \(f x y\).





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\section{Fonts (for Identifiers, Keywords, etc.)}

By default, \emph{identifiers} and \emph{digits} are written in
\verb+\mathtt+ or \verb+\texttt+ font (depending on their context), and
\emph{keywords} are written using small capitals.

This can be changed by redefining the commands \verb+\KeyWord+,
\verb+\IdentifierFont+ and \verb+\DigitFont+ (preferred) or (not so
recommendable) by redefining \verb+\Identifier+ and \verb+\Digit+ (all
defined in \texttt{scanner.sty}). For example:

\begin{itemize}
  \item \verb+\IdentifierFont{it}+ makes identifiers italic.
  \item \verb+\DigitFont{rm}+ makes digits roman.
  \item \verb+\renewcommand{\KeyWord}[1]{...}+ redefines the appearance of
    keywords. The default is \verb+\textsc{\lowercase{#1}}+.
\end{itemize}


In texts, an identifier \Identifier{index} may be obtained by writing
\verb+\Identifier{index}+ and similarly a keyword \KeyWord{Fun} by writing
\verb+\KeyWord{FUN}+ or, shorter, \verb+\`FUN'+. But an alternative
possibility is to use embedded programs, that is \verb+\(FUN\)+ and
\verb+\(index\)+.

\emph{Note}: \verb+\`foo'+ does \emph{not} work in environments, where
\verb+\`+ is used as a special macro (for instance in tabular
environments). Then you should use \verb+\KeyWord{foo}+.



\subsection{Lisp-like identifiers}

Normally, a \Language{Lisp}-like identifier such as \verb+query-replace+
cannot be written in the \texttt{opal} and \texttt{program} environments,
because the outcome would be \(query-replace\). To cope with this notation
(if needed) there are two commands:

\begin{itemize}
  \item \verb+\EnableLisp+
    
    After this command has been given, identifiers such as
    \verb+query-replace+ are written in that form. (That is, a `\verb+-+' is
    \emph{not} considered as a `minus', if it occurs between two letters.)

  \item \verb+\DisableLisp+ (default)
    
    After this command has been given, \verb+query-replace+ is written as
    \(query-replace\) again.
\end{itemize}




\section{Miscellaneous}

A number of further features and commands are also part of the style.

\DefLanguage{Haskell}

\begin{itemize}
  \item \verb+\Language{...}+ is used to write all language names in a
    uniform font (default is \verb+\textsc+). Example:
    \verb+\Language{Haskell}+ yields \Language{Haskell}. (Note: This command
    uses \texttt{xspace.sty}.)
    
  \item \verb+\DefLanguage{...}+ introduces a command for a language
    name. For example, \verb+\DefLanguage{Haskell}+ allows us to write
    afterwards \verb+\Haskell+ in order to obtain \Haskell.
    
  \item \verb+\Opal+ is predefined and yields the name \Opal. (Note that
    the \verb+\xspace+ commmand is used here; hence, the command can be
    followed by a space.)
\end{itemize}






