%  This was prepared at the request of Bart Childs by
%    Tom McCurdy and Clarissa Wilson.  It is a simple
%    introduction to WEB using John Krommes FWEB as the normal form.
%  PROCESS this and Newton but be careful about ftangle to
%    Newton.web for this document.
%  This will input Newton.f which will be page 7 and 8 of Intro
%    The form of Newton.f it inputs should have all occurrences of
%    consectutive blank lines changed to a single one!!!!!!
%    Also, edit the first line to avoid an overfull hbox
%  Early in Newton.web, there is an unusual addition of (see next line)
%  \pageno=10\contentspageno=9
%
%     *  *  *  *  *  *  *  *  *  *  *  *  *  F o n t s    *  *
\input verbatim.sty   %<<<<<=======   NOTICE
\nopagenumbers
\magnification=\magstephalf
\hsize=6.0truein \advance\hoffset by 0.25truein
%\font\title=cmbx10 scaled\magstep1
\font\title=cmbx10 scaled\magstephalf    % for \mag=\magstephalf
%\font\bigtt=cmtt10 scaled\magstep1
\font\bigtt=cmtt10 scaled\magstephalf   % for \mag=\magstephalf
\font\sc=cmcsc10
\font\eightrm=cmr8

%    *   *   *   *   *   *   *   *   *   *   Formatting   *  *
\nopagenumbers
\parskip=2truept plus 1truept minus 1truept
\headline={\ifnum\pageno=1 \hfil \else \header \fi}

\def\header{\ifodd\pageno \hfil\papertitle\hfil\rm\folio\else
                           \rm\folio\hfil\papertitle\hfil \fi}

%     *  *  *  *  *  *  *  *  *  *  *  *  *  Macro  Definitions  *  *
\def\papertitle{An Introduction to \web{}}
\def\WEB{{\bigtt WEB}}
\def\web{{\tt WEB}}
\def\TANGLE{{\tt TANGLE}}
\def\WEAVE{{\tt WEAVE}}
\def\FWEB{{\tt FWEB}}
\def\FTANGLE{{\tt FTANGLE}}
\def\FWEAVE{{\tt FWEAVE}}
\def\CWEB{{\tt CWEB}}
\def\Cee{{\rm C}}                  % Currently undefined
\def\Fortran{{\sc Fortran}}
\def\Ratfor{{\rm Ratfor}}        % Currently undefined
\def\cup{{\tt\char'040}}    % That cup thing from the typewriter font
\def\Bsl{{\tt\char'134}}
\newcount\itemcount
\def\beginitems{\par\bgroup\parskip1pt plus1pt\global\itemcount=0}
\def\enditems{\par\egroup}
\def\Item{\global\advance\itemcount by 1\item{\the\itemcount.}}
\def\BL{\item{$\bullet$}}
%   *  *  *  *  *  *  *  *  *  *  *  *  *  Paper Begins   *  *
\centerline{\title An Introduction to the \WEB{} Style of Literate Programming}
\bigskip

\line{\bf Literate Programming\hfil}
\bigskip

There is a great need to reduce the amount of time that programmers
spend maintaining code.  Programmers spend at least half
of their time trying to understand what code does [PaZv83].

In {\sl The Mythical Man-Month, \it Essays on Software Engineering,}
Brooks states:

{\narrower\hfuzz=2pt
\noindent{\bf Self-Documenting Programs}
\medskip\noindent
A basic principle of data processing teaches the folly of trying to
maintain independent files in synchronism.  It is far better to combine
them into one file with each record containing all the information
both files held concerning a given key.

Yet our practice in programming documentation violates our own teaching.
We typically attempt to maintain a machine-readable form of a program 
and an independent set of human-readable document, consisting of
prose and flow charts.

The results in fact confirm our teachings about the follow of separate
files.  Program documentation is notoriously poor, and its maintenance
is worse.  Changes made in the program do not promptly, accurately,
and invariably appear in the paper.

The solution, I think, is to merge the files, to incorporate the
documentation in the source program.  This is at once a powerful
incentive toward proper maintenance, and an insurance that the
documentation will always be handy to the program user.  Such
programs are called {\it self-documenting}.

\dots\par
}

A method of improving the readability of a code and merging the
documentation with the high level language source was developed by
Donald~E. Knuth at Stanford during his second writing of \TeX, the
typesetting system.  Knuth has termed this methodology {\it literate
programming} and can be thought of as ``instead of imagining that our
task is to instruct a computer what to do, let us concentrate rather on
explaining to human beings what we want a computer to do[Knuth84].''
In other words, a literate program should be thought of as a work of
literature rather than a set of instructions for a computer.

A literate program should have several characteristics.  These include
(but are not limited to):
\beginitems
\BL well-written documentation which is integrated with the code,
\BL well-presented code with indentation and extra vertical white space
  to emphasize blocks of code,
\BL optional typographical niceties like bold keywords, italic programmer
  supplied names, logical symbols (like $\ge$ instead of {\tt >=}), 
  {\tt.GE.}, \dots
\BL standard links to enable navigation of code and documentation including:
\itemitem{} table of contents,
\itemitem{} index of variables, comments, user flags, procedures,
  messages, \dots
\itemitem{} used-in and defined-in pointers for code fragments, macros, and
  subprograms,
\BL a source system which is sufficiently extensible to be tailored to the
  reader's desires or format(s) dictated by the application.
\enditems

Many of these characteristics should be available in an interactive
environment for the development of literate programs.  This environment
should also have some other features that are unique to the development
process.
\vfil\eject

\medskip
\line{\WEB\hfil}

Knuth implemented {\it literate programming} through the \web{} system
of structured documentation. Lins [Lin89] sums the concept in this
manner: \smallskip
\centerline{{\it literate programming}~=~{\it structured programming\/}~+
{\it structured documentation}}\smallskip
\noindent A \web{} document contains both source code and documentation.
\WEAVE{} produces the \TeX{} file from the \web{} source file.  \TeX{} can then
be used to create the typeset document.  To create a compilable source code
from a \web{} document, \TANGLE{} is used.  Knuth's version of \web{} was
developed for Pascal.  The remainer of this document will be based
upon a \Fortran{} \web{}.  Pages~7 and~8 are the resulting \Fortran{} code
and pages~9 through~16
are the formatted version of a {\it literate programming} example.

The combination of \WEAVE{} and \TeX{} produce a document which
appears more like a work of literature than the standard source file
listing. \WEAVE{} enhances the typeset out in many ways:
\beginitems
\Item The code will be like an annotated pseudo-code (both top-down and
  bottom-up code).
\Item All reserved words will be in {\bf boldface} and variable and
  function names will be in {\it italics}.
\Item \WEAVE{} will automatically line up and indent all statements
  ({\it i.e.} {\bf begin/end}, {\bf if-then-else}, loop constructs)
  regardless of the format of the source.
\Item Calls to named modules will contain a the
  module number where it was defined.  Named modules will contain the
  statement `{\eightrm This code is used in section \#}'\ where \# is
  the module number(s) that contain the call(s) to that specific named module.
\Item Boolean and relational operators will be replaced with their
  corresponding mathematical symbols. Boolean operators
  such as {\tt and} and {\tt or} are replaced by $\wedge$ and $\vee$,
  relational operators such as $<>$ and $>=$ are replaced by their
  mathematical equivalents $\not=$ and $\geq$.
\Item It contains a table of contents which lists each title of each
  part and chapter,  followed by the actual sections, and ending with an index
  and a list of sections names.
\Item \WEAVE{} automatically numbers modules sequentially in the order
  they appear in the \web{} source file.  Numbering the modules makes
  referencing code quicker and easier.
\Item Index entries include variable names, functions, keywords used in
  documentation, and forced entries.  Each entry will be referenced
  according to the module number in which it appeared.  Underlined
  numbers indicate the module where the variable or function was defined.
\Item \WEAVE{} will automatically number the pages and produce a page
  header which will contain the program title and the chapter title.
\enditems
\noindent\WEAVE{} will output the \TeX{} source file which will have
the same name as the \web{} source file but, with the extension of
{\tt .tex} instead of {\tt .web}.

Literate programming encourages programmers to write in a
logical order; however, compilers can not always handle code that is
``logical''  to humans.  To make the code readable to the compilier,
\TANGLE{} will replace the module calls with the actual module
definitions no matter where they appear in the program.
``Since the compilation
order of the code no longer dictates how the program is designed and
presented the resulting program is much more comprehensible and thus
will be more maintainable for the future.'' [Smith]  \TANGLE{} will
output the compiler compatible program source file, which will have
the same name as the \web{} file with a language dependent extension.

\vfil\eject

\web{} programs are coded in modules (also called sections).
A part (major module) begins a new train of thought or logical
grouping for a program.
Parts in the source code begin with an `{\tt @*}'
and cause a page break in the typeset output.
Each part title is included in the table of contents.  A chapter (an
emphasized module) will be a subdivision of a part and will begin with
`{\tt @*1}' (or 2, 3, \dots), but will not cause a page break.
A chapter title will be indented in the table of contents.
Modules begin with an `{\tt@\cup}' (\cup\thinspace-\thinspace$<$space$>$)
and will neither appear in the table of contents nor cause a page break.

All modules must contain at least one of three parts:  documentation,
defintions, and program code.  Ideally, each part of a module should be
no more than 25 lines (one screen for those who are not fortunate
enough to be using a workstation).  Modules should be subdivided
until their functionality is easily comprehensible. At times this may
violate the previous rule.
\medskip

\line{\bf Documentation Portion\hfil}

The documentation portion will be neatly typeset in paragraphs. Although no
knowledge of \TeX{} is required; the more \TeX{} a user knows the more
control a user will have over the output.  Most \TeX{} commands begin
with a backslash(\Bsl), the remaining commands are comprised of
infrequently used non-alphabetic characters. To print these characters
the character must be preceded by a `\Bsl'.
$$\vbox{\halign{&\quad\hfil#\hfil\cr
\TeX{} Command&\tt\Bsl\$&\tt\Bsl\#&\tt\Bsl\%&\tt\Bsl\&\cr
        Output&    \$&    \#&    \%&    \&\cr
}}$$

One advantage of using \TeX, especially for scientific programming, is
the ability to typeset mathematical formulas as they would appear in a
math textbook (see module~1, page~??).  \TeX{} switches from text mode to math
mode with the use of a `{\tt\$}' before and after the equation.
Displayed equations are delimited by a pair of dollar signs
({\tt\$\$}) before and after the equation.
$$\vbox{\halign{&\quad\hfil#\hfil\cr
\TeX{} Command &\tt\$x\_k\$&\tt\$x\^{}k\$&\tt\$\Bsl pi\$&
      \tt\$\Bsl sum x\_k \$&\tt\$\Bsl sqrt 5 \$&\tt\$\Bsl Delta \$\cr
         Output&  $x_k$&  $x^ k$&  $\pi$&  $\sum x_k$&
      $\sqrt 5$&  $\Delta$\cr
}}$$

For more mathematical symbols, see the \TeX book chapters 16-18.


In the documentation portion of a \web, a user may want to refer to
pieces from the code portion of the current module
({\it i.e.} variables, function names, reserved words, etc).
By placing the desired piece of code inside vertical bars ({\tt `|'}),
the user is escaping into code mode.  Each element within the
`{\tt|~|}' will be formatted as though it were in the code portion
and will appear in the index in the same format.

\medskip
\line{\bf Definition Portion\hfil}

Definitions are abbreviations for code to make the code more
comprehensible.  This will provide short cuts for the programmer, since
the abbreviation can be substituted instead of rewriting the code in full
each time it is needed.  Definitions begin with an `{\tt @d}', `{\tt @m}',
or an `{\tt@f}'.  This portion is rarely used by beginning users of the
\web{} system.

\vfil\eject

\line{\bf Code Portion\hfil}

Actual program code will appear in one of two type of modules: unnamed and
named.  The \web{} command to begin an unnamed module will be dependent
upon the version of \web{} that is being used.  the code portion of an
unnamed module begins with an `{\tt @a}'.  The names of `named modules'
are \TeX{} strings beginning an `{\tt @<}' and followed by an `{\tt @>=}'.
To reference the code defined in a named module, put the exact name inside
`{\tt @<}' and `{\tt @>}'.  This can occur in both named and unnamed modules.
{\bf Note}: Calls to named modules {\bf cannot} be recursive.

\TANGLE{} will take every reference to a module a substitute the
code that corresponds to the module name.  In addition, definition names
will be replace by the actual code that they represent. \medskip
\line{\bf \FWEB\hfil}
\FWEB{}  is an extension of Knuth's \web{} written by John Krommes at
Princeton University.  \FWEB{}  is different than most \web s in that it
is designed to handle more than one programming language.  Krommes'
\FWEB{}  incorporates Silvio Levy's \CWEB{}  and can also handle
\Fortran{} and \Ratfor{} (a \Cee-like modification of \Fortran).  The
default language for \FWEB{} is \Fortran{} (surprised?), but it is easy
to change to another language even within the same \web{} file. The
global language is defined before the first `{\tt @*}' (part): `{\tt @n}'
for \Fortran, `{\tt @r}' for \Ratfor, and `{\tt @c}' for \Cee. The global
language will be in effect throughout the web file. We mentioned that,
in Knuth's \web{}, unnamed modules begin with `{\tt@p}', in Krommes'
\FWEB{} unnamed modules begin with `{\tt@a}'.  This tells \FWEB{} that
the code portion of an unnamed module is about to begin.

\noindent
The following is an excerpt from {\tt Newton.web} and corresponds to
module~7 in the \WEAVE{}d output:
{\overfullrule0sp\hfuzz=2pt
\sublisting{Newton.web}{157}{170}
}

In the above excerpt on line {\tt 157} is the part title.  `{\tt@*}'
begins the new part and the title begins after the `{\tt*}' and ends at
the first period.  Titles should be descriptive yet fairly short as they
will appear as part of the headings found on each page of that part. The
following lines of text make-up the documentation portion.
Line {\tt 159} illustrates the use of \TeX's math mode.
In math mode, \TeX{} converts everything to algebraic symbols.  All
letters become variables and thus, words appear as products of the
characters contained in the word; therefore to prevent this we
will use the \TeX{}  command `{\tt \Bsl cos}'
({\it e.g.} without the `\Bsl', {\tt\$x~cos(x)\$}
would appear as `$x cos(x)$', instead of the desired `$x \cos(x)$').
Line {\tt 164} is an example of `code mode;' {\tt implicit\_none}
will appear as it will appear in the code portion.
In line {\tt 160}, \Bsl {\tt Fortran} is a
user-defined \TeX{} command.

\vfil\eject

As stated earlier the `{\tt @a}' begins the code portion of an unnamed
module.  Lines {\tt 165} - {\tt 168} contain names of modules that
will be included in the compilable \Fortran{} source file.  Though
modules can be defined in any order and any location in the \web{} file,
the \Fortran{} file will contain the expanded code in the same order as
the modules were used.  As \FTANGLE{} sees the name of a module it
substitues the name with the code that it represents.
\Fortran{} source code (created by \FTANGLE) is the
and the typeset output (created by \FWEAVE{} and \TeX{}) are included.
{\bf Notice, \it the \Fortran{} is not pretty\/}!
The first 7 lines of the \Fortran{}
file will contain comments inserted by \FTANGLE{}.  The following lines
are compilable \Fortran{} code.  \FTANGLE{} will find the first
`{\tt @a}' and output its module number on a comment line ({\it e.g.}
{\tt C*7:*}).  The next line is a comment showing the line number and
file name of the \web{} source file ({\it e.g.} {\tt *line 162 "Newton.web"}).
It will then copy the code as it appears in the \web{} file.  When it
encounters a call to a named module, it will find that module definition and
output its module number on a comment line ({\tt C*8:*}).  On the next
line it will output the line number of \web{} source file
and follow this with the actual code.
When a module expansion is complete, \FTANGLE{} will
output the module number from which it is exiting on a comment line
({\tt C*:8*}). In this case, there is further expansion of
the declarations from module~9 and then from module~13.
The process continues until all code is copied and/or modules
expanded.

The final part of the \web{} source file is the `{\tt @* Index.}'  This
causes the index to begin on a new page.  In addition, `Index' will
appear in the table of contents.  To add entries other than those
choosen by \FWEAVE, use `{\tt @\^{}name@>}' where name is the entry to add
to the index.  This is especially helpful for future maintenance issues
such as system and compiler dependencies.

For \FWEB{} users programming in \Cee{}, \FTANGLE{} adds one more option.
When a \Cee{} complier points out an error, the compiler will give you
the line number in the `{\tt .web}' file not the `{\tt .c}' file.
Using a debugger will also be easier with this feature.
This feature is due to the {\bf \#line} option in \Cee.

\line{\bf \FWEB{} Process\hfil}
\beginitems
\Item Create ASCII text file following the rules of \web.
 Declare global language before first `{\tt@*}' and have at least
one unnamed module.
\Item ``{\tt fweave filename}'' (filename.web)
\itemitem{a. }``{\tt tex filename}'' (filename.tex)
\itemitem{b. }``{\tt texsun filename.dvi}'' (to preview on a
SparcStation)
\itemitem{c. }``{\tt dvi\_ps filname.dvi}'' (to create a postscript file)
\itemitem{d. }``{\tt lpr -Plw$<$room\#$>$ filename.ps}'' (to print
typeset output on a postscript device)
\Item ``{\tt ftangle filename}'' (filename.web)
\itemitem{a. }``{\tt f77 filename}'' (filename.f -- in UNIX)
\itemitem{b. }``{\tt filename}'' (to execute file)
\enditems

\vfil\eject

\centerline{\bf REFERENCES}
\medskip

{\leftskip=3.0truecm \parindent=-2.0truecm\parskip2pt plus1pt minus1pt

[Lin89] C.A. Lins, ``A First Look at Literate Programming,''
{\it Structured Programming}, vol. 10, no. 1, pp. 60-62.

[Knuth84] D.E. Knuth, ``Literate Programming,'' {\it The Computer
  Journal}, vol.~27, no.~2, pp.~97--111, May~1984.

[PaZv83]  G. Parikh and N. Zvegintov, {\it Tutorial on Software
Maintenance.} Silver Spring, MD: Computer Society Press, 1983.

[Smith] L. Smith, ``Measuring Complexity and Stability of \web{}
Programs,'' Masters Thesis, Oklahoma State University, 1990.
 \par}
\bigskip
\vfil\eject

\message{Is this a properly edited Newton.f?}
%  see the comments in the first of this file
\centerline{\bf Partial Listing of \tt Newton.f}
{\overfullrule0sp
\listing{Newton.f}
}
\vfil
\eject
\end


