diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/noweb/README |
Initial commit
Diffstat (limited to 'web/noweb/README')
-rw-r--r-- | web/noweb/README | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/web/noweb/README b/web/noweb/README new file mode 100644 index 0000000000..0ba30b32cb --- /dev/null +++ b/web/noweb/README @@ -0,0 +1,244 @@ +This is version 2.12 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, look for http://www.jim-pettigrew.com/noweb/install.) + + +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 nr@cs.tufts.edu. + + +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 nr@cs.tufts.edu. + +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. |