[linux-l] Warum gibt es keine einheitliche Dokumentation? (war: dwww)

[Detlef Lechner]

Hallo Volker,

Am Dienstag, den 26.12.2006, 01:04 +0100 schrieb Volker Grabsch:

> Detlefs letzte Mail hat mich zu weiteren Gedanken zum Thema freie
> Software & Dokumentation inspiriert. Mich würde interessieren, was
> ihr davon haltet und wie eure Erfahrungen so sind.
> 
> 
> On Mon, Dec 25, 2006 at 11:44:27AM +0100, Detlef Lechner wrote:
> > Ich möchte gern dwww benutzen, weil ich oft Dokumentation zu einem
> > Debian-Befehl nicht finde, weil sie sich auf meinem Rechner irgendwo
> > versteckt. Ich habe deshalb das Programmpaket dwww installiert.
> 
> Nunja, Debian versteckt die Doku nicht wirklich. Zunächst einmal hat
> *jedes* Paket eine Manpage. Das ist eine feste Regel, die jeder
> Debian-Maintainer zu befolgen hat. Hat der Software-Autor keine Manpage
> geschrieben, muss der Maintainer eine schreiben. (mit entsprechenden
> Tools, die z.B. "PROGRAMM --help" in Manpages umwandeln, sodass er eine
> gute Vorlage hat und nicht alles per Hand machen muss)
> 
> Das heißt, unter Debian kommst du mit:
>     man PROGRAMM
> sehr weit, im Vergleich zu anderen Distributionen. Eventuell gibt es
> noch Info-Pages:
>     info PROGRAMM
> 
> Außerdem, wieder als feste Regel, hat jedes Paket eine Doku im
> Verzeichnis:
>     /usr/share/doc/PAKETNAME/
> Mindesten eine README bzw. README.Debian ist da drin.

Dankeschön, daß Du mir die großen Linien so klar dargelegt hast! Das
hilft mir sehr weiter.

> Natürlich sind 3 Stellen schonmal 2 zuviel, und ein Durchsuchen der
> Gesamt-Doku ist ebenfalls kaum möglich. (mit einem kleinen Shellscript
> aber zu schaffen ;-))  

Wieso muß man ein Shellskript schreiben, wenn es dwww gibt?
Darf ich Dich erinnern: Synaptic schreibt: "dwww reads all on-line
documentation with a WWW browser."
 
> In dem Zusammenhang könnte für dich interessant sein:
>     http://www.penguin-soft.com/
> Dort kannst du alle Manpages durchsuchen.

Das ist ein guter Tipp! Da werde ich in Zukunft öfter nachgucken.

> Schade eigentlich. Wenn die Distributionen die Dokumentationen genauso
> vereinheitlichen würden wie die Softwarepakete ...

...wäre das ein großer Fortschritt.

> Andererseits gibt es ja bereits einheitliche Dateiformate. Es gibt
> Manpages, nun gut, etwas beschränkt. Dann Info-Pages, die alles haben,
> was man will. Ein guter Info-Pages-Browser mit Suchfunktion, der auch
> Manpages behandeln kann, das wär's schon.
> 
> Aber nein, trotzdem muss ja unbedingt eine HTML-Doku geben. Und eine
> Plaintext-README. Vielleicht noch ne PDF-Datei und ein ODT-Dokument.
> 
> Versteht mich nicht falsch: Sie werden ja nicht "einfach so" eingesetzt.
> Sie lösen jeweils ein Problem. Aber sie packen es an der falschen Stelle
> an:
> 
> Plaintext
> ---------
> Man soll die wichtigsten Hinweise auch ohne Manpage-Reader
> oder ähnlichem lesen können. Gut so. Aber das ist in Wahrheit ein
> Problem des Manpage- und Infopage-Formats. Sie sind im Plaintext nicht
> so gut lesbar. Besser wäre hier ein Wiki-Markup, aber auch die sind im
> Plaintext mehr aufs Schreiben als aufs Lesen optimiert. Vergleiche zu
> Perl drängen sich auf ;-). Eine gute Alternative wäre reStructuredText
> (reST). Das sieht im Plaintext aus wie eine normale README. Dennoch
> kann daraus gutaussehendes HTML und ähnliches generiert werden:
>     http://docutils.sourceforge.net/docs/user/rst/quickref.html
>     http://www-128.ibm.com/developerworks/xml/library/x-matters24/
> 
> HTML
> ----
> In anderen Betriebssystemen kommt man mit HTML weiter als mit
> Manpages und Infopages. Hinzu kommt, dass heutzutage ein Linux-Anfänger
> eher den Browser kennenlernt als den Info-Viewer. Das mag zum Teil auch
> daran liegen, dass Browser leichter zu bedienen sind und zudem auch noch
> im Netz surfen können. Suchfunktionen im Browser hingegen sind grauenvoll,
> dafür braucht man immer ein extra CGI-Script oder sowas. Außerdem sind
> Browser immer "generisch" gehalten, hier könnten Infopage-Viewer
> eigentlich ordentlich punkten, durch Handbuch-spezifische Features.
> 
> PDF
> ---
> Hier kommt PDF ins Spiel. Die PDF-Viewer sind, was Bedienbarkeit
> und Suchfunktion angeht, dem Infopage-Viewer und dem Browser überlegen.
> Nachteil ist, dass hier nur eine "Druckversion" gezeigt wird, d.h. der
> Text passt sich nicht der individuellen Fensterbreite und ähnlichem an.
> 
> ODT
> ---
> PDF ist kein freies Format, ODT schon. PDF-Dokumente sind darauf
> ausgelegt, einmal generiert und nie wieder geändert zu werden. Hier
> kann ODT punkten. Es kann leicht erzeugt werden (OpenOffice, KOffice,
> ...) und fast überall hat man heutzutage OpenOffice. Konvertierung nach
> PDF ist auch kein Problem, aber einige Paket-Bauer scheinen das als
> überflüssig zu empfinden. :-(
> 
> Es werden jeweils Probleme gelöst, aber nicht der Gesamt-Kontext
> beachtet. Das führt zu einem großen Haufen ungeeigneter Werkzeuge.
> Ich kann zu Java, Python, ... Programmen eine API-Doc generieren
> (JavaDoc, EpyDoc), aber das meistens nur nach HTML. Mit etwas Glück
> auch noch nach LaTeX bzw. PDF. Ein kohärentes Stück Doku innerhalb
> *einer* Software wird damit schon schwer gemacht. Ganz zu schweigen
> von Einheitlichkeit über mehrere Software-Pakete hinweg.
> 
> 
> Dabei könnte es so einfach sein. Man einige sich auf ein Standard-
> Format für Dokumentationen. Zum Beispiel reST mit Zusatz-Empfehlungen
> (Reihenfolge/Namen der Kapitel, etc.)  Meinetwegen auch MediaWiki-
> Syntax, aber wenn man ein Wiki für die Doku aufsetzen will, kann man
> auch gleich eines aufsetzen, das reST kann.
> 
> Sicherlich gibt es nun Probleme mit Grafiken, Formeln, etc.
> aber MediaWiki hat's hinbekommen, und reST kann sicherlich auch
> entsprechend erweitert werden. Für die meiste Software wird's reichen,
> zumal die meisten Formeln und Schema-Skizzen eh erstmal als ASCII
> beginnen. ;-)
> 
> Ich als Autor würde liebendgern die Doku einfach in die README
> reinhauen, z.B. als reST. Das kann dann jeder Sven Guckes im Plaintext
> betrachten. Für die Detlef Lechners unter den Anwendern werden dann
> Manpages und Infopages daraus generiert. (*dürfte* eigentlich nicht
> schwer sein)
> 
> Auch der Rückweg, Man/Infopage -> reST, erscheint mir nicht allzu
> kompliziert (sogar leichter), sodass Projekte wie Debian, die für
> alles ihre Manpages haben, auch nach reST umschwenken könnten, wenn
> sie Interesse an einer großen einheitlichen Doku haben.
> 
> Für die Windows-User und die Projekt-Homepage wird dann noch HTML
> erzeugt (gibt's bereits). Und nicht zu vergessen das PDF für's Web.
> Der normale Benutzer würde seinen Info- oder reST-Viewer nehmen, und
> aus diesem einfach direkt drucken. (intern wahrscheinlich über LaTeX,
> DVI, PS, aber auch das gibt's AFAIK schon)
> 
> Was macht man bei API-Docs? Nunja, der perfekte Programmierer und
> Dokumentator erklärt sein Programm in einem großen Text mit
> entsprechenden Codeteilen. ("Literate Programming")  Diese Doku ist
> didaktisch gut aufbereitet, sodass jeder ohne Probleme in den Code
> hinein findet. Pro Funktionseinheit/Modul ein Unterkapitel, u.s.w.
> 
> Der normale Programmierer, wie ich, ist schon froh, wenn jede Funktion
> einen nicht-trivialen Docstring besitzt. Also kommt ein API-Doc-Generator
> her. Es wäre zu schön, wenn die Tools nicht blind nach HTML konvertieren
> würden, sondern erstmal nach reST. Es ist ja schön, dass EpyDoc dem
> JavaDoc nacheifern will, aber man sollte nur die guten Ideen kopieren.
> 
> Dann würde der Benutzer eine README und eine API-DOC sehen, die sowohl
> im Plaintext gut lesbar sind, als auch im reST-Viewer. Die README könnte
> sogar auf die API-DOC verweisen, oder diese inkludieren, aber das müsste
> nichtmal unbedingt sein.
> 
> Fehlen noch die Linux-Howtos, z.B. das Linux Documentation Projekt:
>     http://www.tldp.org/
> Eine Schande, dass die nur per HTML verfügbar sind und nicht als Info-
> Pages. Ja, sie sind auch noch als PDF und als Docbook verfügbar, aber damit
> kann man noch weniger anfangen. Man sollten den Docbook-Bloat nach reST
> konvertieren und per Wiki zugänglich machen. *Das* würde Mitarbeit anregen.
> 
> Es gibt ja auch viele Linux-Wikis im Netz, die ebenfalls genau diese
> Vereinheitlichung versuchen, aber auf genau dem falschen Wege: Alles
> nochmal neu schreiben. Es erscheint mir absurd, hier die selben Erwartungen
> zu hegen wie bei der Wikipedia: Diese ist einzigartig. Linux-Dokus
> hingegen gibt's zuhauf, und selbst die kleinste Manpage ist ein besserer
> Ausgangspunkt als ein leeres Dokument.
> 
> Gerade die kleinen Wikis sollten bemüht sein, möglichst viel mit wenig
> Manpower zu erreichen. Sie sollten in Effizienz und Automatismen
> investieren. Selbst die überwiegend von Manpower getriebene Wikipedia
> hat sehr viele Mechanismen. Natürlich auch wenn sie oftmal auch von ihrem Luxus
> gebrauch macht, viele aktive Autoren zu haben. So kommt es, dass ihre
> Anti-Spam-Mechanismen und -Empfehlungen für kleine Wikis einfach total
> ungeeignet sind. Zurück zum Thema: Was ich stattdessen sehe, sind Linux-
> und Howto-Wikis mit sehr einfacher Software, keinerlei Vorlagen oder
> Wiederverwendung vorhandener (freier) Texte. Sie scheinen alle zu
> hoffen, eine ähnlich große Autorenschaft wie die Wikipedia zu bekommen.
> Stattdessen erschaffen die meisten es gerade so, die Anfänger zu
> ermutigen, für andere Anfänger zu schreiben.
> 
> 
> Zusammenfassend haben sind das also wirklich drei verschiedene Lager,
> die alle ihre eigenen Interessen und ihre eigenen Sprachen haben:
> 
> Linux Documentation Projekt (LDP)
> ---------------------------------
>     - gute Howtos, FAQs, ...
>     - schlechtes Dateiformat (SGML/XML) als "Quellcode"
>     - motiviert nicht zur Mitarbeit, vorallem nicht zur Mitarbeit von
>       Anfängern, obwohl *hier* gerade das fehlt.
> 
> Linux-Wikis
> -----------
>     - viel zu viele
>     - fachlich schlechtere Dokus
>         (z.T. Halbwissen, z.T. falsch, siehe
>          http://wiki.njh.eu/Gesundes_Misstrauen#Internetseiten)
>     - dafür leichter verständlich geschrieben
>     - keine Wiederverwendung der LDP-Sachen
>     - motiviert hauptsächlich Anfänger zum Schreiben, obwohl *hier*
>       die Mitarbeit von Profis interessant wäre.
> 
> Manpages/Infopages der Software-Autoren
> ---------------------------------------
>     - haben größtes Potential
>     - sind nur dann gut, wenn das Dokuteam mit zum Projekt gehört
>     - hat nur dann gute Howtos, wenn die User mithelfen
>       bzw. der Autor auf die User hört
> 
> 
> Es fehlt eine gemeinsame Sprache. Und ein gemeinsames Projekt, das
> *alle* Aspekte berücksichtigt:
>     - Autoren (Manpages)
>     - fachkundige Dokuschreiber (LDP & Co.)
>     - Anfänger (Linux-Wikis & Co.)
> Dann kann nämlich etwas daraus werden. Für keinen Fachmann ist es
> erstrebenswert, irgendwelche Fehler in irgendwelchen der Heerscharen
> von Howtos zu korrigieren. "Gehören" die Howtos jedoch zum Projekt,
> ist die Hemmschwelle geringer, man sieht einen größeren Sinn darin.
> Kein Anfänger kann zu den LDP-Sachen wirklich etwas beisteuern. Die
> Docbook-Sachen sind böhmische Dörfer für ihn. Dabei sind Doc-
> Verbesserungen mindestens genauso wichtig wie Code-Verbesserungen
> (Patches), wenn nicht sogar wichtiger. Und leichtverständliches
> Schreiben gehört dazu, genauso wie ein Code-Cleanup.
> 
> 
> Auch wenn dwww mehr eine Notlösung ist, weil es auf den wirklich
> untersten gemeinsamen Nenner reduziert: HTML, macht es eine Sache
> richtig: Es ist ein Automatismus, ein Mechanismus. Und kein Projekt,
> das erst dann überhaupt brauchbar ist, wenn es viele Mannstunden vieler
> Schreiberlinge gefressen hat. Und es skaliert sehr gut: Neue Dokus von
> neuer Software werden ohne Aufwand mit eingebunden.
> 
> Dieses Prinzip ist sehr schön formuliert in den "FreeBSD Architectural
> Guidelines", Regel 7, Satz 1:
>     "Provide mechanism, rather than policy."
> 
> Es fehlen im Moment einige wichtige Mechanismen (z.B. Konvertierung
> von Manpages, Infopages, etc.), und vorallem fehlt ein Mechanismus,
> wie Doc-Verbesserungen dem Autor zurückfließen, denn hier ist der
> "klassische Weg" über E-Mails mit Patches oder Bugtracking-Systeme
> nicht ratsam.
> 
> Auch die Einbindung externer Systeme, etwa der Manpages und Infopages,
> wäre wichtig. Solange die Autoren das neue System nicht direkt
> unterstützen, muss es sich.
> 
> 
> Wo sollte solch ein Projekt liegen? Nunja, entweder bei einer großen
> freien Freie-Software-Distribution (Debian, Gentoo). Oder beim einem
> Freie-Software-Dokumentations-Projekt wie LDP. Kleine Sachen wie das
> Unbunto-Wiki wären weniger geeignet als Ort, obwohl deren Unterstützung
> natürlich unerlässlich wäre. (z.B. könnte das Ubuntu-Handbuch diesem
> Projekt anvertraut und dort gepflegt werden ... von den gleichen Autoren
> gepflegt, aber unterstützt durch eine größere Community, und mit der
> Möglichkeit, die nicht-Ubuntu-spezifischen Teile auszulagern)
> 
> 
> So, das waren erstmal meine Gedanken zu dem Thema. Mich würde
> interessieren, wie ihr darüber denkt.

Mir erscheinen Deine Gedanken vernünftig.

Du hast ein großartiges Gebäude entworfen. Aber die kleinen Niederungen
der Fragen, die ich gestern um 17.22 Uhr gestellt hatte, sind dadurch
nicht beantwortet. Ich komme dadurch nicht weiter, dwww zur Erschließung
der Debian-Informationen zu verwenden.

Fröhliche Weihnachten!
Detlef
  
-- 
Debian 4.0 "etch" Linux 2.6.17-grml#1 SMP PREEMPT 2006-07-25 i686
Epiphany 2.14.3, Evolution 2.6.3, OO.o ODE 680_m4 Build-1
MD97600, WinXP MCE 2005