\chapter{What {\tt pphs} does}

This chapter describes a program called {\tt pphs} which implements the typesetting
requirements described in the previous chapter.  The description is from the user's viewpoint,
later chapters going on to describe it from that of the programmer.

The {\tt pphs} program typesets Haskell programs for use with the \LaTeX\
typesetting program.  It takes as input a file containing a Haskell
program and produces the Haskell code to {\tt stdout}.  It is called by
typing {\tt pphs}, followed by the name of the file containing the Haskell
program.  For example, if the Haskell program was in a file called {\tt Haskell.hs},
the program would be called by
\begin{quote}
\tt pphs Haskell.hs
\end{quote}

If the filename ends with a {\tt .hs} extension, the extension may be omitted, provided
there is no file already existing with the same name but with no extension.  If no
extension is given with the filename when called, the program will look for a file of
that name with no extension. If this is not found, the program will add a {\tt .hs}
extension.  The above example, therefore, may be simplified to
\begin{quote}
\tt pphs Haskell
\end{quote}
unless the file {\tt Haskell} exists, in which case the original call must be made.

As the output of {\tt pphs} is to {\tt stdout}, it may be directed to a file by using
the {\tt >} command after the call, followed by the name of the file to contain
the \LaTeX\ code.  Continuing the above example, if the output code is to be put into
a file called {\tt Haskell.tex}, the call would now be
\begin{quote}
\tt pphs Haskell.hs > Haskell.tex
\end{quote}
It must be noted that if the file {\tt Haskell.tex} already exists, it should be
renamed or removed before making this call.

Two options are allowed with the call.  In the output, some people prefer \label{wide-colons}
the {\tt ::} symbol to be written $:\,:$ rather than $::$.  To obtain the former, use
{\tt -w} for wide colons.  A call on {\tt Haskell.hs} requiring wide colons would be
\begin{quote}
\tt pphs -w Haskell.hs
\end{quote}
When the input file's tab characters are not of the standard 8 spaces, this can be
specified with the {\tt -t} command.  For example, if the tabs were 4 spaces long, type
\begin{quote}
\tt pphs -t4 Haskell.hs
\end{quote}
Both options can be used at the same time by calling
\begin{quote}
\tt pphs -t4w Haskell.hs
\end{quote}
or
\begin{quote}
\tt pphs -wt4 Haskell.hs
\end{quote}
Any positive integer can be specified for the tablength.

\section{Left indentation}

It is in the nature of Haskell programs that indentation is heavily used.  As the
indentation is vital to the parsing of the program, any attempt at typesetting
Haskell code must replicate this indentation.  Take, for example, the following piece of code.
\begin{quote}
\input{Haskell_leftindent1}
\end{quote}
Note how the third and fourth lines both start at different levels of indentation.
The {\tt pphs} program produces the correct \LaTeX\ code to align these under the
correct position in the preceding lines once typeset.  It also selects the correct
line to line up under.  Note how, in the following example, the sixth line does not line up
under its predecessor, but under the fourth line.
\begin{quote}
\input{Haskell_leftindent2}
\end{quote}
Again, {\tt pphs} produces the code necessary to typeset this, preserving the parsing
order.  A line of Haskell code may be indented beyond the end of its predecessor.
Here, {\tt pphs} aligns it with whichever line it is lined up underneath in the
original file.  Note that these
examples of possible input have no `extra' typesetting commands.

\section{Internal alignment}

Another form of alignment used in Haskell is {\em internal alignment}.  This is where
there is vertical alignment of columns other than at the left-hand edge of the
Haskell code.
\begin{quote}
\input{Haskell_internalalign1}
\end{quote}
In this example, see how the {\tt =} signs line up, one below the other.  This makes
the program more readable, although it does not affect the parsing of the program.
As the purpose of {\tt pphs} is to make Haskell programs even more readable, it
retains this alignment.

\section{Token highlighting}

To increase the readability of Haskell programs, {\tt pphs} allows various tokens
to be highlighted.  By using different typefaces for some pieces of code, this
distinguishes them from the rest.  The user can specify the details of the highlighting as
described in Section~\ref{user-adj}, but the default settings are {\bf bold} for
keywords, {\it italics} for identifiers and {\rm roman} for everything else.  Strings,
comments and numbers are also highlightable (see Section~\ref{user-adj}).

\section{Mathematical symbols}

Rather than simply replicate the ASCII approximations of mathematical symbols
used in Haskell, {\tt pphs}
substitutes the proper symbols in the output.  These are shown in Table~\ref{maths-sym}.
\begin{table}
\begin{center}
\begin{tabular}[t]{|c|c|} \hline
{\em Haskell\/} & {\em Math\/} \\ \hline
{\tt *} & $\times$ \\
{\tt ++} & {\hbox{$+\mkern-7.5mu+$}} \\
{\tt :+} & {:}{+} \\
{\tt <=} & $\leq$ \\ \hline
\end{tabular} \hskip3mm \begin{tabular}[t]{|c|c|} \hline
{\em Haskell\/} & {\em Math\/} \\ \hline
{\tt >=} & $\geq$ \\
{\tt <-} & $\leftarrow$ \\
{\tt ->} & $\rightarrow$ \\
{\tt =>} & $\Rightarrow$ \\ \hline
\end{tabular}
\end{center}
\caption{Haskell ASCII approximations to mathematical characters} \label{maths-sym}
\end{table}

\section{\LaTeX\ typesetting characters}

\LaTeX\ uses embedded typesetting commands, so {\tt pphs} has to ensure that if
any of the characters used by \LaTeX\ appear in the input Haskell code, the correct
\LaTeX\ code is outputted to typeset them, rather than have the characters interfere
with the typesetting process.  The characters used by \LaTeX\ for typesetting are:
\begin{quote}
\(\#\ \$\ \%\ \&\ \char'176\ \_\ \char'136\ \hbox{$\setminus$}\ \hbox{$\cal \char'146\ \char'147$}\)
\end{quote}
The user of {\tt pphs} need not worry about using any of these characters in Haskell
programs, as this will be dealt with by {\tt pphs} before \LaTeX\ gets to see the code.