Siehe auch: http://www.heise.de/tp/deutsch/inhalt/te/11585/2.html

ManPages im Wiki ablegen

Ich versuche mal diesen Wust etwas zusammen zu fassen:

Allgemeines

FYI: Man pages werden heute zum grossen Teil (vielleicht auch alle) aus Info-Dateien erzeugt. Dies trifft insbesondere auf GNU Manpages zu. Man-Pages zu editieren ist also überhaupt keine Option. Aber man könnte die ganze Diskusion nochmal über das info-Format führen...

Manpages in welcher Sprache?

• deutsch sollte eingentlich reichen
• englische im englischen Teil von linuxwiki.org, wenn es soweit ist.
• alternativ: Sprache im Namen angeben

Unter welchem Namen sollen die Manpages eingehängt werden

Probleme:

• Sektionen
• Sprachen
• mehrere gleichnamige Seiten in verschiedenen Sektionen
• man sollte die Section nicht angeben müssen (aliasing; z.B. tar, tar(1))
  • bei Eindeutigkeit Seite mit redirect
  • sonst Indexseite

Mögliche Schreibweisen:

• Man CGI, oder Linkgenerator auf Wikiseiten

  • ManPage:readlink(1)

    • Implementierung? funktioniert im normalen Wikimarkup nicht

  • ManPage:readlink+1

    • Geht im Wikimarkup
    • Benötigt entsprechendes CGI
    • muss nicht gequotet werden!!!

  • [[ManPage(readlink(1)]]

    • Moinmoinmacro
    • größte Flexibilität, was die dahinterstehende Implementierung angeht
• Automatisch generierte Wikiseiten

  • ["readlink"] als redirect oder als Index zu den Seiten in den Sectionen, eigentlich Seiten als ["readlink/1"]

  • ManPage/readlink/1

  • ManPage/1/readlink - Dann muss man immer die Section mit angeben

  • ManPage/de/1/readlink - bei Mehrsprachigkeit durch mehrere Wikis unnötig

  • Sections als Wikibadge auf die Seite (???)
    • löst das Überschneidungsproblem bei mehreren gleichnamigen Manpages nicht

Das man.cgi von FreeBSDman geht ja in die Richtung, müsste nur leicht überarbeitet werden, damit es mit der entsprechenden Abfrage klar kommt.

Manpages editieren? Und wenn in welchem Format?

Problem: Die Änderungen, die im Wiki gemacht werden/würden, sollen natürlich irgendwie wieder zurück in die Manpages überall auf der Welt.

Nicht editieren

• Wiederspricht Wikikultur
• keine Probleme die Änderungen, die es nicht gibt, in die Manpages zu übernehmen
• einfach
• keine Möglichkeit die Manpages zu korrigieren/verbessern

Editieren

• Im original nroff Format
  • unübersichtlich
  • kryptisch
  • von Sonderzeichen durchsetzt
  • potentielle Autoren / Korrektoren werden abgeschreckt
• Als Infopages
  • komplizierter als Wikimarkup
  • eine Infodatei erzeugt viele Manpages (Implementierung!?!)
  • von der Editierbarkeit etwas besser als nroff
• Im Wikimarkup
  • Man durch ein Programm ersetzen, dass Wikimarkup versteht

  • Konverter Wikimarkup -> Manpage

  • Die (hoffentlich geringen) Änderungen können mit Hilfe des diffs von Hand nachgetragen werden
• Kommentare nur unten anhängen
  • eingentliche Manpage bleibt unverändert
  • nicht sehr wikilike
  • bedeutet faktisch die Manpage nicht zu editieren (gleiche Vor-/Nachteile)
  • evtl. besser als wenn man die Kommentare auf eine extra Seite packen muss

Konvertierung Wikimarkup <-> Manpages

Das einzige was man für Man-Formatierung braucht sind:

• Überschriften (OK)

• Zwei Schriftfarben oder Arten (Fett und Kursiv) => (OK)

• Text als (fast) Blocksatz (OK) [siehe Konqueror man:/apropos z.B.]

• Definitionen (HTML=DL, DT und DD) => (OK, hab gerade nachgeschaut, geht!) (Dies wird für die Optionen gebraucht)

• Links zu anderen Manpages (in jedem Fall! Wir sind hier in nem Wiki ) (OK)

Und das wars auch schon, also ließen sich Manpages ohne Problem in ein Wiki-Format umwandeln! Am besten nimmt man nen Man2Html-Parser und schreibt den um, da die meisten Digne direkte Entsprechungen haben!

Die Idee: Wiki-Markup verwenden und ein neues man-Kommando für die Konsole implementieren.

Für das "man/xman"-Kommando gibt es dann folgende Alternativen einen einfachen Wrapper, der links/lynx/w3m/Grafischer-Browser mit einer passenden URL auf

• ein lokales Wiki oder

• das LinuxWiki (dann spart man sich das lokale Wiki, braucht aber ne Internetverbindung) oder

• auf on-the-fly durch einen Konverter Wiki-Markup->HTML generiertes HTML

loslässt. Wenn man das ganze dann noch vielleicht in Python oder Perl implementieren würde, wäre es auch plattformunabhängig. Ist zwar ein weitreichender Schritt, aber ab und an ist ja sowas notwendig

Der erste Versuch eines Skriptes, welches ein abgeändertes Man2Html ist, ist gegelückt

Nachteil: Da Man2Html (man2wiki!) bereits formatierten man-Code verwendet gehen Definitionen verloren, was beim derzeitigen Parser, aber nicht schlimm ist, da dieser Überschriften, Fußnoten, Definitionen (das vorm ::) sowieso NICHT parst, wodurch man bisher sowieso WorkAround's nutzen müsste. -- FabianFranz 2002-06-19 23:22:42

man2wiki.text

Das Programm wird mit man apropos | ./man2wiki gestartet. Heraus kommt auf stdout der formatierte Output.

Probleme:

• führende Leerzeichen vor den =-Zeichen verhindern korrekte Überschriften
• generell führende Leerzeichen - etwas unhübscht als Wiki-Sourcecode
• PERL (in Python würde es besser zu moin passen und wäre leichter wartbar)

wiki2man

Hab mal angefangen ein kleines TCL-Script zu schreiben (wiki2man): wiki2man -- OliverDippel 2002-06-20 00:15:00

http://wiki2man.sourceforge.net/