--- /dev/null
+\sect{User guide to {\tt pphs}}
+
+The program {\tt pphs} typesets programs in the Haskell programming
+language for use with the \LaTeX\ intensional text formatting
+and typesetting system. It takes
+as input a file containing a Haskell program and produces \LaTeX\
+code to {\tt stdout}. There are various different features of this
+process.
+
+\subsect{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_leftindent2}
+\end{quote}
+Note how the third, fifth and sixth lines 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 the sixth line does not line up
+under its predecessor, but under the fourth line.
+The code necessary to typeset this is produced, preserving the parsing
+order. Once typeset, it will look like this:
+\begin{quote}
+\input{LaTeX_leftindent2}
+\end{quote}
+Note that this
+example of possible input had no `extra' typesetting commands.
+
+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, or, if longer than any preceding line, inserts space to correspond
+to that in the input file.
+
+\subsect{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. This is typically characterised with a column of the same character
+appearing in the program code, and it is this case, along with a
+special case, that {\tt pphs} recognises for internal alignment having occurred.
+\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. This example would be typeset to produce the following:
+\begin{quote}
+\input{LaTeX_internalalign1}
+\end{quote}
+The special case for internal alignment is a $=$ aligned under a $::$.
+This will cause the same effect as would have happened if they were the same
+character.
+
+\subsect{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, 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.
+
+Note that in the previous example, the keywords {\bf instance} and {\bf where}
+are highlighted in bold, whereas the various identifiers are in italics.
+
+\subsect{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 below.
+\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}
+
+\subsect{\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.
+
+\subsect{How to call it}
+
+The program is called by typing {\tt pphs} followed by the name of
+the file containing the Haskell program to be typeset. If the
+filename ends with a {\tt .hs} extension, this may be omitted,
+unless another file exists with the same name but no extension.
+When no extension is specified, the program will look for a
+filename with no extension before looking for a file with the
+{\tt .hs} extension.
+
+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}
+As the filename ends with a {\tt .hs} extension, the extension may be omitted, provided
+there is no file already existing called {\tt Haskell}. If there is no such file
+\begin{quote}
+\tt pphs Haskell
+\end{quote}
+would produce the same effect as the original call.
+
+As the program outputs to {\tt stdout}, the code produced may be
+directed to a file by using a {\tt >} symbol after the call, followed by
+the name of the file to contain the \LaTeX\ code produced by the
+program. Continuing the above example, if the output code is to be in
+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 must be
+renamed or removed before making this call.
+
+There are three options that can be specified in the program call.
+If it is desired that double colon symbols should look like $:\,:$ rather than $::$,
+use {\tt -w} in the call. The length of the tab characters in the input file can
+be specified with {\tt -t} followed by the length. The default tablength is 8.
+If identifiers with subscripts are wanted, eg {\iden ident$_1$\/}, then use {\tt -s}.
+These are written in the Haskell file as {\tt ident\_1}.
+
+If the length of the tabs are 4 and
+the wide double colons are required, the example call above would become as follows.
+\begin{quote}
+\tt pphs -t4w Haskell.hs > Haskell.tex
+\end{quote}
+
+\subsect{What to do with the produced code}
+
+Before including the \LaTeX\ code in the document, it is necessary
+to include definitions of the \LaTeX\ commands used by {\tt pphs}.
+This can be done simply by including the style file {\tt pphs.sty}
+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}
+
+Once this has been done, the file containing the \LaTeX\ code
+of the Haskell program code can be included. This is done
+using the {\tt \char'134 input} command. If the \LaTeX\
+code is located in a file called {\tt Haskell.tex} then the
+command is:
+\begin{quote}
+\begin{verbatim}
+\input{Haskell}
+\end{verbatim}
+\end{quote}
+This can be used in various \LaTeX\ environments such as {\tt quote},
+{\tt figure} or {\tt table} to produce different effects. An example
+of possible code is:
+\begin{quote}
+\begin{verbatim}
+\begin{quote}
+\input{Haskell}
+\end{quote}
+\end{verbatim}
+\end{quote}
+See Lamport, L., {\em \LaTeX : A Document Preparation System\/}
+(Addison-Wesley, 1986) for more details.
+
+\subsect{How to make adjustments to the output}
+
+The {\tt pphs} program is flexible in that it allows user choice on some aspects
+of the appearance of the final result. User choice is allowed in two areas, typefaces
+and qoute marks.
+
+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
+\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}
+It should be noted that the emphatic typeface is just the same as italics, although
+nesting emphatic sections will alternate between italics and roman.
+
+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.
+
+\subsect{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
projects / ghc-hetmet.git / blobdiff