ghc/CONTRIB/pphs/docs/What.tex

   1 \chapter{What {\tt pphs} does}
   2
   3 This chapter describes a program called {\tt pphs} which implements the typesetting
   4 requirements described in the previous chapter.  The description is from the user's viewpoint,
   5 later chapters going on to describe it from that of the programmer.
   6
   7 The {\tt pphs} program typesets Haskell programs for use with the \LaTeX\
   8 typesetting program.  It takes as input a file containing a Haskell
   9 program and produces the Haskell code to {\tt stdout}.  It is called by
  10 typing {\tt pphs}, followed by the name of the file containing the Haskell
  11 program.  For example, if the Haskell program was in a file called {\tt Haskell.hs},
  12 the program would be called by
  13 \begin{quote}
  14 \tt pphs Haskell.hs
  15 \end{quote}
  16
  17 If the filename ends with a {\tt .hs} extension, the extension may be omitted, provided
  18 there is no file already existing with the same name but with no extension.  If no
  19 extension is given with the filename when called, the program will look for a file of
  20 that name with no extension. If this is not found, the program will add a {\tt .hs}
  21 extension.  The above example, therefore, may be simplified to
  22 \begin{quote}
  23 \tt pphs Haskell
  24 \end{quote}
  25 unless the file {\tt Haskell} exists, in which case the original call must be made.
  26
  27 As the output of {\tt pphs} is to {\tt stdout}, it may be directed to a file by using
  28 the {\tt >} command after the call, followed by the name of the file to contain
  29 the \LaTeX\ code.  Continuing the above example, if the output code is to be put into
  30 a file called {\tt Haskell.tex}, the call would now be
  31 \begin{quote}
  32 \tt pphs Haskell.hs > Haskell.tex
  33 \end{quote}
  34 It must be noted that if the file {\tt Haskell.tex} already exists, it should be
  35 renamed or removed before making this call.
  36
  37 Two options are allowed with the call.  In the output, some people prefer \label{wide-colons}
  38 the {\tt ::} symbol to be written $:\,:$ rather than $::$.  To obtain the former, use
  39 {\tt -w} for wide colons.  A call on {\tt Haskell.hs} requiring wide colons would be
  40 \begin{quote}
  41 \tt pphs -w Haskell.hs
  42 \end{quote}
  43 When the input file's tab characters are not of the standard 8 spaces, this can be
  44 specified with the {\tt -t} command.  For example, if the tabs were 4 spaces long, type
  45 \begin{quote}
  46 \tt pphs -t4 Haskell.hs
  47 \end{quote}
  48 Both options can be used at the same time by calling
  49 \begin{quote}
  50 \tt pphs -t4w Haskell.hs
  51 \end{quote}
  52 or
  53 \begin{quote}
  54 \tt pphs -wt4 Haskell.hs
  55 \end{quote}
  56 Any positive integer can be specified for the tablength.
  57
  58 \section{Left indentation}
  59
  60 It is in the nature of Haskell programs that indentation is heavily used.  As the
  61 indentation is vital to the parsing of the program, any attempt at typesetting
  62 Haskell code must replicate this indentation.  Take, for example, the following piece of code.
  63 \begin{quote}
  64 \input{Haskell_leftindent1}
  65 \end{quote}
  66 Note how the third and fourth lines both start at different levels of indentation.
  67 The {\tt pphs} program produces the correct \LaTeX\ code to align these under the
  68 correct position in the preceding lines once typeset.  It also selects the correct
  69 line to line up under.  Note how, in the following example, the sixth line does not line up
  70 under its predecessor, but under the fourth line.
  71 \begin{quote}
  72 \input{Haskell_leftindent2}
  73 \end{quote}
  74 Again, {\tt pphs} produces the code necessary to typeset this, preserving the parsing
  75 order.  A line of Haskell code may be indented beyond the end of its predecessor.
  76 Here, {\tt pphs} aligns it with whichever line it is lined up underneath in the
  77 original file.  Note that these
  78 examples of possible input have no `extra' typesetting commands.
  79
  80 \section{Internal alignment}
  81
  82 Another form of alignment used in Haskell is {\em internal alignment}.  This is where
  83 there is vertical alignment of columns other than at the left-hand edge of the
  84 Haskell code.
  85 \begin{quote}
  86 \input{Haskell_internalalign1}
  87 \end{quote}
  88 In this example, see how the {\tt =} signs line up, one below the other.  This makes
  89 the program more readable, although it does not affect the parsing of the program.
  90 As the purpose of {\tt pphs} is to make Haskell programs even more readable, it
  91 retains this alignment.
  92
  93 \section{Token highlighting}
  94
  95 To increase the readability of Haskell programs, {\tt pphs} allows various tokens
  96 to be highlighted.  By using different typefaces for some pieces of code, this
  97 distinguishes them from the rest.  The user can specify the details of the highlighting as
  98 described in Section~\ref{user-adj}, but the default settings are {\bf bold} for
  99 keywords, {\it italics} for identifiers and {\rm roman} for everything else.  Strings,
 100 comments and numbers are also highlightable (see Section~\ref{user-adj}).
 101
 102 \section{Mathematical symbols}
 103
 104 Rather than simply replicate the ASCII approximations of mathematical symbols
 105 used in Haskell, {\tt pphs}
 106 substitutes the proper symbols in the output.  These are shown in Table~\ref{maths-sym}.
 107 \begin{table}
 108 \begin{center}
 109 \begin{tabular}[t]{|c|c|} \hline
 110 {\em Haskell\/} & {\em Math\/} \\ \hline
 111 {\tt *} & $\times$ \\
 112 {\tt ++} & {\hbox{$+\mkern-7.5mu+$}} \\
 113 {\tt :+} & {:}{+} \\
 114 {\tt <=} & $\leq$ \\ \hline
 115 \end{tabular} \hskip3mm \begin{tabular}[t]{|c|c|} \hline
 116 {\em Haskell\/} & {\em Math\/} \\ \hline
 117 {\tt >=} & $\geq$ \\
 118 {\tt <-} & $\leftarrow$ \\
 119 {\tt ->} & $\rightarrow$ \\
 120 {\tt =>} & $\Rightarrow$ \\ \hline
 121 \end{tabular}
 122 \end{center}
 123 \caption{Haskell ASCII approximations to mathematical characters} \label{maths-sym}
 124 \end{table}
 125
 126 \section{\LaTeX\ typesetting characters}
 127
 128 \LaTeX\ uses embedded typesetting commands, so {\tt pphs} has to ensure that if
 129 any of the characters used by \LaTeX\ appear in the input Haskell code, the correct
 130 \LaTeX\ code is outputted to typeset them, rather than have the characters interfere
 131 with the typesetting process.  The characters used by \LaTeX\ for typesetting are:
 132 \begin{quote}
 133 \(\#\ \$\ \%\ \&\ \char'176\ \_\ \char'136\ \hbox{$\setminus$}\ \hbox{$\cal \char'146\ \char'147$}\)
 134 \end{quote}
 135 The user of {\tt pphs} need not worry about using any of these characters in Haskell
 136 programs, as this will be dealt with by {\tt pphs} before \LaTeX\ gets to see the code.