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

So Dez 31 04:28:56 CET 2006

On Tue, Dec 26, 2006 at 05:25:50AM +0000, Peter Ross wrote:
> > Man soll die wichtigsten Hinweise auch ohne Manpage-Reader
> > oder ähnlichem lesen können. Gut so. 
> 
> Warum?
> 
> man(1)
[...]
> laeuft in jedem Terminal und ist nicht schwieriger zu bedienen als ein 
> less oder aehnliches,

Es ging mir weniger um die Reader. Mit der Argumentation kannst du auch
PDF empfehlen, denn welcher Computer kann heutzutage kein PDF anzeigen?
Oder HTML, wenn man es auch an der Konsole gut lesen können soll (lynx, w3m).

Mir ging es vorallem um das Schreiben. Ich will nicht sagen, dass das
Format der Manpages kompliziert ist. Aber es ist lange nicht so schön
wie Wiki-Markup, oder gar reST.

Oder kennst du irgendein Dokumentations/Handbuch-Projekt, das im
Wiki-Stil betrieben wird und als Dateiformat "manpages" benutzt?

> es unterteilt die Dokumentation gleichfoermig in Kapitel (auch ein gutes 
> Grundgeruest, um nichts zu vergessen), die Markierung ist simpel, und es 
> ist mit Standardtools durchsuchbar, man kann es "von oben nach unten" 
> lesen, und weiss dann Bescheid (bei Menusystemen ist es leicht, einen 
> Hinweis, den man dringend braucht, zu uebersehen, weil er irgendwo vier 
> Submenus tief versteckt ist).

Dennoch werden für größere Handbücher lieber Info-Pages genommen. Wieso?
Das Menüsystem scheint doch Vorteile zu haben.

Aber ich stimme zu, dass ein Zerhacken in zu kleine Teile gefährlich
ist, vorallem in erklärenden Texten, die aufeinander aufbauen.

> Es hat eigentlich auch schon Links (alles, was mit blabla(x) drinsteht, 
> besonders unter SEE ALSO).

Ja, nur leider kann "man" die nicht verfolgen. Warum gibt es keine guten
Manpage-Programme? Dieses einfache Feature, das jeder von "info",
"lynx", etc. kennt, gibt es dort einfach nicht. :-(

> Desweiteren macht die geeignete Angabe des Manpath es einfach, deutsche 
> (z.B.;-) Doku als Default anzubieten und im Falle des Fehlens auf englisch 
> zurueckzufallen..

Gut, das Konzept mehrerer Seiten in mehreren Sprachen ist gelöst. Aber
nur durch die Namensgebung der Dateien. Geht haargenauso mit reST-
Textdateien, Wikiseiten oder HTML-Seiten.

> Kurz gesagt - man(1) wurde nicht von Dummies erfunden und hat sich 
> hervorragend bewaehrt.

Warum gibt es dann Alternativen? Wieso werden große Texte in Info-Pages
geschrieben und eher selten auf mehrere Manpages aufgeteilt?

Vielleicht fehlen auch einfach nur schicke Manpage-Editoren bzw.
-Viewer.

(schick = ergonomisch bedienbar, leicht bedienbar, optisch ansprechend,
          anfängerfreundlich, vielleserfreundlich, vielschreiberfreundlich)

> Fuer umfassende Doku ist es das geeigneteste System, es laesst sich auch 
> leicht "aufbohren", um ein paar <HTML>-Klammern - meinetwegen ach XML - 
> verpasst zu bekommen, und schon hast Du die gleiche Doku im Webbrowser - 
> inklusive der Links. (siehe z.B. die CGI-Web-Manpages unter 
> www.freebsd.org)

Das Drumherum (Suche, etc.) ist wirklich gut. Aber die Darstellung der
Seiten .. nunja, kommt über "man" nicht weit hinaus. Es gibt Farben und
man kann Links folgen. Aber hey, es ist eher eine Schande, dass "man"
dies nicht drauf hat. Vielleicht geht's ja mit

    man -H ...

Aber bei mir funktioniert das nicht:

    groff: can't find `DESC' file
    groff:fatal error: invalid device `html'

Zurück zu den CGI-Manpages: Wieso gibt es dort manuelle Zeilenumbrüche
und Courier-Schriftart. In Beispiel-Code und Aufruf-Diagrammen muss das
so sein, aber doch nicht im Fließtext. Das liest sich ja genauso wie auf
der Kommandozeile. Da wurde der ASCII-Renderer mit etwas Farbe und Links
aufgepeppt und das war's. Eine HTML-Konvertierung ist was anderes.

Du kannst natürlich ein OpenOffice-Dokument Pixel-für-Pixel rendern und
jedes einzelne davon als Mini-Quadrat in LaTeX setzen. Eine Konvertierung
von ODT nach LaTeX wäre das aber nicht wirklich. Genauso wirken diese
CGI-Seiten auf mich. Gibt es denn niemanden, der sowohl in Sachen
Manpages als auch in HTML/CSS-Sachen etwas drauf hat?

Also, da ist ja jeder Wiki-Renderer weiter entwickelt. Das erzeugte HTML
taugt gerade so für Lynx.

> Wenn Du es jetzt schaffst, die HowTos oder Handbuecher (die wirklich 
> schwer in Manpages zu bringen sind) mit ordentlichen Hinweisen auf die 
> Manpages zu verheiraten, hast Du alles unter der Haube.

Guter Ansatz. Aber genau das war ja meine Ausgangsfrage. Der Tipp mit
dem Manpage-Format als "Zentrum", anstelle von Wiki-Markup / reST, ist
zwar gut. Und du hast mir die Augen geöffnet, wieso Debian auf Manpages
besteht.

Aber die eigentlichen Probleme, Konsistenz und Kooperation, sind damit
höchstens angekratzt.

Was meinst du damit, dass man HowTos nicht in Manpages unterbringen kann?
Ist das Format ungeeignet? Beispiel-Code etc. kann es doch darstellen?!

Und warum soll "man" ungeeignet für Handbücher sein? Was zum Teufel sind
"Manual Pages" denn sonst, wenn keine Handbücher? Sie leiten ein, geben
Code/Aufruf-Beispiele, weisen auf typische Fallen hin, etc.

> Ganz ehrlich - in den letzten Jahren haben viele Koeche mit 
> Verbesserungen den Schlamassel der Unuebersichtlichkeit herbeigefuehrt, 

Sie haben ihre Probleme gelöst. Aber zugegebenermaßen an den falschen
Stellen angepackt.

> und angesichts weniger Vorteile, die oft nur in bestimmten Situationen 
> greifen und in anderen eher hinderlich sind, ist das kaum 
> nachzuvollziehen.

Wenn diese bestimmten Siturationen gerade auf dich zutreffen, und du
keinen Blick für das Ganze hast (das heutzutage schwerer zu finden ist
denn je)? Ich kann das sehr gut nachvollziehen.

Wiegesagt, der HTML-Renderer für Manpages hat genau das gleiche Problem.
Nixh mit Semantic Web, nix mit Trennung von Inhalt und Markup (HTML/CSS).
Die Seiten sind auf Lynx zugeschnitten, also auf eine bestimmte Situation.
Und in anderen (gängige stinknormale Browser) nur hinderlich (unnötig
schwer lesbar).

> Die Flexibilitaet von man(1) ist wirklich kaum zu schlagen..

Ja, das ist richtig und gut so. Aber diese Flexibilität muss man auch
*nutzen*. Wie kann es sein, dass für ein so schön supertoll einfaches
Format kein vernünftiger HTML-Renderer existiert?

Wenn Manpages so flexibel sind, wieso kann/soll man damit keine Howtos
oder Handbücher schreiben? Vielleicht habe ich ja nur ein Brett vorm
Kopf, aber ich vermag darin kein flexibles Konzept zu erkennen.

> Daher wuerde ich einfach sagen - schreibt ordentliche Manpages und nutzt 
> man (oder halt ein CGI-Skript, ums im Browser darzustellen).

Bin noch nicht ganz überzeugt. Aber ein Webinterface für Manpages zu
schreiben, das gängige Wikis in Sachen Einfachheit und guter Vorgaben
überbietet, sollte möglich sein.

Solange Anfänger von Manpages abgeschreckt werden (nicht nur vom Lesen,
sondern vorallem auch vom Schreiben), wird die von mir beschriebene
Dreiteilung nicht durchbrochen werden.

Viele Grüße,

    Volker

-- 
Volker Grabsch
---<<(())>>---
Administrator
NotJustHosting GbR