Noweb — A Simple, Extensible Tool for Literate Programming
Literate programming is the art of preparing programs for
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 fifteen years at many universities and
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
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> as shown in the
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:
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.
I am using
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
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.
Details and examples are available via WWW:
- 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
- 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
- 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
- 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
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
which rewrites error messages so that language implementations without
#line can work nicely with noweb.
Schmidt has built
dpp and fu,
which help make noweb output look like CWEB, as well as a nifty
mode for GNU emacs.
- Some ftp sites for noweb are
- 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
in plain TeX.
- Noweb's liberal copyright is given
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
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
I enjoy hearing from noweb users; if you have enjoyed noweb, why not
send me a local postcard for my collection? My address is:
- 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.
Department of Computer Science, Halligan Hall
161 College Ave
Medford, MA 02155
You can also send electronic mail to
For Linux users,
I recommend getting the Debian package.
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.)
NetBSD 1.3.x (g)
Jim Pettigrew has
instructions for Windows 7 (on top of mingw).
- Thanks to Preston Briggs for the Aho-Corasick recognizer, and for
- 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
- Thanks to Garret Prestwood for the initial pipeline and buffer
interfaces used in Version 3.
- Thanks to Alexandra Seremina of
azoft for a
Romanian translation of this page.
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