Noweb
Encyclopedia
noweb is a literate programming
tool, created in 1989–1999 by Norman Ramsey, and designed to be simple, easily extensible and language independent.
As in WEB
and CWEB
, the main components of noweb are two programs: "notangle", which extracts 'machine' source code from the source texts, and "noweave", which produces nicely-formatted printable documentation.
noweb supports TeX
, LaTeX
, HTML
, and troff
back ends and works with any programming language. Besides simplicity this is the main advantage over WEB
, which needs different versions to support programming languages other than Pascal. (Thus the necessity of CWEB
, which supports C
and similar languages.)
It uses LaTeX
code for documentation chunks, but you may easily use any form you like.
Code-chunks aren't treated specially by noweb's tools – they may be placed in any order and when needed, they are just concatenated, chunk-references in code are dereferenced and the whole requested source code is extracted.
A code-chunk consists of at least 3 lines: The declaration, the contents and the terminating @. Smaller chunks cannot be reduced onto single lines.
@
\section{Hello world}
Today I awoke and decided to write
some code, so I started to write Hello World in \textsf C.
<>=
/*
<>
*/
#include
int main(int argc, char *argv[]) {
printf("Hello World!\n");
return 0;
}
@
\noindent \ldots then I did the same in PHP.
<>=
/*
<>
*/
echo "Hello world!\n";
?>
@
\section{License}
Later the same day some lawyer reminded me about licenses.
So, here it is:
<>=
This work is placed in the public domain.
@
Assuming that the above code is placed in a file named 'hello.nw', the command to extract the human-readable document in HTML
format is:
... and in LaTeX
format:
To extract machine source code:
Literate programming
Literate programming is an approach to programming introduced by Donald Knuth as an alternative to the structured programming paradigm of the 1970s....
tool, created in 1989–1999 by Norman Ramsey, and designed to be simple, easily extensible and language independent.
As in WEB
WEB
WEB is a computer programming system created by Donald E. Knuth as the first implementation of what he called "literate programming": the idea that one could create software as works of literature, by embedding source code inside descriptive text, rather than the reverse , in an order that is...
and CWEB
CWEB
CWEB is a computer programming system created by Donald Knuth and Silvio Levy as a follow up to Knuth's WEB literate programming system, using the C programming language instead of Pascal....
, the main components of noweb are two programs: "notangle", which extracts 'machine' source code from the source texts, and "noweave", which produces nicely-formatted printable documentation.
noweb supports TeX
TeX
TeX is a typesetting system designed and mostly written by Donald Knuth and released in 1978. Within the typesetting system, its name is formatted as ....
, LaTeX
LaTeX
LaTeX is a document markup language and document preparation system for the TeX typesetting program. Within the typesetting system, its name is styled as . The term LaTeX refers only to the language in which documents are written, not to the editor used to write those documents. In order to...
, HTML
HTML
HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....
, and troff
Troff
troff is a document processing system developed by AT&T for the Unix operating system.-History:troff can trace its origins back to a text formatting program called RUNOFF, written by Jerome H. Saltzer for MIT's CTSS operating system in the mid-1960s...
back ends and works with any programming language. Besides simplicity this is the main advantage over WEB
WEB
WEB is a computer programming system created by Donald E. Knuth as the first implementation of what he called "literate programming": the idea that one could create software as works of literature, by embedding source code inside descriptive text, rather than the reverse , in an order that is...
, which needs different versions to support programming languages other than Pascal. (Thus the necessity of CWEB
CWEB
CWEB is a computer programming system created by Donald Knuth and Silvio Levy as a follow up to Knuth's WEB literate programming system, using the C programming language instead of Pascal....
, which supports C
C (programming language)
C is a general-purpose computer programming language developed between 1969 and 1973 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system....
and similar languages.)
Noweb's input
A noweb input text contains program source code interleaved with documentation. It consists of so-called chunks that are either code-chunks or documentation-chunks.It uses LaTeX
LaTeX
LaTeX is a document markup language and document preparation system for the TeX typesetting program. Within the typesetting system, its name is styled as . The term LaTeX refers only to the language in which documents are written, not to the editor used to write those documents. In order to...
code for documentation chunks, but you may easily use any form you like.
Code-chunks aren't treated specially by noweb's tools – they may be placed in any order and when needed, they are just concatenated, chunk-references in code are dereferenced and the whole requested source code is extracted.
A code-chunk consists of at least 3 lines: The declaration, the contents and the terminating @. Smaller chunks cannot be reduced onto single lines.
Example of a simple noweb program
This is an example of a "hello world" program with documentation:@
\section{Hello world}
Today I awoke and decided to write
some code, so I started to write Hello World in \textsf C.
<
/*
<
*/
#include
int main(int argc, char *argv[]) {
printf("Hello World!\n");
return 0;
}
@
\noindent \ldots then I did the same in PHP.
<
/*
<
*/
echo "Hello world!\n";
?>
@
\section{License}
Later the same day some lawyer reminded me about licenses.
So, here it is:
<
This work is placed in the public domain.
@
Assuming that the above code is placed in a file named 'hello.nw', the command to extract the human-readable document in HTML
HTML
HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....
format is:
noweave -filter l2h -index -html hello.nw | htmltoc > hello.html... and in LaTeX
LaTeX
LaTeX is a document markup language and document preparation system for the TeX typesetting program. Within the typesetting system, its name is styled as . The term LaTeX refers only to the language in which documents are written, not to the editor used to write those documents. In order to...
format:
noweave -index -latex hello.nw > hello.texTo extract machine source code:
notangle -Rhello.c hello.nw > hello.cnotangle -Rhello.php hello.nw > hello.php