ghc/CONTRIB/pphs/docs/Introduction.tex

   1 \chapter{Introduction}
   2
   3 Documents, such as papers for publication, often include sections
   4 of program code.  These have to be specially typeset, as default
   5 typesetting modes are generally intended for plain prose.
   6 It is therefore useful to have a special-purpose system for typesetting
   7 programs for inserting into documents.
   8 Haskell \cite{Haskell-report} is a fairly new functional programming language and does not
   9 yet have a full range of tools available to use with the language,
  10 including one to do typesetting.
  11 The goal of this project, therefore, is to provide a tool to automatically
  12 typeset Haskell programs.
  13
  14 Many people use the \LaTeX\ system \cite{LaTeX-book}
  15 for typesetting.  This uses
  16 embedded typesetting commands in the input to arrange the typesetting.
  17 The typeset result has variable-width characters with a choice of
  18 font styles and sizes available.  The page-size, margins and layout
  19 are also controllable by the user.  Because \LaTeX\ is so widely used and
  20 so flexible, the tool to be created will be
  21 for use with the \LaTeX\ system.
  22
  23 Haskell programs are generally written with editors that produce ASCII
  24 text.  This has fixed-width characters and one plain font.
  25 Indentation and vertical alignment are simple because
  26 fixed-width characters line up in columns, one below the other.
  27 Haskell avoids having compulsory expression terminators
  28 by using such indentation to delimit expressions.  It is thus crucial
  29 that this indentation is retained when the text is typeset.
  30
  31 The \LaTeX\ system, however, uses variable-width characters, so the indentation
  32 level becomes dependent on the characters under which the text is aligned.
  33 The tabs and spaces that went to make
  34 up the indentation in the original file have to be replaced with a
  35 suitable amount of space to make the text line up with the position
  36 it is aligned with in the original file.
  37
  38 It is also desirable to have formatting improvements, such as
  39 highlighting keywords and identifiers, as well as to have
  40 proper mathematical characters inserted in place of the
  41 Haskell ASCII approximations.  A tool could do this as well.
  42
  43 Currently the only way of typesetting Haskell program code is to
  44 labouriously insert formatting
  45 commands into the text by hand.  The alternative is to print out the programs
  46 verbatim with a plain ASCII-style fixed-width font, but it would be far better
  47 if there were a tool to do the proper typesetting.
  48
  49 \subsection*{Goals}
  50
  51 The proposed tool is required to comply to the following requirements:
  52 \begin{itemize}
  53 \item The program must take a file with a Haskell program in it and produce
  54 \LaTeX\ code to stdout.  This code must produce the input Haskell program in
  55 typeset style when run through
  56 the \LaTeX\ program.  The typeset result must be recognisable as having the same
  57 layout as the input file's Haskell program had.
  58
  59 \item The typeset result must preserve the parse of the program.
  60
  61 \item The input file will contain only Haskell code.  Any documentation in the file
  62 will be in the form of comments.
  63
  64 \item The input file will not have any embedded typesetting commands, so
  65 the program must analyse the input and decide for itself what needs to be
  66 done to produce the correct \LaTeX\ code.
  67
  68 \item The \LaTeX\ code produced must be easy to incorporate into a \LaTeX\
  69 document such as a paper or book.  Thus the produced code must be able
  70 to be incorporated into documents of different page and font sizes.
  71
  72 \item Keywords and identifiers must be highlightable so as to distinguish
  73 them from the rest of the Haskell program.
  74 The user should be allowed some choice in the typeface used for
  75 highlighting.
  76
  77 \item Proper mathematical symbols must replace ASCII approximations in the
  78 typeset output.
  79
  80 \item The program must accept as input
  81 a file of any name and thus not use an inflexible built-in filename.
  82
  83 \item The program must be in keeping with conventional UNIX style to fit in with
  84 Haskell and \LaTeX , which are also run under UNIX.
  85 \end{itemize}
  86
  87 \noindent This report describes a program written to satisfy these needs.
  88
  89 \subsection*{Background}
  90
  91 Haskell, being a functional programming language, uses functions as its
  92 sole means of programming.  This is unlike traditional programming
  93 languages such as C or Pascal, where assignments and procedures are also used.
  94 Haskell also does not normally use expression terminators, such as semi-colons,
  95 but instead relies on the layout of the
  96 program and, in particular, the indentation to determine the context of
  97 lines of code.  Lines of code are positioned so they are aligned under particular
  98 points on preceding lines, and this delimits expressions.  It is thus
  99 imperative that this indentation be replicated in any attempt to pretty-print
 100 the program code.
 101
 102 \LaTeX\ is a typesetting program that takes a file with embedded typesetting
 103 commands and produces a file containing typeset text.  This is commonly used when
 104 writing documents such as papers and books for publication.  Users of \LaTeX\
 105 can do many things, but anything fancy requires lots of typesetting commands to
 106 be embedded into the input file.  Thus typesetting a Haskell program in the
 107 desired way is a considerable task.  More simply, a
 108 Haskell program can be displayed in \LaTeX's verbatim mode, but this uses a fixed-width
 109 typewriter font.  Verbatim mode does not recognise tab characters, however these can be
 110 replaced with spaces.
 111
 112 It will be assumed that the user is familiar with Haskell and at least familiar with
 113 preparing basic textual documents with \LaTeX, although it is not required for the
 114 user to understand many of the more involved parts of typesetting with \LaTeX.
 115
 116 Already in existence is a program called `Phinew' written by Phil Wadler.
 117 This can be found in {\tt \char'176 wadler/bin}.  This required the user to supply
 118 typesetting commands embedded in their Haskell programs, meaning that the
 119 user would have to manually pre-process their Haskell code before using
 120 Phinew.  Although simpler
 121 than typesetting in \LaTeX, it is still better to have a program
 122 to do all the typesetting automatically, taking an unprepared Haskell
 123 program as input.
 124
 125 \subsection*{Outline}
 126
 127 In the remaining sections of this report the functionality of the program written
 128 are discussed; in particular, how all the various layout arrangements are dealt with.  The way
 129 in which the program goes about working out what to do is explained,
 130 along with descriptions of the algorithm and data-structures used.  Examples
 131 of the input and resulting output are used to illustrate the capabilities
 132 of the program.  The various possibilities for the user to decide what happens
 133 are explained, along with details on how to exploit them.  The user will
 134 need to know how to incorporate the results into a document so this
 135 is also explained.  Finally, the limitations and deficiencies of the
 136 program are detailed complete with an outline of further possible work
 137 which could rectify these problems and make the program more complete.