ghc/CONTRIB/pphs/docs/UserGuide_Text.tex

   1 \sect{User guide to {\tt pphs}}
   2
   3 The program {\tt pphs} typesets programs in the Haskell programming
   4 language for use with the \LaTeX\ intensional text formatting
   5 and typesetting system.  It takes
   6 as input a file containing a Haskell program and produces \LaTeX\
   7 code to {\tt stdout}.  There are various different features of this
   8 process.
   9
  10 \subsect{Left indentation}
  11
  12 It is in the nature of Haskell programs that indentation is heavily used.  As the
  13 indentation is vital to the parsing of the program, any attempt at typesetting
  14 Haskell code must replicate this indentation.  Take, for example, the following piece of code.
  15 \begin{quote}
  16 \input{Haskell_leftindent2}
  17 \end{quote}
  18 Note how the third, fifth and sixth lines start at different levels of indentation.
  19 The {\tt pphs} program produces the correct \LaTeX\ code to align these under the
  20 correct position in the preceding lines once typeset.  It also selects the correct
  21 line to line up under.  Note how the sixth line does not line up
  22 under its predecessor, but under the fourth line.
  23 The code necessary to typeset this is produced, preserving the parsing
  24 order.  Once typeset, it will look like this:
  25 \begin{quote}
  26 \input{LaTeX_leftindent2}
  27 \end{quote}
  28 Note that this
  29 example of possible input had no `extra' typesetting commands.
  30
  31 A line of Haskell code may be indented beyond the end of its predecessor.
  32 Here, {\tt pphs} aligns it with whichever line it is lined up underneath in the
  33 original file, or, if longer than any preceding line, inserts space to correspond
  34 to that in the input file.
  35
  36 \subsect{Internal alignment}
  37
  38 Another form of alignment used in Haskell is {\em internal alignment}.  This is where
  39 there is vertical alignment of columns other than at the left-hand edge of the
  40 Haskell code.  This is typically characterised with a column of the same character
  41 appearing in the program code, and it is this case, along with a
  42 special case, that {\tt pphs} recognises for internal alignment having occurred.
  43 \begin{quote}
  44 \input{Haskell_internalalign1}
  45 \end{quote}
  46 In this example, see how the {\tt =} signs line up, one below the other.  This makes
  47 the program more readable, although it does not affect the parsing of the program.
  48 As the purpose of {\tt pphs} is to make Haskell programs even more readable, it
  49 retains this alignment.  This example would be typeset to produce the following:
  50 \begin{quote}
  51 \input{LaTeX_internalalign1}
  52 \end{quote}
  53 The special case for internal alignment is a $=$ aligned under a $::$.
  54 This will cause the same effect as would have happened if they were the same
  55 character.
  56
  57 \subsect{Token highlighting}
  58
  59 To increase the readability of Haskell programs, {\tt pphs} allows various tokens
  60 to be highlighted.  By using different typefaces for some pieces of code, this
  61 distinguishes them from the rest.  The user can specify the details of
  62 the highlighting, but the default settings are {\bf bold} for
  63 keywords, {\it italics} for identifiers and {\rm roman} for everything else.
  64 Strings, comments and numbers are also highlightable.
  65
  66 Note that in the previous example, the keywords {\bf instance} and {\bf where}
  67 are highlighted in bold, whereas the various identifiers are in italics.
  68
  69 \subsect{Mathematical symbols}
  70
  71 Rather than simply replicate the ASCII approximations of mathematical symbols
  72 used in Haskell, {\tt pphs}
  73 substitutes the proper symbols in the output.  These are shown below.
  74 \begin{center}
  75 \begin{tabular}[t]{|c|c|} \hline
  76 {\em Haskell\/} & {\em Math\/} \\ \hline
  77 {\tt *} & $\times$ \\
  78 {\tt ++} & {\hbox{$+\mkern-7.5mu+$}} \\
  79 {\tt :+} & {:}{+} \\
  80 {\tt <=} & $\leq$ \\ \hline
  81 \end{tabular} \hskip3mm \begin{tabular}[t]{|c|c|} \hline
  82 {\em Haskell\/} & {\em Math\/} \\ \hline
  83 {\tt >=} & $\geq$ \\
  84 {\tt <-} & $\leftarrow$ \\
  85 {\tt ->} & $\rightarrow$ \\
  86 {\tt =>} & $\Rightarrow$ \\ \hline
  87 \end{tabular}
  88 \end{center}
  89
  90 \subsect{\LaTeX\ typesetting characters}
  91
  92 \LaTeX\ uses embedded typesetting commands, so {\tt pphs} has to ensure that if
  93 any of the characters used by \LaTeX\ appear in the input Haskell code, the correct
  94 \LaTeX\ code is outputted to typeset them, rather than have the characters interfere
  95 with the typesetting process.  The characters used by \LaTeX\ for typesetting are:
  96 \begin{quote}
  97 \(\#\ \$\ \%\ \&\ \char'176\ \_\ \char'136\ \hbox{$\setminus$}\ \hbox{$\cal \char'146\ \char'147$}\)
  98 \end{quote}
  99 The user of {\tt pphs} need not worry about using any of these characters in Haskell
 100 programs, as this will be dealt with by {\tt pphs} before \LaTeX\ gets to see the code.
 101
 102 \subsect{How to call it}
 103
 104 The program is called by typing {\tt pphs} followed by the name of
 105 the file containing the Haskell program to be typeset.  If the
 106 filename ends with a {\tt .hs} extension, this may be omitted,
 107 unless another file exists with the same name but no extension.
 108 When no extension is specified, the program will look for a
 109 filename with no extension before looking for a file with the
 110 {\tt .hs} extension.
 111
 112 For example, if the Haskell program was in a file called {\tt Haskell.hs},
 113 the program would be called by
 114 \begin{quote}
 115 \tt pphs Haskell.hs
 116 \end{quote}
 117 As the filename ends with a {\tt .hs} extension, the extension may be omitted, provided
 118 there is no file already existing called {\tt Haskell}.  If there is no such file
 119 \begin{quote}
 120 \tt pphs Haskell
 121 \end{quote}
 122 would produce the same effect as the original call.
 123
 124 As the program outputs to {\tt stdout}, the code produced may be
 125 directed to a file by using a {\tt >} symbol after the call, followed by
 126 the name of the file to contain the \LaTeX\ code produced by the
 127 program.  Continuing the above example, if the output code is to be in
 128 a file called {\tt Haskell.tex}, the call would now be
 129 \begin{quote}
 130 \tt pphs Haskell.hs > Haskell.tex
 131 \end{quote}
 132 It must be noted that if the file {\tt Haskell.tex} already exists, it must be
 133 renamed or removed before making this call.
 134
 135 There are three options that can be specified in the program call.
 136 If it is desired that double colon symbols should look like $:\,:$ rather than $::$,
 137 use {\tt -w} in the call.  The length of the tab characters in the input file can
 138 be specified with {\tt -t} followed by the length.  The default tablength is 8.
 139 If identifiers with subscripts are wanted, eg {\iden ident$_1$\/}, then use {\tt -s}.
 140 These are written in the Haskell file as {\tt ident\_1}.
 141
 142 If the length of the tabs are 4 and
 143 the wide double colons are required, the example call above would become as follows.
 144 \begin{quote}
 145 \tt pphs -t4w Haskell.hs > Haskell.tex
 146 \end{quote}
 147
 148 \subsect{What to do with the produced code}
 149
 150 Before including the \LaTeX\ code in the document, it is necessary
 151 to include definitions of the \LaTeX\ commands used by {\tt pphs}.
 152 This can be done simply by including the style file {\tt pphs.sty}
 153 by adding {\tt pphs} to the option list of the documentstyle
 154 command like thus:
 155 \begin{quote}
 156 \begin{verbatim}
 157 \documentstyle[12pt,a4,pphs]{article}
 158 \end{verbatim}
 159 \end{quote}
 160
 161 Once this has been done, the file containing the \LaTeX\ code
 162 of the Haskell program code can be included.  This is done
 163 using the {\tt \char'134 input} command.  If the \LaTeX\
 164 code is located in a file called {\tt Haskell.tex} then the
 165 command is:
 166 \begin{quote}
 167 \begin{verbatim}
 168 \input{Haskell}
 169 \end{verbatim}
 170 \end{quote}
 171 This can be used in various \LaTeX\ environments such as {\tt quote},
 172 {\tt figure} or {\tt table} to produce different effects. An example
 173 of possible code is:
 174 \begin{quote}
 175 \begin{verbatim}
 176 \begin{quote}
 177 \input{Haskell}
 178 \end{quote}
 179 \end{verbatim}
 180 \end{quote}
 181 See Lamport, L.,  {\em \LaTeX : A Document Preparation System\/}
 182 (Addison-Wesley, 1986) for more details.
 183
 184 \subsect{How to make adjustments to the output}
 185
 186 The {\tt pphs} program is flexible in that it allows user choice on some aspects
 187 of the appearance of the final result.  User choice is allowed in two areas, typefaces
 188 and qoute marks.
 189
 190 The default settings for typefaces are bold for keywords, italics for identifiers and
 191 roman for everything else that is not in the math typeface.  However, keywords, identifiers,
 192 strings, comments and numbers may be in whatever typeface the user chooses.
 193 This is done using the {\tt \char'134 def} command to redefine the typeface commands
 194 used by {\tt pphs}.  These are {\tt \char'134 keyword}, {\tt \char'134 iden},
 195 {\tt \char'134 stri}, {\tt \char'134 com} and {\tt \char'134 numb} respectively.
 196
 197 For example, to put all comments into typewriter font, use
 198 {\tt \char'134 def\char'134 com\char'173 \char'134 tt\char'175} in
 199 the document.  The scope of the declaration will be from the point of introduction to
 200 the end of the document.  To cancel a redefinition, use {\tt \char'134 def} to
 201 redefine it back to what it was originally.  The different typefaces available in \LaTeX\ are
 202 \begin{center}
 203 \begin{tabular}{|c|l|} \hline
 204 {\em code\/} & {\em meaning\/} \\ \hline
 205 {\tt \char'134 bf} & {\bf Boldface} \\
 206 {\tt \char'134 em} & {\em Emphatic\/} \\
 207 {\tt \char'134 it} & {\it Italics\/} \\
 208 {\tt \char'134 rm} & {\rm Roman} \\ \hline
 209 \end{tabular} \hskip3mm \begin{tabular}{|c|l|} \hline
 210 {\em code\/} & {\em meaning\/} \\ \hline
 211 {\tt \char'134 sc} & {\sc Small Caps} \\
 212 {\tt \char'134 sf} & {\sf Sans Serif} \\
 213 {\tt \char'134 sl} & {\sl Slanted\/} \\
 214 {\tt \char'134 tt} & {\tt Typewriter} \\ \hline
 215 \end{tabular}
 216 \end{center}
 217 It should be noted that the emphatic typeface is just the same as italics, although
 218 nesting emphatic sections will alternate between italics and roman.
 219
 220 Two types of quote mark are redefinable, forwards quotes and escape quotes.
 221 The default for both of them is ' but if it is wished to redefine one or
 222 both of them, use the {\tt \char'134 def} with either {\tt \char'134 forquo}
 223 or {\tt \char'134 escquo}.  For example, to make escape quotes be
 224 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.
 225
 226 \subsect{Altering the output}
 227
 228 As {\tt pphs} produces code which is subsequently run through \LaTeX , it is possible
 229 to alter the code before it is run through \LaTeX .  This is useful for correcting
 230 mistakes made by {\tt pphs}.  However, it is recommended that only those experienced
 231 in \LaTeX\ try this.