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 (!) 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

noweb

noweb

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:

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

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.

noweb

noweb

contrib

noweb

noweb

Norman Ramsey

Department of Computer Science, Halligan Hall

161 College Ave

Tufts University

Medford, MA 02155

USA

nr@cs.tufts.edu

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).

Acknowledgements

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.

Thanks to Alexandra Seremina of azoft for a Romanian translation of this page.

Copyright

Noweb

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