[linux-l] API-Doc vs. Literate Programming (war: Warum gibt es keine einheitliche Dokumentation?)

[Steffen Dettmer]

* Volker Grabsch wrote on Wed, Jan 03, 2007 at 05:32 +0100:
> On Wed, Jan 03, 2007 at 03:17:38AM +0100, Volker Grabsch wrote:
> > > http://en.wikipedia.org/wiki/Literate_programming
> > > 
> > > hat ein Beispiel a la:
> 
> Hier ist auch ein gutes Beispiel, mit dem bereits existierenden Tool
> "noweb" erstellt:
>     http://moonflare.com/code/select/index.php
> 
> Die select.nw-Datei ist die Quelle. Schau dir vorallem mal die
> generierte PDF-Datei an.

Guter Ansatz, vielversprechend, auf jeden Fall! 

Das PDF sieht erstaunlich gut aus! Aber nicht perfekt (z.B. im
Inhaltsverzeichnis mehrfach Seite 13, hätte ein Level weniger gereicht,
aber das weiss das noweb nicht automatisch). Warum vor 1 keine neue
Seite vor 2 aber schon? Komisch. Leider fehlen hyperlinks, Gelierung und
diese PDF Features (sieht mehr wie ein xvid-als-PDF aus :)). 

Auf Seite 3 ist eine überlange Zeile. Das sind diese Ausnahmen, die es
einem versauen. Sowas meinte ich. Besonders, wenn die Zeile nicht mehr
passt (hier kann man ja damit leben). Ich hab das immer bei $Header:$,
was immer zu lang ist :)

Es wird ganz schön mit whitespace rumgeaast. Wenn das nicht DIN-A4
sondern letter wird, wird dann reformatiert vom Tool oder sind die
Wechsel hart? Warum Kapitel 3 so komisch getrennt ist (der Rest auf
Seite 7? Der erste Abschnitt hätte mindestens noch auf Seite 6
gepasst!).

Der Mozilla formatiert das HTML IMHO auch nicht westenlich schlechter
zum Drucken (nur Inhalt etc fehlt natürlich, aber bei 5-10 Seiten geht
das ja).

Das meinte ich. Klar, man kann PDF automatisch erzeugen. Aber kein
schönes. Man sieht, dass es automatisch hingeknallt ist. Man möchte es
gar nicht drucken :-) Und das hier ist noch ein sehr gutes Beispiel, wo
nur Kleinigkeiten drin sind, aber es ist ja ein noweb-Beispiel (also,
ich denke, viel besser geht wohl auch nicht) und es verwendet schon ne
Menge Kram, der nach LaTeX aussieht...

oki,

Steffen

-- 
Dieses Schreiben wurde maschinell erstellt,
es trägt daher weder Unterschrift noch Siegel.