[linux-l] Re: Linux - Dokumentationsstandard? "manuals"

[Sven Guckes]

* Peter Ross <Peter.Ross at alumni.tu-berlin.de> [2005-04-08 03:27]:
> On Thu, 7 Apr 2005, Sven Guckes wrote:
> > welches dokumentationsmittel haetten
> > wir denn nun gern als *standard*?
>
> Schau mal unter http://www.freebsd.org/cgi/man.cgi
> nach, wieviele Systeme Manpages benutzen

ja - da sind so einige systeme...
aber es sind so ziemlich alles unixoide systeme.

> (es sind lange nicht alle auf der Seite)

ich vermisse windows ;-)

> Es ist bewaehrt und ueberall einsetzbar,
> selbst mit dem duemssten Terminal
> (was fuer den Serverraum wichtig ist).

ja, text only ist ein guter grund.
drum mag ich ja auch die texttools.

aber... dokumentation soll doch auch
bunte bilder enthalten. und was nun?

> Die Aufteilung der einzelnen Kapitel ist weitgehend
> standardisiert, nicht erst seit gestern, so dass
> sich jeder Nutzer schnell zurechtfindet.

jeder *geuebte* nutzer findet sich schnell zurecht.
das springen zwischen den sektionen
scheinen nicht viele zu beherrschen.

> Dadurch, dass man etwas von Anfang zu Ende
> durchlesen kann, entfaellt die "Moeglichkeit",
> den passenden Menuepunkt zu uebersehen, dank
> des Pagers (less or more;-) gibt es ausgefeilte
> Suchfunktionalitaet ueber die gesamte
> Dokumentation zu einem Kommando/Fileformat etc.

die befehle der pager scheinen auch nicht viele zu kennen.
allein die benutzung von '!" und CTRL-K in der suche
bei "less" ist vielen offensichtlich nicht bekannt.

> Ja, es implementiert Hyperlinks nicht direkt,
> stattdessen steht am Ende eine "SEE ALSO"-Rubrik,
> welche Hyperlinks anbietet, die durch einen weiteren
> Aufruf von man einfach erreichbar sind.

ja - hyperlinks fehlen.
zwar kann man erneut "man" aufrufen -
aber man kann keinen text *in* einem
anderen manual direkt referenzieren.
hyperlinks fehlen sogar *sehr*.

> Diese leichte Unbequemlichkeit ist fuer mich nicht
> ausreichend Grund, um stattdessen mich durch ein
> Sammelsurium von Alternativen durchschlagen zu
> muessen, um endlich eine Info zu bekommen.

die alternativen bieten aber auch teilweise hyperlinks an.
ich finde, man sollte diese alternativen unbedingt kennen.
mit Robin Socha hatte ich mal ein sammelsurium an hilfen
zusammengestellt - und er hatte das souveraen vorgetragen.
ein vortrag, den man eigentlich immer wieder halten koennte..

> Die funktionalen Unterschiede unterschiedlicher Formate sind
> marginal, fuer mich sind daher Standardisierung (sprich
> Verfuegbarkeit ueberall), Uebersichtlichkeit (nichts ist
> versteckt unter Menupunkt 7.5.4.2) minimale Anforderungen an
> Ein- und Ausgabe (Stichwort dummes Terminal) und Lokalitaet
> (sprich: auf Platte und nicht irgendwo im Netz) wichtiger.

gute punkte!

> Und da schneidet man(1) am besten ab..

.. mit nroff, groff oder troff?  ;-)

an einem aufruf von "man" haengen ja
schliesslcih noch einige prozesse dran..

--man(30760)---sh(30769)-+-less(30773)
                         |-nroff(30772)---groff(30788)-+-grotty(30790)
                         |                             `-troff(30789)
                         `-tbl(30771)

apropos:
http://www.troff.org/papers.html
Papers on troff and its companions

Sven