Sacrideo: Programming, Philosophy, &c.

ChezWEB: Hygienic Literate Programming

Aaron W. Hsu  <>

17 February 2012


Current Version
Threaded 64-bit Linux
64-bit Linux
User's Guide (CWEB)

ChezWEB is a Knuthian style WEB programming system that is very compatible with the CWEB syntax. However, it supports a number of interesting features that are not included in the CWEB system, including hygienic preserving named sections. This means that you can relocate code in a WEB document without actually breaking the scoping rules of the Scheme language. ChezWEB is written for Chez Scheme and runs on the latest versions.

ChezWEB provides a unique perspective on documentation and code, extending the idea that code and documentation should not be separate things, but rather, that a program should be written like an essay, with formal and informal elements. The latter is written in TeX, and the former is written in the formal language of choice, in this case, Chez Scheme. This means that updating documentation is not an external matter done after the fact, when the important points are probably all forgotten. Instead, documentation becomes a part of the code artifact, and you can more easily keep the two synchronized and accurate.

ChezWEB encourages you to document the important things, such as why you wrote the code you did, the high-level architecture, and the details about why certain things were necessary or not, rather than the what. By writing code in small, manageable sections, your code should become more obvious and more modular, leaving you free to document the ideas and reasons behind your code, rather than the code itself. Documentation and code become intertwined in an useful path that makes it easier for people to read and understand you code as they go through it.

Together with this fundamental element of literate programming, ChezWEB follows the WEB tradition by providing a host of other useful features such as cross-referencing and indexing that are done automatically. You can also insert your own index entries, making it easy to get a picture of your code in different forms. ChezWEB also generates a table of contents based on your code so that you can get a high-level over view in pretty format.

The output of ChezWEB is a print quality document that makes it easy to read through code.

Combined with the hygienic guarantees of the ChezWEB system, literate programming gives you the opportunity to create more reliable, and, importantly, more readable programs that are actually enjoyable to go through, rather than painful. ChezWEB provides the guarantees you expect from working in Scheme (hygiene and referential transparency) in ways that make it convenient to write non-trivial programs.

Take a look, we think you'll find literate programming an enlightening and fulfilling programming paradigm.

Getting Started

The best way to get started with ChezWEB is to download one of the binary packages listed in the side bar. From there, you can read the chezweb developer documenation and the CWEB manual, as well as install the binaries for ChezWEB without needing to compile anything.

You can use the source distribution with either Chez Scheme or Petite Chez Scheme, if you prefer, or if you do not see your machine type listed.