1 files changed, 262 insertions, 0 deletions
diff --git a/ghc/CONTRIB/pphs/docs/Uses.tex b/ghc/CONTRIB/pphs/docs/Uses.tex
new file mode 100644
index 0000000000..c488bb4263
--- /dev/null
+++ b/ghc/CONTRIB/pphs/docs/Uses.tex
@@ -0,0 +1,262 @@
+\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.
+\ No newline at end of file