ghc/CONTRIB/pphs/docs/Uses.tex

   1 \chapter{Uses for output}
   2
   3 This chapter describes how the output from {\tt pphs} can be used.  First,
   4 examples of the capabilities of {\tt pphs} are shown, then it is explained how
   5 the output is incorporated into \LaTeX\ documents, and how the user can alter
   6 the output using built in methods or by editing the output.
   7
   8 \section{Examples of output} \label{examples}
   9
  10 Up until now, only examples of input have been shown.  Let us now see what
  11 {\tt pphs} actually does to this input.  Take this earlier example.
  12 \begin{quote}
  13 \input{Haskell_leftindent2}
  14 \end{quote}
  15 This is how this code is typeset by {\tt pphs}.
  16 \begin{quote}
  17 \input{LaTeX_leftindent2}
  18 \end{quote}
  19 Probably the most obvious thing about the typeset code is the highlighting
  20 of the identifiers.  The reserved identifier or keyword {\keyword where} has been
  21 highlighted in boldface while all the other identifiers are in italics.
  22 The various symbols are in roman or math font as appropriate, these do not
  23 get put in italics.  Less obvious is the indentation.  Notice how the starts
  24 of the third, fourth and sixth lines all line up under {\iden state\/} on the
  25 second line, just like they do in the input.  Similarly, the start of the fifth
  26 line is under the $|$ on the fourth.  This demonstrates {\tt pphs}'s ability to
  27 recreate left indentation in \LaTeX.  But note how the $=$ on the sixth line does
  28 not align under the $|$ on the fifth as it does in the input.  This is because
  29 they are different characters and so {\tt pphs} does not recognise this as internal
  30 alignment.  The only special case made in this part of the program was for $::$ and $=$.
  31 Alignment would have occurred by coincidence had the preceding characters on both lines
  32 been of the same width.
  33
  34 To illustrate internal alignment, recall this earlier example.
  35 \begin{quote}
  36 \input{Haskell_internalalign1}
  37 \end{quote}
  38 This code gets typeset like this.
  39 \begin{quote}
  40 \input{LaTeX_internalalign1}
  41 \end{quote}
  42 Notice here how the $=$ signs are aligned in a column, despite being preceded
  43 be characters that may be of different widths.  This demonstrates the ability of
  44 {\tt pphs} to recreate internal alignment.  Notice also how the {\tt '} signs
  45 have been interpreted as primes.  This is because they are immediately preceded
  46 by identifiers.  The {\tt *} signs have been transformed into multiplication signs,
  47 while the {\tt =>} has been replaced with $\Rightarrow$.
  48
  49 Here is a new example, this time illustrating a comment and strings.
  50 \begin{quote}
  51 \input{Haskell_string1}
  52 \end{quote}
  53 This example gets typeset as follows.
  54 \begin{quote}
  55 \input{LaTeX_string1}
  56 \end{quote}
  57 Note how {\tt pphs} puts the correct inverted commas at each end of the strings
  58 and how the strings themselves and the comment are in roman typeface.
  59 The $=$ signs show internal alignment.
  60
  61 This next example demonstrates a comment, character quotes and the special case
  62 with internal alignment where {\tt =} are aligned under {\tt ::}.
  63 \begin{quote}
  64 \input{Haskell_char}
  65 \end{quote}
  66 Typeset, this becomes
  67 \begin{quote}
  68 \input{LaTeX_char}
  69 \end{quote}
  70 The comment is typeset in roman, as are the character quotes.  This example has
  71 the default double colon.  Using the {\tt -w} option, the colons can be positioned
  72 further apart as illustrated below.
  73 \begin{quote}
  74 \input{LaTeX_wide-colons}
  75 \end{quote}
  76 It is a matter of taste which is used.
  77
  78 \section{Incorporating output into \LaTeX\ documents}
  79
  80 The motivation behind typesetting Haskell programs was so they could be incorporated
  81 into \LaTeX\ documents.  This section describes how to do this with the output
  82 of {\tt pphs}.
  83
  84 \subsection{The style file} \label{style-file}
  85
  86 Before using the output generated by {\tt pphs}, it is necessary to incorporate the
  87 {\tt pphs.sty} style file (see Appendix~\ref{style-code}) into the document.
  88 This provides definitions of the non-standard
  89 commands produced by the program.  The use of the style file is announced
  90 by adding {\tt pphs} to the option list of the documentstyle
  91 command like thus:
  92 \begin{quote}
  93 \begin{verbatim}
  94 \documentstyle[12pt,a4,pphs]{article}
  95 \end{verbatim}
  96 \end{quote}
  97 Without {\tt pphs} in the option list, errors will occur when \LaTeX\ is run,
  98 unless all the non-standard commands used by {\tt pphs} have been defined elsewhere
  99 in the document.
 100
 101 \subsection{Including the output file}
 102
 103 To include the file containing the code output by {\tt pphs}, the \LaTeX\
 104 {\tt \char'134 input} command is used.  If the file containing the output is called
 105 {\tt output.tex} then the following command is used.
 106 \begin{quote}
 107 \begin{verbatim}
 108 \input{output}
 109 \end{verbatim}
 110 \end{quote}
 111 The code will appear at the left margin like this:
 112 \input{LaTeX_simple}
 113 This is useful for code listings.
 114
 115 By using various different \LaTeX\ environments, the typeset Haskell code
 116 can be arranged differently.
 117 To have the code indented like the examples in Section~\ref{examples}, the
 118 {\tt quote} environment should be used.  The code
 119 \begin{quote}
 120 \begin{verbatim}
 121 \begin{quote}
 122 \input{output}
 123 \end{quote}
 124 \end{verbatim}
 125 \end{quote}
 126 would produce
 127 \begin{quote}
 128 \input{LaTeX_simple}
 129 \end{quote}
 130 The {\tt table} environment can be used to put the typeset Haskell code
 131 into a table and also allows the code to be captioned.
 132 The table will appear at the top of the current or next page depending on what
 133 space is available in the document.  The \LaTeX\ code used to produce this is
 134 \begin{quote}
 135 \begin{verbatim}
 136 \begin{table}
 137 \begin{center}
 138 \begin{minipage}{5cm}
 139 \input{output}
 140 \end{minipage}
 141 \end{center}
 142 \caption{Typeset code in a table} \label{output-table}
 143 \end{table}
 144 \end{verbatim}
 145 \end{quote}
 146 and this will produce a table, in this case Table~\ref{simple-table}.
 147 The {\tt minipage} environment is required because \LaTeX\ interprets the {\tt tabbing}
 148 environment as occupying the full page width, even if the text doesn't actually
 149 use all that space.  The width argument, here {\tt 5cm}, is set to the width of the typeset
 150 Haskell code.  If centering is not required, omit the {\tt center} and
 151 {\tt minipage} environments.
 152 The table can be referenced if it is labelled with the {\tt \char'134 label}
 153 command, as above, and can be referred to in the text by using the code
 154 {\tt Table\char'176 \char'134 ref\char'173 output-table\char'175} which will
 155 keep the table number consistent with the numbering of the chapter and other tables.
 156 \begin{table}
 157 \begin{center}
 158 \begin{minipage}{5cm}
 159 \input{LaTeX_simple}
 160 \end{minipage}
 161 \end{center}
 162 \caption{Typeset code in a table} \label{simple-table}
 163 \end{table}
 164 Similarly, the {\tt figure} environment can be used.  The code is
 165 \begin{quote}
 166 \begin{verbatim}
 167 \begin{figure}
 168 \begin{center}
 169 \begin{minipage}{5cm}
 170 \input{output}
 171 \end{minipage}
 172 \end{center}
 173 \caption{Typeset code in a figure} \label{output-figure}
 174 \end{figure}
 175 \end{verbatim}
 176 \end{quote}
 177 which produces a figure, in this case Figure~\ref{simple-figure}.
 178 Again, it can be captioned and referenced, as with tables.
 179 \begin{figure}
 180 \begin{center}
 181 \begin{minipage}{5cm}
 182 \input{LaTeX_simple}
 183 \end{minipage}
 184 \end{center}
 185 \caption{Typeset code in a figure} \label{simple-figure}
 186 \end{figure}
 187
 188 The result, once included in the final document, may have too
 189 much blank space under the typeset code such as is the case in
 190 this next example.
 191 \begin{quote}
 192 \input{LaTeX_blankline}
 193 \end{quote}
 194 This means there were extra blank lines at the end of the input file, caused
 195 by extra return characters.  This can be
 196 rectified by removing the extra return characters and running {\tt pphs} again.
 197
 198 \subsection{Lengthy lines}
 199
 200 It is always possible that the lines of typeset Haskell code will run off
 201 the right-hand edge of the user's page in the final document.  Where this happens,
 202 it is necessary to edit the input file and re-run {\tt pphs}.  Be careful not to
 203 change the parse of the program by wrongly indenting the second part of the line.
 204
 205 \section{User adjustments} \label{user-adj}
 206
 207 The user is able to have some say on what the output looks like.
 208 This makes the program more flexible and doesn't dictate what a
 209 Haskell program should look like when typeset.  There are two areas in which user
 210 choice is allowed, other than the double colon symbol described in Chapter~\ref{wide-colons}.
 211
 212 \subsection{Typefaces}
 213
 214 The default settings for typefaces are bold for keywords, italics for identifiers and
 215 roman for everything else that is not in the math typeface.  However, keywords, identifiers,
 216 strings, comments and numbers may be in whatever typeface the user chooses.
 217 This is done using the {\tt \char'134 def} command to redefine the typeface commands
 218 used by {\tt pphs}.  These are {\tt \char'134 keyword}, {\tt \char'134 iden},
 219 {\tt \char'134 stri}, {\tt \char'134 com} and {\tt \char'134 numb} respectively.
 220
 221 For example, to put all comments into typewriter font, use
 222 {\tt \char'134 def\char'134 com\char'173 \char'134 tt\char'175} in
 223 the document.  The scope of the declaration will be from the point of introduction to
 224 the end of the document.  To cancel a redefinition, use {\tt \char'134 def} to
 225 redefine it back to what it was originally.
 226
 227 The different typefaces available in \LaTeX\ are shown in Table~\ref{fonts}.
 228 It should be noted that the emphatic typeface is just the same as italics, although
 229 nesting emphatic sections will alternate between italics and roman.
 230 \begin{table}
 231 \begin{center}
 232 \begin{tabular}{|c|l|} \hline
 233 {\em code\/} & {\em meaning\/} \\ \hline
 234 {\tt \char'134 bf} & {\bf Boldface} \\
 235 {\tt \char'134 em} & {\em Emphatic\/} \\
 236 {\tt \char'134 it} & {\it Italics\/} \\
 237 {\tt \char'134 rm} & {\rm Roman} \\ \hline
 238 \end{tabular} \hskip3mm \begin{tabular}{|c|l|} \hline
 239 {\em code\/} & {\em meaning\/} \\ \hline
 240 {\tt \char'134 sc} & {\sc Small Caps} \\
 241 {\tt \char'134 sf} & {\sf Sans Serif} \\
 242 {\tt \char'134 sl} & {\sl Slanted\/} \\
 243 {\tt \char'134 tt} & {\tt Typewriter} \\ \hline
 244 \end{tabular}
 245 \end{center}
 246 \caption{Typefaces available in \LaTeX } \label{fonts}
 247 \end{table}
 248
 249 \subsection{Quote marks}
 250
 251 Two types of quote mark are redefinable, forwards quotes and escape quotes.
 252 The default for both of them is ' but if it is wished to redefine one or
 253 both of them, use the {\tt \char'134 def} with either {\tt \char'134 forquo}
 254 or {\tt \char'134 escquo}.  For example, to make escape quotes be
 255 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.
 256
 257 \section{Altering the output}
 258
 259 As {\tt pphs} produces code which is subsequently run through \LaTeX , it is possible
 260 to alter the code before it is run through \LaTeX .  This is useful for correcting
 261 mistakes made by {\tt pphs}.  However, it is recommended that only those experienced
 262 in \LaTeX\ try this.