% $Id: report-intro.tex,v 1.4 1995/04/20 12:02:04 gaertner Exp gaertner $
%
% $Log: report-intro.tex,v $
% Revision 1.4  1995/04/20  12:02:04  gaertner
% Typo solemly = solemnly
%
% Revision 1.3  1995/02/24  08:49:26  gaertner
% Changes first paragraph and introduced `execution' quote.
%
% Revision 1.2  1995/02/21  09:20:52  gaertner
% Changed \mkWEAVE to \pretzel.
%
% Revision 1.1  1995/02/21  09:17:42  gaertner
% Initial revision
%
%


\chapter*{Introduction}

\addcontentsline{toc}{chapter}{Introduction}

\begin{quote}

  ``Any programmer who fails to comply with the standard naming,
  formatting or commenting conventions should be shot.  If it so
  happens that it is inconvenient to shoot him, then he is to be
  politely requested to recode his program in adherence to the above
  standard.'' \cite{Ledgard77}

\end{quote}

\noindent Recently, when discussing an assignment in a course on
software engineering, the lecturer addressed the auditorium and
stressed the fact that he would reject any code that wasn't properly
indented.  This was very striking for me since I have never considered
proper indentation to be a major problem for any programmer. I always
had assumed that everybody was already doing so. But I was wrong.

Luckily, insufficient program formatting in this course didn't result
in any executions as the above quote might suggest. But this note
pointed to a problem that I have never been really aware of, possibly
because I have actually learned to write programs in a to date
non-standard way, i.e.~using a \WEB.

In common words a {\em web} is a fine net made by a spider to
catch insects. Since 1984, `\WEB' is also known as another name
for a {\em literate program}, a highly documented program
designated for the eye of a reader and not solemnly for execution
by a computer; \WEB s are meant to be {\em works of literature}.

This is the basicly new idea of {\em literate programming}, a
programming style first introduced by Donald E.~Knuth in
1984~\cite{Knuth:CJ-27-2-97}. This concept is a new attempt to promote
understandability and readability of a program's source code. With
this style, the programmer can be ``regarded as an essayist, whose
main concern is with exposition and excellence of style''. Instead of
writing a program sufficing the rigid rules of a compiler, the
programmer is free to choose the manner of presenting the ideas and
algorithms of his program. This change of attitude lifts normal
computer programs up to become \WEB{}s.

\index{Literate programming}
\index{Knuth, Donald E.}

To turn these ideas from theory to practice one needs special tools to
bypass the restrictions imposed by normal compilers. One of these
tools processes the \WEB\ and turns it into a well formatted, high
quality document (including proper indentation) that serves as a
source code documentation. A system routine performing this task is
usually referred to as a \WEAVE\ processor. This processor {\em weaves
  the web}, i.e.~it improves the appearance of the \WEB. In most
cases, \WEAVE{}ing is only the first step towards the final document:
The second step normally consists of using a professional typesetter
program to produce code for output devices such as high resolution
graphic displays or laser printers.

\index{weave@\WEAVE}
\index{Typesetters}

Normally \WEAVE\ not only enhances the readability of the informal
text (i.e.~commentary) in the \WEB; it also improves the
appearance of the formal text, i.e.~the small parts of source code
that are scattered all over the \WEB. This work is commonly called
{\em prettyprinting}. The prettyprinting of the source code is
normally the most intricate part of every \WEAVE\ program. This is
due to the fact that the problem of prettyprinting is highly
language dependent and that---being mostly a matter of personal
taste---prettyprinting has to follow a lot of small details to
make the output look nice. \WEAVE\ systems normally have a built
in prettyprinting algorithm designed by the program author that
reflects mainly his opinion of how to space instructions of the
underlying programming language.

\index{Prettyprinting}
\index{Personal taste}

\bigskip\noindent This paper states that together with the literate
program the way of prettyprinting should also be an input parameter to
a \WEAVE\ system. To enable this idea, the author has written a
program called \pretzel\ that automatically generates a prettyprinter
from a general description of the programming language to be
prettyprinted. In this paper I will present this program and discuss
several issues related with the topic of prettyprinting, as well as
giving an overview of how this program may be used in future projects
on literate programming.

\index{pretzel@\pretzel}

This text follows a course that can be described as ``from theory to
practise''. It starts by giving a rather long and theoretical overview
over the area of prettyprinting (chapter \ref{one}) and then turns to
a more user orientated introduction to the \pretzel\ program (chapter
\ref{two}, the \pretzel\ user's manual). The end of the more abstract
part (chapter \ref{three}) is devoted to the issue of literate
programming and the role that \pretzel\ may play in it.

The more practical part is centered around a programmer's point of
view. It discusses the design of the \pretzel\ system (chapter
\ref{four}) and states future work that may be done to improve the
system (chapter \ref{five}). The most ``practical'' part follows in the
appendix where you actually will see parts of the program code,
i.e.~some specifications of \pretzel\ modules.
