\chapter{Uses for output}

This chapter describes how the output from {\tt pphs} can be used.  First,
examples of the capabilities of {\tt pphs} are shown, then it is explained how
the output is incorporated into \LaTeX\ documents, and how the user can alter
the output using built in methods or by editing the output.

\section{Examples of output} \label{examples}

Up until now, only examples of input have been shown.  Let us now see what
{\tt pphs} actually does to this input.  Take this earlier example.
\begin{quote}
\input{Haskell_leftindent2}
\end{quote}
This is how this code is typeset by {\tt pphs}.
\begin{quote}
\input{LaTeX_leftindent2}
\end{quote}
Probably the most obvious thing about the typeset code is the highlighting
of the identifiers.  The reserved identifier or keyword {\keyword where} has been
highlighted in boldface while all the other identifiers are in italics.
The various symbols are in roman or math font as appropriate, these do not
get put in italics.  Less obvious is the indentation.  Notice how the starts
of the third, fourth and sixth lines all line up under {\iden state\/} on the
second line, just like they do in the input.  Similarly, the start of the fifth
line is under the $|$ on the fourth.  This demonstrates {\tt pphs}'s ability to
recreate left indentation in \LaTeX.  But note how the $=$ on the sixth line does
not align under the $|$ on the fifth as it does in the input.  This is because
they are different characters and so {\tt pphs} does not recognise this as internal
alignment.  The only special case made in this part of the program was for $::$ and $=$.
Alignment would have occurred by coincidence had the preceding characters on both lines
been of the same width. 

To illustrate internal alignment, recall this earlier example.
\begin{quote}
\input{Haskell_internalalign1}
\end{quote}
This code gets typeset like this.
\begin{quote}
\input{LaTeX_internalalign1}
\end{quote}
Notice here how the $=$ signs are aligned in a column, despite being preceded
be characters that may be of different widths.  This demonstrates the ability of
{\tt pphs} to recreate internal alignment.  Notice also how the {\tt '} signs
have been interpreted as primes.  This is because they are immediately preceded
by identifiers.  The {\tt *} signs have been transformed into multiplication signs,
while the {\tt =>} has been replaced with $\Rightarrow$.

Here is a new example, this time illustrating a comment and strings.
\begin{quote}
\input{Haskell_string1}
\end{quote}
This example gets typeset as follows.
\begin{quote}
\input{LaTeX_string1}
\end{quote}
Note how {\tt pphs} puts the correct inverted commas at each end of the strings
and how the strings themselves and the comment are in roman typeface.
The $=$ signs show internal alignment.

This next example demonstrates a comment, character quotes and the special case
with internal alignment where {\tt =} are aligned under {\tt ::}.
\begin{quote}
\input{Haskell_char}
\end{quote}
Typeset, this becomes
\begin{quote}
\input{LaTeX_char}
\end{quote}
The comment is typeset in roman, as are the character quotes.  This example has
the default double colon.  Using the {\tt -w} option, the colons can be positioned
further apart as illustrated below.
\begin{quote}
\input{LaTeX_wide-colons}
\end{quote}
It is a matter of taste which is used.

\section{Incorporating output into \LaTeX\ documents}

The motivation behind typesetting Haskell programs was so they could be incorporated
into \LaTeX\ documents.  This section describes how to do this with the output
of {\tt pphs}.

\subsection{The style file} \label{style-file}

Before using the output generated by {\tt pphs}, it is necessary to incorporate the
{\tt pphs.sty} style file (see Appendix~\ref{style-code}) into the document.
This provides definitions of the non-standard
commands produced by the program.  The use of the style file is announced
by adding {\tt pphs} to the option list of the documentstyle
command like thus:
\begin{quote}
\begin{verbatim}
\documentstyle[12pt,a4,pphs]{article}
\end{verbatim}
\end{quote}
Without {\tt pphs} in the option list, errors will occur when \LaTeX\ is run,
unless all the non-standard commands used by {\tt pphs} have been defined elsewhere
in the document.

\subsection{Including the output file}

To include the file containing the code output by {\tt pphs}, the \LaTeX\
{\tt \char'134 input} command is used.  If the file containing the output is called
{\tt output.tex} then the following command is used.
\begin{quote}
\begin{verbatim}
\input{output}
\end{verbatim}
\end{quote}
The code will appear at the left margin like this:
\input{LaTeX_simple}
This is useful for code listings.

By using various different \LaTeX\ environments, the typeset Haskell code
can be arranged differently.
To have the code indented like the examples in Section~\ref{examples}, the
{\tt quote} environment should be used.  The code
\begin{quote}
\begin{verbatim}
\begin{quote}
\input{output}
\end{quote}
\end{verbatim}
\end{quote}
would produce
\begin{quote}
\input{LaTeX_simple}
\end{quote}
The {\tt table} environment can be used to put the typeset Haskell code
into a table and also allows the code to be captioned.
The table will appear at the top of the current or next page depending on what
space is available in the document.  The \LaTeX\ code used to produce this is
\begin{quote}
\begin{verbatim}
\begin{table}
\begin{center}
\begin{minipage}{5cm}
\input{output}
\end{minipage}
\end{center}
\caption{Typeset code in a table} \label{output-table}
\end{table}
\end{verbatim}
\end{quote}
and this will produce a table, in this case Table~\ref{simple-table}.
The {\tt minipage} environment is required because \LaTeX\ interprets the {\tt tabbing}
environment as occupying the full page width, even if the text doesn't actually
use all that space.  The width argument, here {\tt 5cm}, is set to the width of the typeset
Haskell code.  If centering is not required, omit the {\tt center} and
{\tt minipage} environments.
The table can be referenced if it is labelled with the {\tt \char'134 label}
command, as above, and can be referred to in the text by using the code
{\tt Table\char'176 \char'134 ref\char'173 output-table\char'175} which will
keep the table number consistent with the numbering of the chapter and other tables.
\begin{table}
\begin{center}
\begin{minipage}{5cm}
\input{LaTeX_simple}
\end{minipage}
\end{center}
\caption{Typeset code in a table} \label{simple-table}
\end{table}
Similarly, the {\tt figure} environment can be used.  The code is
\begin{quote}
\begin{verbatim}
\begin{figure}
\begin{center}
\begin{minipage}{5cm}
\input{output}
\end{minipage}
\end{center}
\caption{Typeset code in a figure} \label{output-figure}
\end{figure}
\end{verbatim}
\end{quote}
which produces a figure, in this case Figure~\ref{simple-figure}.
Again, it can be captioned and referenced, as with tables.
\begin{figure}
\begin{center}
\begin{minipage}{5cm}
\input{LaTeX_simple}
\end{minipage}
\end{center}
\caption{Typeset code in a figure} \label{simple-figure}
\end{figure}

The result, once included in the final document, may have too
much blank space under the typeset code such as is the case in
this next example.
\begin{quote}
\input{LaTeX_blankline}
\end{quote}
This means there were extra blank lines at the end of the input file, caused
by extra return characters.  This can be
rectified by removing the extra return characters and running {\tt pphs} again.

\subsection{Lengthy lines}

It is always possible that the lines of typeset Haskell code will run off
the right-hand edge of the user's page in the final document.  Where this happens,
it is necessary to edit the input file and re-run {\tt pphs}.  Be careful not to
change the parse of the program by wrongly indenting the second part of the line.

\section{User adjustments} \label{user-adj}

The user is able to have some say on what the output looks like.
This makes the program more flexible and doesn't dictate what a
Haskell program should look like when typeset.  There are two areas in which user
choice is allowed, other than the double colon symbol described in Chapter~\ref{wide-colons}.

\subsection{Typefaces}

The default settings for typefaces are bold for keywords, italics for identifiers and
roman for everything else that is not in the math typeface.  However, keywords, identifiers,
strings, comments and numbers may be in whatever typeface the user chooses.
This is done using the {\tt \char'134 def} command to redefine the typeface commands
used by {\tt pphs}.  These are {\tt \char'134 keyword}, {\tt \char'134 iden},
{\tt \char'134 stri}, {\tt \char'134 com} and {\tt \char'134 numb} respectively.

For example, to put all comments into typewriter font, use
{\tt \char'134 def\char'134 com\char'173 \char'134 tt\char'175} in
the document.  The scope of the declaration will be from the point of introduction to
the end of the document.  To cancel a redefinition, use {\tt \char'134 def} to
redefine it back to what it was originally.

The different typefaces available in \LaTeX\ are shown in Table~\ref{fonts}.
It should be noted that the emphatic typeface is just the same as italics, although
nesting emphatic sections will alternate between italics and roman.
\begin{table}
\begin{center}
\begin{tabular}{|c|l|} \hline
{\em code\/} & {\em meaning\/} \\ \hline
{\tt \char'134 bf} & {\bf Boldface} \\
{\tt \char'134 em} & {\em Emphatic\/} \\
{\tt \char'134 it} & {\it Italics\/} \\
{\tt \char'134 rm} & {\rm Roman} \\ \hline
\end{tabular} \hskip3mm \begin{tabular}{|c|l|} \hline
{\em code\/} & {\em meaning\/} \\ \hline
{\tt \char'134 sc} & {\sc Small Caps} \\
{\tt \char'134 sf} & {\sf Sans Serif} \\
{\tt \char'134 sl} & {\sl Slanted\/} \\
{\tt \char'134 tt} & {\tt Typewriter} \\ \hline
\end{tabular}
\end{center}
\caption{Typefaces available in \LaTeX } \label{fonts}
\end{table}

\subsection{Quote marks}

Two types of quote mark are redefinable, forwards quotes and escape quotes.
The default for both of them is ' but if it is wished to redefine one or
both of them, use the {\tt \char'134 def} with either {\tt \char'134 forquo}
or {\tt \char'134 escquo}.  For example, to make escape quotes be
printed as {\sf '} use {\tt \char'134 def\char'134 escquo\char'173 \char'134 hbox\char'173 \char'134 sf '\char'175 \char'175} in the document.

\section{Altering the output}

As {\tt pphs} produces code which is subsequently run through \LaTeX , it is possible
to alter the code before it is run through \LaTeX .  This is useful for correcting
mistakes made by {\tt pphs}.  However, it is recommended that only those experienced
in \LaTeX\ try this.