summaryrefslogtreecommitdiff
path: root/web/tweb/tug95/paper.tex
blob: bccd4aab9a6ab71ce33d12b72a21f5dfa26cdbbb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
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: ***