Noweb
| Noweb | |
|---|---|
| Basic data
|
|
| Publishing year | 1989 |
| Current version | 2.11b |
| operating system | Platform independent |
| programming language | C , Awk , and Icon |
| http://www.cs.tufts.edu/~nr/noweb/ | |
noweb is a programming tool for literate programming , developed between 1989 and 1999 by Norman Ramsey. Design goals were simplicity, easy extensibility and language independence.
As in WEB and CWEB , the main components of noweb are two programs: " notangle ", which extracts 'machine' source code from the source code, and " noweave ", which produces formatted printable documents.
noweb supports TeX , LaTeX , HTML and Troff backends and works with every programming language. Besides simplicity, this is the main advantage over WEB, which requires different versions to support programming languages other than Pascal . (Hence, CWEB was necessary, which supports C and similar languages.)
Noweb's input
A noweb input text contains program source code interrupted by documentation. It consists of so-called chunks , which are either documentation chunks or code chunks .
A documentation chunk begins with a line that begins with an at sign (@) followed by a space bar or a line feed. A documentation chunk has no name. Documentation chunks usually contain LaTeX , but you can also use HTML , plain TeX, or Troff .
Code chunks are named. A code chunk begins with
<<chunk name>>=
on its own line. The double left angle bracket (<<) must be in the first column.
Each chunk is ended by the beginning of the next chunk. If the first line of a file does not mark the beginning of a chunk, it is assumed to be the first line of a documentation chunk.
Code chunks are not specially treated by the noweb tools; they can be placed in any order and, if necessary, put together in the correct order. Chunk references in the code are resolved and all the desired source code is extracted.
Example of a simple noweb program
This is the example of a simple "hello world" program with documentation:
\section{Hello world}
Heute wachte ich auf und beschloss zu coden.
Also begann ich mit einem Hello World in \textsf C.
<<hello.c>>=
/*
<<license>>
*/
#include <stdio.h>
int main(int argc, char *argv[]) {
printf("Hello World!\n");
return 0;
}
@
\noindent \ldots Dann machte ich dasselbe in PHP.
<<hello.php>>=
<?php
/*
<<license>>
*/
echo "Hello world!\n";
?>
@
\section{License}
Dann erinnerte mich mein Anwalt an die Lizenz.
So, da ist sie nun:
<<license>>=
Copyright (C) 2012 Erika Mustermann
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
should have received a copy of the GNU General Public License along with this program.
If not, see <http://www.gnu.org/licenses/>
Assuming the above code is in a file called hello.nw , the command to extract it into a human-readable document in HTML format is:
noweave -filter l2h -index -html hello.nw | htmltoc > hello.html
htmltoc adds a table of contents (" t able o f c ontent").
... and in LaTeX format:
noweave -index -latex hello.nw > hello.tex
To extract the source code:
First the C code:
notangle -Rhello.c hello.nw > hello.c
... then PHP :
notangle -Rhello.php hello.nw > hello.php
And now the whole thing in HTML :
<h1>Hello world</h1>
<tableofcontents></tableofcontents>
<h2>Programme</h2>
<p>Heute wachte ich auf und beschloss zu coden.
Also begann ich mit einem Hello World in C.</p>
<<hello.c>>=
/*
<<license>>
*/
#include <stdio.h>
int main(int argc, char *argv[]) {
printf("Hello World!\n");
return 0;
}
@
<p>Dann machte ich dasselbe in PHP.</p>
<<hello.php>>=
<?php
/*
<<license>>
*/
echo "Hello world!\n";
?>
@
<h2>License</h2>
<p>Dann erinnerte mich mein Anwalt an die Lizenz.
So, da ist sie nun:</p>
<<license>>=
Copyright (C) 2012 Erika Mustermann
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
should have received a copy of the GNU General Public License along with this program.
If not, see <http://www.gnu.org/licenses/>
Extract HTML (and generate table of contents)
noweave -index -html hello-html.nw |htmltoc > hello.html
compatibility
noweb defines a certain file format and a file probably nests three different formats (noweb, LaTeX and the programming language used). This is not understood by other software development tools and consequently the use of noweb precludes the use of UML or code documentation tools.
Individual evidence
- ^ Website of Norman Ramsey, accessed December 29, 2012.