Noweb

Noweb
Basisdaten
Erscheinungsjahr	1989
Aktuelle Version	2.12 (28. Juni 2018)
Betriebssystem	Plattform unabhängig
Programmier­sprache	C, Awk, und Icon
Lizenz	2-Klausel-BSD-Lizenz
http://www.cs.tufts.edu/~nr/noweb/

Noweb (Eigenschreibweise: noweb) ist ein Programmierwerkzeug für Literate programming, das in den Jahren 1989 bis 1999 von Norman Ramsey entwickelt wurde. Entwurfsziele waren Einfachheit, einfache Erweiterbarkeit und Sprachunabhängigkeit.

Wie in WEB und CWEB sind die Hauptkomponenten von noweb zwei Programme: „Notangle“, das aus den Quelltexten 'Maschinen'-Quelltext extrahiert, und „noweave“, das formatierte druckbare Dokumente produziert.

Noweb unterstützt TeX-, LaTeX-, HTML- und Troff-Backends und arbeitet mit jeder Programmiersprache. Außer Einfachheit ist dies der Hauptvorteil gegenüber WEB, das verschiedene Versionen benötigt, um andere Programmiersprachen als Pascal zu unterstützen. (Daher war CWEB notwendig, das C und ähnliche Sprachen unterstützt.)

Nowebs Input

Ein Noweb-Inputtext enthält Programmquellcode unterbrochen durch Dokumentation. Er besteht aus sogenannten Chunks, die entweder Dokumentations-Chunks oder Code-Chunks sind.

Ein Dokumentations-Chunk beginnt mit einer Zeile, die mit einem At-Zeichen (@) gefolgt von einer Leertaste oder einem Zeilenvorschub beginnt. Ein Dokumentations-Chunk hat keinen Namen. Dokumentations-Chunks enthalten normalerweise LaTeX, aber man kann auch HTML, einfaches TeX oder Troff verwenden.

Code-Chunks sind benamt. Ein Code-Chunk beginnt mit

<<chunk name>>=

in einer eigenen Zeile. Die doppelte linke spitze Klammer (<<) muss in der ersten Spalte stehen.

Jeder Chunk wird durch den Anfang des nächsten Chunks beendet. Wenn die erste Zeile einer Datei nicht den Anfang eines Chunks markiert, wird davon ausgegangen, dass sie die erste Zeile eines Dokumentations-Chunks ist.

Code-Chunks werden nicht besonders behandelt durch die Werkzeuge von Noweb; sie können in beliebiger Reihenfolge platziert werden und werden, wenn nötig, in richtiger Reihenfolge zusammengefügt. Chunk-Verweise im Code werden aufgelöst und der ganze erwünschte Quellcode extrahiert.

Beispiel eines einfachen Noweb-Programms

Dies ist das Beispiel eines einfachen „hello world“- Programms mit Dokumentation:

\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/>

Angenommen, der vorstehende Code befindet sich in einer Datei namens hello.nw, dann lautet der Befehl, ihn in ein menschenlesbares Dokument im HTML-Format zu extrahieren:

noweave -filter l2h -index -html hello.nw | htmltoc > hello.html

htmltoc fügt ein Inhaltsverzeichnis („table of content“) hinzu.

… und ins LaTeX-Format:

noweave -index -latex hello.nw > hello.tex

Um den Quellcode zu extrahieren:

Zuerst den C-Code:

notangle -Rhello.c hello.nw > hello.c

… dann PHP:

notangle -Rhello.php hello.nw > hello.php

Und nun das Ganze 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/>

HTML extrahieren (und Inhaltsverzeichnis erzeugen) durch

noweave -index -html hello-html.nw |htmltoc > hello.html

Kompatibilität

Noweb legt ein bestimmtes Dateiformat fest und eine Datei verschachtelt wahrscheinlich drei verschiedene Formate (Noweb, LaTeX und die verwendete Programmiersprache). Dies wird durch andere Softwareentwicklungswerkzeuge nicht verstanden und konsequenterweise schließt die Verwendung von Noweb den Gebrauch von UML oder Codedokumentationswerkzeugen aus.

Weblinks

• Offizielle Website
• Norman Ramseys Homepage
• noweb.py – ein freier Noweb-Klon geschrieben in Python
• noweb.php – Noweb-Klon in PHP