Noweb — A Simple, Extensible Tool for Literate Programming

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—especially noticeable when compared with other literate-programming tools. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 4 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, HTML, and troff 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. The primary sacrifice relative to WEB is that code is seldom prettyprinted. Noweb is distributed from CTAN.

noweb has been used for thirty-five (!) years at many universities and industrial sites. It has been used for tens of thousands of lines of code in such languages as awk, C, C++, Haskell, Icon, Modula-3, Objective Caml, PAL, perl, Promela, R, Turing, and Standard ML. I maintain a list of people and projects that use noweb.

The articles

• Andrew L. Johnson and Brad C. Johnson. Literate programming using noweb. Linux Journal, 64-69, October 1997.
• Norman Ramsey. Literate programming simplified. IEEE Software, 11(5):97-105, September 1994.

The original Linux Journal article is marred by a serious printing error—the chunk syntax is <<name>> and not <<name> as shown in the article. This error is corrected in the Web version. The Software article is riddled with minor errors; send me a postcard and I'll happily send you a reprint with errors corrected.

This site is a member of the Literate Programming Web Ring:

Previous

Next

Next 5 Sites

Random Site

List Sites

What's new?

In 2018, I finally got my act together and released version 2.12. As part of that release, I put noweb on github.

I am using Noweb 3 every day, but I think the rationale for Noweb 3 has come and gone, and I doubt I will ever take it out of ``alpha'' stage or port it to Lua version 5.x, which it richly deserves.

Newcomers should know that versions numbered 2.x are mature and may be preferred to version 3. As of 28 June 2018, the current supported version is version 2.12.

WWW resources

• Noweb Frequently Asked Questions.
• The user documentation takes the form of Unix man pages, which are online.
• The One-Page Guide to Using Noweb with LaTeX is the place to go if you don't like reading documentation, or if you have trouble remembering what you've read.
• Example programs rendered in HTML, including hypertext links created automatically from the noweb source. Most have had their documentation chunks automatically converted from latex.
• Many kind people have sent postcards, which have been viewable online since April, 1998.
• One of noweb's greatest strengths is that you can begin by using a vanilla system, then gradually add extensions and customizations as needed, all without even recompiling. The Noweb Hacker's Guide explains how noweb works in sufficient detail for you to add new features. (An HTML version of the guide is available, but because it is converted automatically from latex source, it is not authoritative.) The extensibility strategy is sketched here.
• noweb's custom extensions include the ability to parse and manipulate nuweb files, and the ability to convert LaTeX to HTML. This nuweb program formatted with noweb tools shows off both.
• A separate page discusses noweb's indexing capability. Several idiosyncrasies arise because noweb is language-independent.
• The Lyx document processor, which provides a WYSIWYG interface but is compatible with LaTeX, has supported Noweb since March, 1999.
• Since Version 2.8a, the distribution has included Thorsten Ohl's noweb-mode for Emacs. Joe Kelsey has written a promising class for emacs mmm-mode, but it doesn't quite work out of the box yet.
• Felix Gaertner has built Pretzel, a prettyprinter generator that works with noweb.
• Sven Kloppenburg, a student of Felix's, has built Noerr, which rewrites error messages so that language implementations without #line can work nicely with noweb.
• Dan Schmidt has built dpp and fu, which help make noweb output look like CWEB, as well as a nifty outline mode for GNU emacs.
• Some ftp sites for noweb are listed below.
• Here are my near-term plans and wish list for improvements to noweb. You can also look at the plans for Noweb 3, or you can look at an older white paper on Noweb 3.
• Rob Partington has done some work on supporting cross-references in plain TeX.
• Noweb's liberal copyright is given below.

Literate programming and prettyprinting

• Most of my programs are edited at least as often as they are read, and it is distracting to have to switch between plain ASCII for editing and fancy fonts and symbols for reading. It is much better for the literate-programming tool to display the code almost exactly as written. (I do believe in typographical distinction for chunk names.)
• Prettyprinting is necessarily a language-dependent function, and I haven't got time to create pretty printers for each of the many languages I use.
• My experience with prettyprinting is that it tends to distract people from the real work of programming and writing. People spend lots of time tinkering with prettyprinters, trying to get the output just right.

Getting in touch

Where to get noweb

For Linux users, I recommend getting the Debian package. For others, try CTAN. I also tried to make a Red Hat RPM; I'd appreciate hearing if it works.

(Note to old-timers: noweb is still mirrored on CTAN, but since I first started distributing noweb in the early 1990s, our ideas of how to get things have changed—as have our ideas of what's big. In the bad old days, CTAN built zipped tar files on the fly to save disk space. Since the collapse of this service circa 2003, I no longer recommend getting noweb from CTAN.) Precompiled binaries for Debian and NetBSD 1.3.x (g) are available.

Jim Pettigrew has written installation instructions for Windows 7 (on top of mingw).

• 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 Aharon Robbins for making troff work (finally!).
• Thanks to Bill Trost for the original HTML back end.
• Thanks to Lee Wittenberg and Phil Miller for DOS binaries.
• Thanks to Lee Wittenberg and Carl Gregory for the nucleus of the One-Page Guide.
• Thanks to Garret Prestwood for the initial pipeline and buffer interfaces used in Version 3.

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 do anything you like with programs created with noweb. You may even sell noweb itself, for example, as part of a CD-ROM distribution, provided that what you sell is the true, complete, and unmodified noweb.

Without wanting to be elitist, the thing that will prevent literate programming from becoming a mainstream method is that it requires thought and discipline. The mainstream is established by people who want fast results while using roughly the same methods that everyone else seems to be using, and literate programming is never going to have that kind of appeal. This doesn't take away from its usefulness as an approach.                         —Patrick TJ McPhee