diff options
Diffstat (limited to 'web/tweb/tug95/paper.tex')
| -rw-r--r-- | web/tweb/tug95/paper.tex | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/web/tweb/tug95/paper.tex b/web/tweb/tug95/paper.tex new file mode 100644 index 0000000000..bccd4aab9a --- /dev/null +++ b/web/tweb/tug95/paper.tex @@ -0,0 +1,419 @@ +%%% ==================================================================== +%%% @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: *** |