On Wed, Jul 25, 2001 at 10:09:51AM +0100, jens weisse wrote:

Hi Thomas,

Thomas Guettler wrote:

...

Wie kann ich aus einer Datei "man" Pages sowie eine etwas strukturierte Version (html, info oder ähnliches) erstellen?

groff man-Seite -> ASCII, DVI oder Ps groff -Tps /der/Pfad/zur/Datei/gewuenschteDatei -mandoc > /wohin/das/Ergnis/soll/Ergebnis.ps -Tps PS-Datei als Ergebnis -Tdvi DVI-Datei - " - -Tlatin1 ASCII-Datei mit deutschen Sonderzeichen

rman man-Seite -> ASCII, HTML, SGML, LaTeX rman -f html /der/Pfad/zur/Datei/gewuenschteDatei > /wohin/das/Ergnis/soll/Ergebnis.html

Beides leider nicht was ich suche. Es geht dabei um die man page von fetchmail. Ich habe mit einem Entwickler gemailt. Er ist auch daran interessiert die Man-page übersichtlicher zu machen. Info wäre nicht schlecht, aber daraus kann man keine Man-page erstellen. Ich suche eine hierarchische Sicht auf die Dokumentation wie sie Info oder HTML (z.B. Howtos) bieten. Es sollte aber immer noch möglich sein eine Man-Page daraus zu generieren. "groff2html" wäre was ich Suche.

On Fri, Jul 27, 2001 at 11:36:04AM +0200, Thomas Guettler wrote:

Beides leider nicht was ich suche. Es geht dabei um die man page von fetchmail. Ich habe mit einem Entwickler gemailt. Er ist auch daran interessiert die Man-page übersichtlicher zu machen. Info wäre nicht schlecht, aber daraus kann man keine Man-page erstellen.

Ich mag folgende amliebsten: Eine ***knapp*** gehaltene man-page, die die Funktionalität des Tools beschreibt. Alle weitere Doku sollte ausgelagert werden (info-seiten, FAQ, HowTo)

Die man-page von fetchmail ist arg bloated durch überflüsse Prosa und teilweise unlogisch strukturiert. Ein Beispiel:

General Options -V, --version ... Protocol and Query Options -p, --protocol <proto> ...

USER AUTHENTICATION AND ENCRYPTION Prosa DAEMON MODE Prosa ADMINISTRATIVE OPTIONS The --postmaster <name> option (keyword: set postmaster) specifies the last-resort username to which multidrop mail

nun also plötzlich wieder Options und zwar verkleidet in Prosa :-(

Man-Pages sollen lediglich Funktionalität des Tools erklären und nicht alle eventuellen Anwendungsfälle inklusive subjektiviver Bewertung auflisten. Weniger ist hier mehr.

Abschnitte, die ich ein HowTo stecken würde sind z.b:

Good Ways To Use Multidrop Mailboxes Multiple local names can be used to administer a mailing list from the client side of a fetchmail collection. Sup .... Bad Ways To Abuse Multidrop Mailboxes Multidrop mailboxes and fetchmail serving multiple users .... Speeding Up Multidrop Checking Normally, when multiple user are declared fetchmail extracts recipient addresses as described above and checks APPLICABLE STANDARDS SMTP/ESMTP: RFC 821, RFC 1869, RFC 1652, RFC 1870, RFC1983, RFC ...

Teile von: USER AUTHENTICATION AND ENCRYPTION Every mode except ETRN requires authentication of the ...

Ich suche eine hierarchische Sicht auf die Dokumentation wie sie Info oder HTML (z.B. Howtos) bieten. Es sollte aber immer noch möglich sein eine Man-Page daraus zu generieren. "groff2html" wäre was ich Suche.

Aus einer Quelle sowohl eine gute man-page als auch eine gute hierarchische Doku (die das, was man in FAQ/HowTo erwartet, auch enthält) zu bauen wird nichts werden, da die Anforderungen zu verschieden sind. Selbst mit Flags im Quelltext der Doku ala <das in die man-page> und <das nicht in die man-page> kommt man nicht weit.

Ich würde also die Manpage gekürzt erhalten und den Rest in eine Form bringen, die man leicht in andere Formate (html,ps,...) wandeln kann. texinfo oder sgml bieten sich da wohl an. Aus den texinfo-Dokus der Pakete aus dem GNU-Projekt lassen sich beispielsweise mit Texi2html (http://www.mathematik.uni-kl.de/~obachman/Texi2html/) wirklich gute HTML-Seiten bauen.

Reinhard