ghc/CONTRIB/pphs/docs/External_Specification.tex

   1 \section{External specification}
   2
   3 The program is to be run in UNIX by typing {\tt pphs} followed by the
   4 filename containing the Haskell code requiring to be typeset.  This will
   5 produce the \LaTeX\ code to stdout.  If there is some error,
   6 a suitable error message is to be printed to stderr.  The user may, if
   7 desired, direct the output to another file by typing {\tt pphs infilename > outfilename}.
   8 In this case, any error messages must still go to the screen and not the file.
   9
  10 The input filename may be given in its entirety or the {\tt .hs} extension may be omitted.
  11 In the case where there are two files with the same name, except that one has the
  12 {\tt .hs} extension, to run the program on the file with the extension to its name
  13 the complete filename will be typed.
  14
  15 The output will consist of the \LaTeX\ code to produce the typeset Haskell
  16 code.  As this is to be made easily insertable into another \LaTeX\ document, the output
  17 will not contain any header information such as declarations or definitions.  These,
  18 however, can
  19 be contained in a style file which the user will include in their main document.
  20
  21 Keywords and identifiers are to be distinguished in the result as typeset.
  22 The default for keywords is to be boldface and for identifiers italics.
  23 Numbers not forming part of an identifier are to be in roman by default
  24 while math is to be used where appropriate.
  25
  26 Haskell uses ASCII characters and combinations of ASCII characters
  27 to substitute for mathematical characters not present on the
  28 keyboard.  Where this happens, the program is to replace the ASCII character(s)
  29 with the corresponding mathematical character using the special \LaTeX\ commands
  30 to generate them.  The single characters are:
  31 \begin{quote}
  32 \begin{tabular}[t]{@{}cc@{}}
  33 Haskell & Math\\
  34 {\tt *} & $\times$
  35 \end{tabular}
  36 \end{quote}
  37 The double characters are:
  38 \begin{quote}
  39 \begin{tabular}[t]{@{}cc@{}}
  40 Haskell & Math\\
  41 {\tt ++} & {\hbox{$+\mkern-7.5mu+$}}\\
  42 {\tt :+} & {:}{+}\\
  43 {\tt <=} & $\leq$\\
  44 {\tt >=} & $\geq$\\
  45 {\tt <-} & $\leftarrow$\\
  46 {\tt ->} & $\rightarrow$\\
  47 {\tt =>} & $\Rightarrow$
  48 \end{tabular}
  49 \end{quote}
  50
  51 The \LaTeX\ system uses special characters to aid with the typesetting.
  52 They are:
  53 \begin{quote}
  54 \(\#\ \$\ \%\ \&\ \char'176\ \_\ \char'136\ \hbox{$\setminus$}\ \hbox{$\cal \char'146\ \char'147$}\)
  55 \end{quote}
  56 These characters may
  57 appear in the input, so the program must generate the correct \LaTeX\ code to
  58 print them and
  59 avoid having them mess up the typesetting process.
  60
  61 As the output when typeset must have the same layout as the input, the program
  62 must get the linebreaks and indentation right.  As \LaTeX\ is primarily designed for normal
  63 text, it would ignore the linebreaks and indentation in the Haskell file.  Therefore
  64 the program must insert them using the correct typesetting commands.  In the case of
  65 linebreaks it must recognise where these occur, but for indentation it must also work out
  66 how much space needs to be inserted.
  67
  68 There are two types of indentation in Haskell programs: left-hand and internal.
  69 For the former, the program must work out what the start of the line is aligned
  70 under in the input file.  It then has to calculate how much space is required
  71 to get the line of text to line up with this in the output once typeset.
  72 Take, for instance, the following Haskell example input:
  73 \begin{quote}
  74 \begin{verbatim}
  75 foobar a b = c
  76            where
  77                c = (a, b)
  78 \end{verbatim}
  79 \end{quote}
  80 Notice that the {\tt w} of {\tt where} on the second line lines up
  81 under the {\tt =} on
  82 the first line.  Similarly, the {\tt c} on the third line is aligned under the
  83 final letter of {\tt where} on the second line.  The result as typeset must
  84 get the indentation correct like this:
  85 \begin{quote}
  86 \begin{tabbing}
  87 foobar a b = c\\
  88 \newbox\foo
  89 {\setbox\foo\hbox{foobar a b }\hskip\wd\foo}where\\
  90 {\setbox\foo\hbox{foobar a b wher}\hskip\wd\foo}c = (a, b)
  91 \end{tabbing}
  92 \end{quote}
  93
  94 For internal indentation, the program must first recognise where it has
  95 occurred.  It must then insert the correct amount of space to get alignment
  96 in the output.  As \LaTeX\ uses variable-width characters, extra space
  97 may be needed in lines preceding a line within an internal alignment section.
  98 This is necessary if a lower line which
  99 aligns in the input file is longer up to the alignment point,
 100 due to the variable-width characters, than its predecessors
 101 once it has been properly typeset.  For example:
 102 \begin{quote}
 103 \begin{verbatim}
 104 lilli  :: a
 105 wmwm   :: b
 106 \end{verbatim}
 107 \end{quote}
 108 becomes
 109 \begin{quote}
 110 \begin{tabular}[t]{@{}l@{\ }c@{\ }l}
 111 lilli & :: & a\\
 112 wmwm  & :: & b\\
 113 \end{tabular}
 114 \end{quote}
 115 Notice how {\tt lilli} is longer than {\tt wmwm} in the input file style
 116 using fixed-width font but shorter when using the variable-width font
 117 of the typeset output.