Re: Portmaster - unklare manpage

Heino Tiedemann wrote:
> -a ist auch hier zulässig:
>
> portmaster [--force-config|-G] [-P|-PP] [-aftv] -F

Dieses Synopsis gilt nur, wenn -F benutzt wird (d.h. wenn
nur distfiles heruntergeladen werden). Sieht man daran,
dass das -F nicht in Klammern steht.

Leider (?) hat portmaster eine ganze Menge unterschiedlicher
Aufrufmöglichkleiten und eine entsprechend große Anzahl von
Synopsis-Zeilen in der Manpage. Diese sind aber durchaus
korrekt und eindeutig aufgeführt, soweit ich das beurteilen
kann. Man muss halt nur genau hinsehen.

Zum vorliegenden Fall: Die Option -n aus den "Common Flags"
(d.h. "run through all steps ...") kann nur bei den Synopsen
verwendet werden, wo "[Common Flags]" steht. Die Option -n
in der Bedeutung "no" (oder -y für "yes") kann nur bei den
Synopsen verwendet werden, wo "[-n|y]" steht. Ist doch
eigentlich einleuchtend. (Genaugenommen fehlt da ein "-";
es müsste "[-n|-y]" heißen, aber es ist trotzdem klar, was
gemeint ist.)

Ich persönlich verwende portmaster nicht, aber allein schon
anhand der Synopsis-Zeilen in der Manpage sieht man genau,
wie das Kommando aufgerufen werden kann und wann man welche
Optionen verwenden kann.

Das ist einer der Vorteile von UNIX-Manpages: Sie sind
einheitlich aufgebaut und verwenden eine einheitliche Syntax.
Wenn man einmal damit vertraut ist, kann man fast beliebige
Manpages lesen und findet sich sofort zurecht. Anderswo ist
das leider häufig ein buntes Durcheinander. Es gibt Fälle,
wo Software-Projekte ihre Manpage(s) aufgegeben haben und
stattdessen die Referenzdokumentation in irgendeine anderen
Form (wenn überhaupt) überführt haben -- meistens ging das
mit einer Verschlechterung einher. Ich könnte jetzt ein
paar Beispiele nennen, aber dann wird's vermutlich wieder
ein Endlos-Thread ...

> > Oder einfach nur verwirrend?
>
> Unix manpages halt.
>
> Ich habe sie nie gemocht. Allein wegen des eklatenten mangels an
> beispielen.

Die portmaster-Manpage hat doch einen Abschnitt "EXAMPLES".

Natürlich gibt es auch schlechte Manpages, aber gerade
die, die zu FreeBSD gehören, sind eigentlich hervorragend
geschrieben und gehen häufig sogar weit über die Referenz-
dokumentation hinaus, die die Manpages bei klassischen UNIX-
Systemen darstellen. Schau Dir zum Vergleich mal Manpages
von Solaris an: Die sind deutlich spartanischer.

Der Haken an den Manpages ist natürlich, dass man sie -- wie
jede Dokumentation -- aufmerksam lesen muss. Und nicht mit
der Attitüde »Das ist eh alles Mist« drangehen, sonst wird
das nichts.

> aber warum macht man diese manpages nicht mal "user fiendly"?

Das nenn' ich mal einen »Freudschen Vertipper« ... :-)
("fiend" ist so ziemlich das Gegenteil von friend)

Gruß
   Olli

-- 
Oliver Fromme,  secnetix GmbH & Co. KG,  Marktplatz 29, 85567 Grafing
Handelsregister:  Amtsgericht Muenchen, HRA 74606, Geschäftsfuehrung:
secnetix Verwaltungsgesellsch. mbH, Handelsreg.: Amtsgericht München,
HRB 125758, Geschäftsführer:  Maik Bachmann,  Olaf Erb,  Ralf Gebhart
FreeBSD-Dienstleistungen/-Produkte + mehr: http://www.secnetix.de/bsd
"It combines all the worst aspects of C and Lisp:  a billion different
sublanguages in one monolithic executable.  It combines the power of C
with the readability of PostScript."
        -- Jamie Zawinski, when asked: "What's wrong with perl?"
To Unsubscribe: send mail to majordomo(at)de.FreeBSD.org
with "unsubscribe de-bsd-questions" in the body of the message