-
Notifications
You must be signed in to change notification settings - Fork 27
/
README
252 lines (201 loc) · 11.6 KB
/
README
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
This is version 2.13 of ``noweb'', a simple, extensible literate-
programming tool. noweb is available from the Github repository
https://github.com/nrnrnr/noweb, and it is mirrored by the
Comprehensive TeX Archive Network. It is distributed under the BSD-2
open-souce license. Other helpful information can be found on noweb's
home page at http://www.cs.tufts.edu/~nr/noweb.
The most convenient way to get noweb is to install it from a package;
the procedure for building noweb from source dates from 1989, and it is
both baroque and brittle. If you must build noweb from source, change
to the `src' directory and follow the instructions in the file INSTALL.
(Windows users, you're on your own, but you might find it useful to check
https://web.archive.org/web/20190415151640/http://www.jim-pettigrew.com/noweb/install.)
WHAT'S NEW IN VERSION 2.13
Version 2.13 fixes issues #24 and #26 at
https://github.com/nrnrnr/noweb/issues. Both were compatibility
issues with TeXlive 2022.
WHAT'S NEW IN VERSION 2.12
Version 2.12 now has a dual license: in addition to noweb's original
license, it is licensed under the BSD 2-clause license.
Version 2.12 no longer defines a getline() function, which conflicted
with a new POSIX standard. And it no longer uses the deprecated
tempnam(3).
Version 2.12 contains a number of enhancements to the sl2h program and
l2h filter, which convert from LaTeX to HTML. They now deal with
\suspend and \resume from \usepackage{mdwlist}, and they also convert
some TeX ligatures to HTML entities, most notably the -- and ---
ligatures. Thanks to Christian Lynbeck, 2.12 also has new Emacs Lisp
code that better supports font-lock. Other than that, 2.12 fixes a
number of bugs, the most notable of which is that the emacs noweb-mode
command is now compatible with Emacs 25 desktop-read and desktop-save.
INTRODUCTION --- WHAT IS NOWEB, ANYWAY?
noweb is designed to meet the needs of literate programmers while
remaining as simple as possible. Its primary advantages are
simplicity, extensibility, and language-independence. noweb uses 5
control sequences to WEB's 27. The noweb manual is only 3 pages; an
additional page explains how to customize its LaTeX output. noweb
works ``out of the box'' with any programming language, and supports
TeX, latex, and HTML back ends. A back end to support full hypertext
or indexing takes about 250 lines; a simpler one can be written in 40
lines of awk. Noweb does not prettyprint natively, but supports
prettyprinting through such third-party filters as pretzel and dpp.
noweb has been distributed free of charge for thirty years, and it is
one of the world's most widely used literate-programming tools. It
has been used for hundreds of thousands of lines of code in such
languages as awk, C, C++, Haskell, Icon, Lua, Modula-3, Objective
Caml, PAL, perl, Promela, and Standard ML.
If you already know you want to use noweb, you need only install it
and read the manual page. If you're just curious about noweb, read
the paper that appeared in the September 1994 issue of IEEE Software.
(If you can't get Software, send me a postcard and I'll send you a
reprint.) A nice, brief tutorial appeared in the October 1997 issue
of Linux Journal (but beware that chunk syntax is <<name>> and not <<name>).
If you're brand new to literate programming, check out the FAQ for the
USENET newsgroup comp.programming.literate. There are also some
resources available through the noweb home page:
http://www.cs.tufts.edu/~nr/noweb
WHAT YOU GET IN THIS DISTRIBUTION
This distribution contains the following directories:
binaries Pre-built distributions containing binaries and documentation
contrib software contributed by noweb users
examples sample noweb filters and programs in different languages
src Source code and documentation (including FAQ) for noweb
Where appropriate, these directories have README files of their own.
BINARY DISTRIBUTIONS MAY NOT ALWAYS BE UP-TO-DATE, especially DOS
distributions.
EXTENSIBILITY
noweb provides extensibility by using the Unix toolkit philosophy.
The ``noweb,'' ``notangle,'' and ``noweave'' commands are built from
pieces, which are then assembled in pipelines using shell scripts.
The pieces include:
markup convert noweb file from human syntax to tool syntax
unmarkup inverse of markup
totex convert from tool syntax to TeX/latex markup
tohtml convert from tool syntax to HTML markup
nt `tangle' the tool form of the noweb file
mnt discover roots, then act like nt
noidx insert indexing and cross-reference information
finduses finds uses of identifiers
These pieces are combined by the scripts in the src/shell directory to
provide more than just weaving and tangling:
noweb analog of nuweb
notangle analog of TANGLE
noweave analog of WEAVE
nountangle tangle, but keep interleaved documentation in comments
noroots print names of all root chunks in a noweb file
nocount count number of lines of code and documentation.
nodefs extract defined identifiers for noweave -indexfrom
noindex build an external index for multi-file documents
WEAVING --- A TAR PIT
The worst aspect of literate programming is the enormous amount of
time wasted wrangling over what ``woven'' output should look like.
Although noweb does no prettyprinting, it is not entirely immune---
several people have complained about noweave's output or have sent me
changes that add more options to noweave. I resisted for years, but
with version 2.5 I finally succumbed. I let the number of options to
noweave double, and I have provided for too many options and hooks for
customizing the latex output. I won't let it happen again.
noweb doesn't try to be all things to all programmers, but it is very
easy to change. If you don't like noweave's formatting, you can read
tex/support.nw to learn how to customize it; look for the words
``style hook.'' (Reading noweb.sty directly is not recommended.) For
simple formatting, it might be easier to throw away noweave and make
your own. To help you get started, the shell directory contains
noweave.simple, a simplified version of noweave that Dave Hanson
created for use with C programs (it can't handle code with @ signs).
The Noweb Hacker's Guide (xdoc/guide.tex) explains the intermediate
language that noweb uses to represent literate programs.
The intermediate language makes it possible to extend noweave with a
language-dependent prettyprinter, as shown by contributions of an Icon
prettyprinter by Kostas Oikonomou and a guarded-command prettyprinter
by Conrado Martinez-Parra. (I haven't written a prettyprinter myself
because my experience with Spider left me thinking that prettyprinting
is far more trouble than it's worth.) Further contributions of
prettyprinters are welcome.
noweb comes with two cross-referencers for use with noweave. The
standard one is written in Icon, because Icon offers excellent
functionality and performance. Because Icon is not available on all
platforms, I profide an alternative, but inferior cross-referencer
written in awk. See the INSTALL file for details.
Cross-referencing makes formatting even more of a tar pit; the
cross-referencer itself takes about 300 lines, and extensive LaTeX
support is also required. I haven't made the attempt to write
cross-reference code for plain TeX. Anyone who has ideas for reducing
the number of options or for other ways to restore sanity to the
situation is urged to write to [email protected].
INDEX AND IDENTIFIER CROSS-REFERENCE
Noweb creates identifier cross-references so that you can click on an
identifier and jump to its definition (if you're using printed LaTeX
output, a footnote gives you the page number of the definition).
To noweb, any string of nonwhite characters can be an identifier.
A human being or a language-dependent tool must mark definitions of
identifiers; noweb finds the uses using a language-independent
algorithm. The algorithm relies on an idea taken from the lexical
conventions of Standard ML. Characters are divided into three
classes: alphanumerics, symbols, and delimiters. If an identifier
begins with an alphanumeric, it must be delimited on the left by a
symbol or a delimiter. If it begins with a symbol, it must be
delimited on the left by an alphanumeric or a delimiter. If it begins
with a delimiter, there are no restrictions on the character
immediately to the left. Similar rules apply on the right-hand side.
The default classifications are chosen to make sense for commonly used
programming languages, so that noweb will not recognize `zip' when it
sees `zippy', or `++' when it sees `++:='. This trick works
surprisingly well, but it does not prevent noweb from spotting
identifiers in comments or string literals.
The basic assumption in noweb is that a language-dependent filter will
identify definitions automatically. Filters for Icon, TeX, and yacc
all take about 30 lines of Icon code and are included in the noweb
distribution; if you write a filter of your own, you can put it in the
$LIB directory with a name like `autodefs.pascal'. Try `noweave
-showautodefs' for a complete list of such filters.
If the automatic filter does not work well for you, or if there is no
filter available for your language, I recommend that you mark
definitions using backticks (`) in your source code, and use
`-filter btdefn' with both noweave and notangle.
noweave -index works well for short programs, but nodefs, noindex, and
noweave -indexfrom are there for large multi-file programs. See the
noindex man page for details.
NOTES
src/xdoc/techrep.* contains an early, almost unrecognizable version
of a paper describing noweb that appeared in IEEE Software in
September, 1994. You are probably better off writing me for a
reprint of the Software paper. (Send a postcard!)
The Noweb Hacker's Guide, which appears in src/xdoc/guide.*,
documents the representation of noweb files that is used by the
noweb tools, in case you want to write any tools of your own.
Simple tools (e.g. count the number of lines of interleaved
documentation) are trivial. If you write any tools, or you want
tools written (e.g. prettyprinters, index generators), let me know.
The icon directory contains Icon versions of most pipeline
stages. If you want to adapt noweb to work with a text processor
other than TeX or latex, they might provide a better starting point.
Perhaps the whole system should have been written in Icon from the
beginning, but I'm not going to do it over. Icon is available by
anonymous ftp from cs.arizona.edu.
Thanks to Preston Briggs for the Aho-Corasick recognizer, and for
helpful discussions.
Thanks to Dave Hanson for cpif.
Thanks to Dave Love for LaTeX wizardry.
Thanks to Joseph Reynolds for prodding me to fix [[...]].
Thanks to Bill Trost for the original HTML back end.
Thanks to Phil Bewig for the troff support.
Thanks to Philip Miller and Lee Wittenberg for DOS binaries.
Thanks to Paolo Ciccone for the Win32 binaries.
Thanks to Hubert Chathi for picking up the Debian distribution.
Send comments or questions to [email protected].
I enjoy hearing from noweb users; if you have enjoyed noweb, why not
send me a local postcard for my collection? My address is:
Norman Ramsey
Department of Computer Science
Tufts University
161 College Avenue
Medford, MA 02155
USA
COPYRIGHT
Noweb is copyright 1989-2018 by Norman Ramsey. All rights reserved.
You may use and distribute noweb for any purpose, for free. You may
modify noweb and create derived works, provided you retain the
copyright notice, but the result may not be called noweb without my
written consent. You may not sell noweb itself, but you may do
anything you like with programs created with noweb.