%%% ====================================================================
%%%  @TeX-file{
%%%     author     = "W\l{}odek Bzyl",
%%%     version    = "1.03",
%%%     date       = "10 July 1995",
%%%     time       = "23:30:58 MET",
%%%     filename   = "Bzyl.tex",
%%%     checksum   = "14630 396 2096 14305",
%%%     address    = "Instytut Matematyki,
%%%                   Uniwersytet Gda\'nski
%%%                   Wita Stwosza 57
%%%                   80--952 Gda\'nsk, Poland",
%%%     email      = "matwb@halina.univ.gda.pl (Internet)",
%%%     abstract   = "Paper for TUG '95 meeting",
%%%  }
%%% ====================================================================
%%%
%%%   TeXing this file requires the following files:
%%% --------------------------------------------------------------------
%%%     TUGPROC.STY
%%%     TUGBOAT.STY
%%%     TUGBOAT.CMN
%%% --------------------------------------------------------------------

\input tugproc.sty

%%%
%%%   Local macros:
%%%

\def \footnoterule% footnote rule was to close to main text
     {\kern-2pt
      \hrule width 5pc \kern 1.6pt }

\def \nl {\hfill\break}

\let \mc=\ninerm
\font \xivss = cmss10 at 14pt

\def\UNIX{{\smc u\kern-.05em nix}\spacefactor1000 }
\def\MSDOS{{\smc MSDOS}\spacefactor1000 }

\def \CWEB {{\smc cweb}\spacefactor1000 }
\def \FWEB {{\smc fweb}\spacefactor1000 }
\def \NOWEB {{\tt noweb}\spacefactor1000 }
\def \TANGLE {{\tt T\kern-.025em ANGLE}\spacefactor1000 }
\def \WEAVE {{\tt WEA\kern-.05em VE}\spacefactor1000 }
\def \TWEB {{\tt \TeX-WEB}\spacefactor1000 }

\def \AWK {{\smc awk}\spacefactor1000 }
\def \C {{\smc c}\spacefactor1000 }
\def \flex {{\smc flex}\spacefactor1000 }
\def \Fortran {{\smc fortran}\spacefactor1000 }
\def \icon {{\smc icon}\spacefactor1000 }
\def \perl {{\smc perl}\spacefactor1000 }
\def \plain {{\tt plain}\spacefactor1000 }
\def \RCS {{\smc rcs}\spacefactor1000 }

\let \( = (
\let \) = )

{\makeactive\(
\gdef \enablemetacode
     {\AddToSpecialsGetOther{\catcode`\(=\other}%
      \makeactive\(%
      \def(##1)%
         {{\it\makeCtrlMspace\makespacespace##1\/}}}}
\enablemetacode
\everyverbatim = {\makeescape\!\enablemetacode\parindent=0pt}

\frenchspacing
\normalbottom
\nopunctuation
\def\mtgyear{1995}

%%%--------------------------------------------------------------------

\title * Literate plain source is available! *

\author     * W\l{}odek Bzyl *
\netaddress * matwb@halina.univ.gda.pl *

\abstract
When introduced, literate programming was synonymous
with \WEB, a system for writing literate Pascal programs.
Since then many different \WEB's,
aimed on particular programming language, were created.
Each \WEB\ is constructed of two separate parts.
One is called \TANGLE, the other \WEAVE.
Typically each part consists of just one program
performing many tasks---expands macros,
prettyprints code, generates and sorts an index etc.
This makes adaptation of the existing \WEB\ to another
language extremely difficult.

Other approach to literate programming is presented by
Norman Ramsey, the author of \NOWEB. He designed and
realized \TANGLE/\WEAVE\ pair as \UNIX\ pipes.
By extending and/or replacing parts of pipes with programs,
written in \AWK, \icon, \flex, \perl, \C, \TeX, \mf,
new tool could be created with relatively small effort.
%%%new profession: plumber
%%%see also: plume
For example, with \NOWEB, it was possible to create simple
\TWEB\ system by writing \AWK\ script and new \TeX\ format.
New system was applied for creation
of literate \plain\ source. Although the resulted file
is principally {\tt plain.tex} code interleaved with
documentation, borrowed mainly from \TB, it presents the
whole code from the different perspective. The documentation is
organized around the macros as they appear in the {\tt plain.tex}
rather than around the topics as in \TB.
This means that \WEB\ source is {\it not\/} a
user manual, even though many notions are explained there.
\endabstract


\article

\head * WEB for everyone? *

\subhead * \WEB\ is a powerful tool. *

\nl The strength of literate programs lies in their ability to
produce high-quality typeset documentation. The strength of
literate programming lies in allowing you to write code
where you are telling to humans what computer should do,
instead of telling to computer what should be
done. Obviously we are more efficient and precise when
communicate with humans than computers. Thus literate
programs are more easily written and maintained than
ordinary ones.
%%% \TeX/\mf/and friends were ported to every possible
%%% platform

\subhead * \WEB\ is a complex tool. *

\nl A literate program consists of pieces of documentation and
named chunks containing code and references to other chunks.
The pieces are arranged in order
which helps to explain \(and understand\) the program as a whole.
 \WEB\ consists of two processors: \TANGLE\ and \WEAVE.
\TANGLE\ is used for extracting a program by replacing one
named chunk by its definition. The process of replacement is
recursive. It continues until no named chunks remain.  From
one \WEB\ source many programs could be extracted \(this is
achieved by presenting \TANGLE\ with different chunks\).
   \WEAVE\ is used for converting \WEB\ markup into \TeX\
markup as described and coded in a separate format
file which handles numerous typographical details of typeset
documentation and provide support for typical tasks as
cross-referencing, preparation of indexes, bibliography.
Formats for long and short documents will be different.
To typeset converted file you will need \TeX\ running on
your system. Errors can creep in \TeX\ code. 
To get \TeX\ code working with other formats 
could end with a short trip into \TeX\ language
\(this will be needed if you plan your literate program to
form a part of article, report, or book\).


\bigskip

We learn by reading. Why not to read `literate books'.
There are a few such books already and more will appear.
We learn by writing too. Why not to try one of finished tools.
\C/\C++/\Fortran\ programmer could try \CWEB\ or \FWEB.
Programmers which write in other languages
could check {\tt CTAN:/tex-archive/web} directory.
If your language is not on the list, or you are not able to
express yourself with the style offered then
you are welcome in the province of those who build their
own tools.  This territory is growing fast due to efforts of
Norman Ramsey who established a base for creating simple and
extensible literate tools.


\head * Presenting a new tool \TeX-WEB *

N.~Ramsey was the first who attempted to create generic
--- not aimed for particular language --- literate tool.
Such a tool would be useless because its generality.
Key to usefulness of \NOWEB\ lies in extendibility.
The tasks for \TANGLE/\WEAVE\ were divided among stand-alone
programs.
To simplify tangling and weaving a front end was introduced.
It performs a kind of lexical analysis of the source,
task previously performed by both processors separately.
 The front end provided with \NOWEB\ is called {\tt markup}
because it marks each line of source as line of text, as
beginning/end of code/documentation, as definition/use of
named chunks, etc.%%%
\footnote{$^1$}{%%%-----------------------------------------
     There is {\tt unmarkup} which works in opposite way.
     I borrowed from \NOWEB\ two more programs:
        {\tt nt} \(tangle\) and 
        {\tt mnt} \(multiple tangle\).}


\subhead * \WEAVE *

\verbatim
markup foo.tw | web2tex > foo.tex
markup foo.tw | awk -f web2tex > foo.tex
\endverbatim
where the second command line is used on \MSDOS\ systems.
 With {\tt markup} as front end, \WEAVE\ was build as \AWK\
script {\tt web2tex}%%%
\footnote{$^2$}{%%%----------------------------------------
    To allow tangling many files at once {\tt web2tex} is 
    actually shell wrapper for the \AWK\ script.}
which reads marked source line by line
and performs actions attached to line type.
Most of the time it inserts a bunch of \TeX\ macros.

The format |tweb.sty| provides support for cross
references, indexes, and multicolumn output.
There you find macros |\chapter|, |\[sub[sub]]section|,
|\paragraph|,%%%
\footnote{$^3$}{%%%---------------------------------------
These macros should not be overused.
Usually the chunk name alone is a better choice.}
|\printcontents|, |\title|.

Index macros are inserted by |web2tex|.

\subhead * \TANGLE *

\verbatim
markup foo.tw | nt > foo.sty
markup foo.tw | nt -R'Chunk B' > foo.sty
markup foo.tw | mnt 'Chunk B' 'Chunk A'
\endverbatim
Here we have several possibilities. We can extract code
beginning from the chunk named `|<<*>>|', or
from the `|Chunk A|' \(see template file below\).
Finally, `|Chunk A|' and `|Chunk B|' could be simultaneously
extracted to the files with the same names.

\subhead * \tt\TeX *

\verbatim
tex foo.tex
makeindex -s dnd.ist -o foo.dnd foo.ddx
makeindex -s und.ist -o foo.und foo.udx
makeindex -s chn.ist -o foo.chn foo.chk
tex foo.tex
\endverbatim
Indexes are sorted by |makeindex|. Three very short style
files are provided due to different formatting of indexes.
\MSDOS\ |makeindx| breaks on large indexes.

\subhead * Sample {\tt Makefile} *

\nl To ease work with tools a simple |Makefile| is provided.
Write |make| on the command line, press {\tt Enter} key, and,
assuming that only one \TWEB\ file named |foo.tw| resides in
the current directory, the following lines will appear on a
terminal

\verbatim[\ruled]
        Weaving:  make foo.tex
       Tangling:  make foo.sty
         Texing:  make foo.dvi
 Making archive:  make archive
       Cleaning:  make clean or veryclean
\endverbatim
Many different conventions are used where to store files in
a file system. In the |Makefile| three variables are defined:
 |SCRIPTDIR| -- place for |web2awk| and other scripts 
 \(defaults to |BIN|\), 
 |INDEXDIR| -- place for index styles 
 \(defaults to |IDXSTY|\), 
 |MAKEINDEX| -- the name of makeindex program 
 \(defaults to |makeindex|\).


\subhead * Template of \TWEB\ source *

\nl The structure of \TWEB\ file will be shown on the example.
\medskip
\noindent File name: {\tt foo.tw}
\verbatim[\ruled]
\title{foo.tw -- template file}
\printcontents % if you want TOC
@
The skeleton of the file foo.tw
<<*>>=
<<Chunk A>>
<<Chunk B>>
@
Documentation for Chunk A.
<<Chunk A>>=
(!TeX! code / references to other chunks)
@
Documentation for Chunk B.
<<Chunk B>>=
(!TeX! code / references to other chunks)
\endverbatim

 Documentation chunks begin with the line that
starts with |@| followed by space or newline.
 Code chunks begin with |<<|Chunk name|>>=| on a line by itself.
 Chunks are terminated by the beginning of another chunk or
end of file.

\subhead * Making changes/updates *

\nl The change file mechanism is not needed in case of \TeX\
language.  Change files are used to incorporate system
dependent code into source file, but \TeX\ code is already
system independent. \TeX\ code could be only `format
dependent'.
 Another feature of format file is that it evolves with
time, yet some intermediate versions are used for
preparation of books, articles etc.  All these versions and
configurations must be kept well organized, otherwise you
are bound to be lost.  The Revision Control System is the tool that
assists with these tasks.
 With the \RCS\ it is possible, with small overhead,
 to preserve {\it all revisions}
 which evolved from given text document,
 merge changes made by others,
 compare different versions,
 keep log of changes.


\subhead * \RCS *

\verbatim
ci foo.tw !hfill (check-in last version!kern 1.25em)
co foo.tw !hfill (check-out last version!kern 1.25em)
co -r(rev) foo.tw
rlog foo.tw
rcsdiff -r(rev) foo.tw
rcsmerge -r(later!_rev) -r(earlier!_rev) foo.tw
\endverbatim
\medskip
\noindent When the first command is executed |foo.tw| is stored in
a {\it group file\/} \(with default name |foo.tw,v| on \UNIX\
machines, or |foo.tw%| on \MSDOS\) as new revision. 
 For each deposited revision |ci| prompts for log
message. The file |foo.tw| is deleted unless you say 
|ci -l foo.tw|.  The message |ci error: no lock set by (login)|
means that \RCS\ was configured with `strict locking feature'
enabled. Locking prevents overlapping modifications
if several users are working on the same file. This feature
is disabled with |rcs -U foo.tw|; it is unnecessary if only
owner of the file is expected to deposit revisions into it.

The next two commands are used to extract the latest, or the
specified revision from the group file.  
|rlog| is used to print log messages.
 With |rcsdiff| different revisions are compared.
|rcs foo.tw| compares the latest revision with the contents
of the working file. Differences between files are found by
the program |diff|; 
if you do not like the |diff| default output, change it by
passing appropriate switches to |rscdiff|.
The last command undoes the changes between revisions; the
file |foo.tw| will be overwritten. |rcsmerge| 
incorporates changes between two revisions into the
working file.
 Similar effect could be achieved
with a stand-alone program called |merge|.
If files to compare are |mine|, |older|, |yours|
then with the command
\verbatim
merge mine older yours
\endverbatim
|merge| tries to add to |main| the result of subtracting |older| from
|yours|; if overlap occurs i.e. both files |mine|
and |yours| have changes to the same segment of lines in
|older| then |merge| delimits the alternatives with
\verbatim
<<<<<<< mine
(lines in) mine
=======
(lines in) yours
>>>>>>> yours
\endverbatim
and writes above to |mine|. Now is up to you wich set of
changes you adopt. |merge -p ... | sends the result of
merging to the standard output.

To keep working directory uncluttered, all \RCS\ files are
usually stored in the subdirectory with the name |RCS|.
\RCS\ commands look first into this directory when searching
for files.


%%%\subhead * Errors *

%%%|\inputlineno = (number)|
%%%does not work in horizontal nor vertical mode.

\head * Concluding remarks *

It seems that \TeX\ language constitutes a good starting
point for exploring the idea of literate programming.  The
system is simple, because many features present in other
\WEB's are not needed. The system is extensible, which means
that it possible to try different styles and features.
 And finally, programs written in \TeX\ are not too long ---
{\tt plain.tex} is about 1000 lines of code --- which means
that you can print the documentation of real programs
yourself and share it with others.

For those who are convinced by the analysis above
I included literate source of {\tt plain.tex} -- a basic set of
macros for \TeX. Please read and enjoy.


\endarticle

Local Variables: ***
mode: text ***
fill-column: 60 ***
End: ***