Noweb — A Simple, Extensible Tool for Literate Programming

Literate programming is the art of preparing programs for human readers.

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's master distribution is here.

noweb has been used for fifteen 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

introduce literate programming with noweb. The article from Linux Journal is more elementary; the article in Software explains what makes noweb simple and extensible (and why those are important).

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 2012, I learned that there is no longer any Emacs mode that supports Noweb and really works with Emacs 23 or Emacs 24. The closest is Dave Love's mode, but it suffers from some serious problems related to "indirect buffers." Dave himself seems to have vanished from the Net.

Otherwise, nothing's new. 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 21 July 2011, the current supported version is version 2.11b.

WWW resources

Details and examples are available via WWW:

Literate programming and prettyprinting

As originally conceived by Don Knuth, literate programming involves prettyprinting code: displaying it using several fonts, mathematical symbols, and with stylized indentation and line breaks. I believe this treatment was inspired by the ``publication syntax'' of Algol 60. For three reasons, however, I myself seldom use prettyprinting: I do see a place for prettyprinting—prettyprinting can be helpful for archival programs that are read much more often than they are edited, e.g., if they appear in published books or journals. noweb supports prettyprinting through the use of ``prettyprinting filters,'' and there are several such filters in noweb's contrib directory, including one that I wrote, so this had better quash all rumors that I will never use a prettyprinter.

Getting in touch

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, Halligan Hall
  161 College Ave
  Tufts University
  Medford, MA 02155
               USA
You can also send electronic mail to nr@cs.tufts.edu.

Where to get noweb

For Linux users, I recommend getting the Debian package. For others, a gzipped tar file is available. 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).

Acknowledgements

Copyright

Noweb is copyright 1989–2011 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 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