Ich möchte einige Linux-Manpages ohne Verwendung von groff in HTML konvertieren. Mein Vorurteil gegen groff ist auf einige PNG-Rendering-Probleme zurückzuführen , die Sabayon zu bieten scheint (da diese Probleme auf meinen VirtualBox-VMs für andere Distributionen nicht auftreten). Mir ist klar, dass dies ein Fehler ist, aber eine Lösung scheint nicht in naher Zukunft zu sein. Daher möchte ich fragen, ob es andere Möglichkeiten gibt, Linux-Manpages in HTML zu konvertieren. Die Verwendung der HTML-Seiten unter http://linux.die.net/man ist keine akzeptable Lösung, da einige der Manpages, an denen ich interessiert bin, nicht vorhanden sind (z. B. emerge(1)nicht vorhanden sind).

Es gibt viele Alternativen wie roffit , troff , man2html . Es gibt auch Perl-basierte Online-Manpage-Browser wie manServer .

Mein Favorit ist pandoc, obwohl es leider standardmäßig keine ROFF-Eingabe unterstützt (obwohl Sie es wahrscheinlich verwenden können, wenn Sie mehrere Transformationsfilter miteinander verketten müssen.

man2html Beispiel:

zcat /usr/share/man/man1/dd.1.gz \ 
    | man2html \
    | sudo tee /var/www/html/dd.html

roffit Beispiel:

git clone git://github.com/bagder/roffit.git
cd roffit
zcat /usr/share/man/man1/dd.1.gz \
    | perl roffit \
    | sudo tee /var/www/html/dd-roffit.html

Andere Werkzeuge:

• troffcvt macht ungefähr das Gleiche.
• The 'real' troff- Ich werde http://heirloom.sourceforge.net/doctools.html ausprobieren . Ich vermute, schily hat OpenSolaris und Freunde im Sinn :-).

Dieses erste Stück ist ein schamloser Rip von der offiziellen Website :

mandocist eine Reihe von Tools zum Kompilieren mdoc, die roffMakrosprache der Wahl für BSD-Handbuchseiten und mandie vorherrschende historische Sprache für UNIX-Handbücher. Es ist klein, ISO C, ISC-lizenziert und recht schnell. Die Hauptkomponente des Toolset ist das mandocauf dem libmandocValidierungs-Compiler basierende Dienstprogramm zum Formatieren der Ausgabe für UNIX-Terminals (mit Unterstützung für Gebietsschemas mit großen Zeichen) , XHTML, HTML, PostScript und PDF.

mandocwurde überwiegend auf OpenBSD entwickelt und ist sowohl ein OpenBSD- als auch ein BSD.lv-Projekt. Wir bemühen uns, alle interessierten freien Betriebssysteme zu unterstützen, insbesondere FreeBSD, NetBSD, DragonFly, illumos, Minix 3 und GNU / Linux sowie alle Systeme, auf denen das pkgsrctragbare Paketerstellungssystem ausgeführt wird. Um die mandocEntwicklung zu unterstützen , sollten Sie eine Spende an die OpenBSD-Stiftung in Betracht ziehen.

pacmanmdocmlInformiert mich, dass meine lokal installierte Paketgröße 3,28 MB beträgt und die folgenden /usr/binBinärdateien enthält:

/usr/bin/demandoc
/usr/bin/makewhatis
/usr/bin/mandoc
/usr/bin/mapropos
/usr/bin/mman
/usr/bin/mwhatis

Damit kann ich machen:

mman -Thtml mman >/tmp/html
firefox file:///tmp/html

Sie können Ihre eigenen Stylesheets nach Belieben anwenden. Die gesamte Dokumentation ist ebenfalls online . Und all das wird, wie ich denke, auch zusammengestellt mandoc.

Zunächst ist zu beachten, dass mehr als ein Programm aufgerufen wird man2html.

Ein Dienstprogramm namens man2htmlist ein C-Programm, das ursprünglich Ende der 90er Jahre von Richard Verhoeven an der Technischen Universität Eindhoven Ende der 90er Jahre geschrieben wurde. Das Programm hat im Wesentlichen skurrile Interna. Es hat jedoch den Vorteil, dass es mit der Roh-Manpage-Quelle und nicht mit troffoder der nroffAusgabe funktioniert . Dieses Programm wurde zu Frederico Lucifredis Man Suite hinzugefügt.

Das Programm versteht die Semantik von manund mandocMakros und gibt eine vernünftige HTML-Struktur aus. Zum Beispiel, wenn Sie eingerückte Absätze wie folgt verwenden:

.IP Wort
Definition von
Wort.
.RS

Das Programm erstellt eine HTML-Definitionsliste.

Ich verwalte eine sehr große Manpage (fast ein Megabyte Quellenseite und fast 400 Seiten lang, wenn sie von in PDF im Letter-Format konvertiert wird groff):

$ ls -l txr.1
-rw-rw-r-- 1 kaz kaz 980549 3. Januar 11:38 txr.1

Als ich dies vor etwa fünf Jahren in HTML konvertieren musste, fand ich nur das man2htmlC-Programm und die Nachbearbeitung seiner Ausgabe auf "Season to Taste".

Schließlich wollte ich ein HTML-Dokument von viel besserer Qualität, also fing ich an, troffMakros zu schreiben . Die Einschränkungen des C-Programms wurden schmerzlich deutlich, also gabelte ich es. Auf meiner Git-Seite findest du ein Git-Repo mit 30 Patches für man2html . Diese Patches beheben eine Reihe von Fehlern und erweitern das Programm um eine wesentlich verbesserte Fähigkeit, Troff-Makros, Bedingungen, Schleifen und andere Konstrukte zu interpretieren. Ich habe auch ein M2Register hinzugefügt , mit dem Sie Code schreiben können, der erkennt, dass er ausgeführt wird, man2htmlund einige Dinge bedingt anders ausführen kann (scrollen Sie für ein Beispiel nach unten). Außerdem habe ich einen .M2SSBefehl hinzugefügt, mit dem Sie einen benutzerdefinierten HTML-Header-Abschnitt ausgeben können.

Meine große Manpage wird hier gehostet . Dies wird mit man2htmlmeinem genman.txrProgramm erstellt, nachbearbeitet , das die Abschnitte neu anordnet und Hyperlinks im gesamten Dokument hinzufügt. Außerdem werden die internen Links im Inhaltsverzeichnis als stabile URLs umgeschrieben (basierend auf Hashing und nicht auf willkürlicher Aufzählung) und das Inhaltsverzeichnis über Javascript zusammenklappbar gemacht.

Die genauen Befehle von my Makefile:

man2html txr.1 | ./txr genman.txr -> txr-manpage.html
tbl txr.1 | pdfroff -man --no-toc -> txr-manpage.pdf

Ein Beispiel dafür, wie sich die Ausgabe zwischen HTML und anderen Bedingungen bedingt unterscheidet, nroffist ein Abschnitt der manAusgabe:

       9.19.4 Makroabbau

       Syntax:

                (defstruct {<name> | (<name> <arg> *)} <super>
                   <Steckplatzspezifizierer> *)

              Das Defstruct-Makro definiert einen neuen Strukturtyp und Register
              es unter <Name>, das ein verbindliches Symbol sein muss, gemäß
              die bindbare Funktion. Ebenso muss der Name jedes <Slots> sein
              auch ein bindbares Symbol sein.

Beachten Sie oben, wie Parameter in bezeichnet werden <angle> <brackets>. In der HTML-Version werden sie kursiv dargestellt .

Der Syntaxabschnitt wird im Quellcode folgendermaßen angezeigt:

.coNP Macro @ defstruct
.synb
.mets (defstruct >> {name | >> (name << arg *)} <super
.mets \ \ << Slot-Spezifizierer *)
.syne

Dies sind alle benutzerdefinierten Makros, die im selben Dokument definiert sind. Unter .mets, < bMittel bist eine Meta-syntaktische Variable. >> a bmeans aist eine konkrete Syntax, neben der sich die Metasyntaktik bohne Zwischenraum befindet, und <> a b cmeans bist eine Metasyntaktik, die zwischen aund cLiteralen zusammengesetzt ist.

Meine verbesserte Version von man2htmlversteht das ziemlich komplizierte Makro, das diese Markup-Konventionen implementiert.

Beachten Sie auch, wie das Handbuch automatisch Abschnitte nummeriert hat: Dies geschieht alles durch troff-Code, der man2htmlversteht.

Da OpenSolaris als OSS verfügbar gemacht wurde, gibt es eine kostenlose troff.

Eine Reihe von portierten Quellen finden Sie hier:

http://heirloom.sourceforge.net/doctools.html

aber Heirloom ist ein totes Projekt seit ungefähr. 2007. Vielleicht möchten Sie überprüfen

https://github.com/nt-roff/heirloom-doctools

wo einige Leute das tote Erbstückprojekt fortsetzen.

Zusammen mit man2htmltroff können Sie automatisch schöne HTML-Manpages erstellen.

Siehe zB die SchilliX-Manpages:

http://schillix.sourceforge.net/man/

mit der Schily Bourne Shell:

http://schillix.sourceforge.net/man/man1/bosh.1.html

Ich bin damit zufrieden und mit den richtigen Optionen erhalten Sie verknüpfte Manpages mit anderen Dokumentationen derselben Gruppe. Ich benutze zB diesen Befehl:

soelim sh.1 | tbl | nroff -u1 -Tlp -man - | col -x | \
                        (sed -e 's/XXX/sh.1/g' ../conf/pre.html; \
                        man2html  -cgiurl '../man$section$subsection/$title.$section$subsection.html' -compress -nodepage; \
                        cat ../conf/post.html) | \
                        egrep -v 'HTML|BODY'> sh.1.html

Das ist Teil des make-Dateisystems in den Schily-Tools. Notieren Sie sich die Dateien ../conf/pre.htmlund ../conf/post.htmldas schily makefilesystem, die für den Titel und andere benötigt werden. Vielleicht möchten Sie diese vier Ihre Bedürfnisse ändern.

Eine man2thmlErweiterung ist Teil der Schily-Tools (siehe unten auf der boshManpage).

BTW: eine lustige Informationen: Der gesamte troffQuellcode sowie alle Quellen für alle Hilfsprogramme wie soelim, tbl, ... plus die manProgrammquelle ist nur die Hälfte der Code , den Sie für das müssen mandocProgramm und mandochat nur eine sehr begrenzte tblUnterstützung , die Pausen meisten Solaris Mann Seiten.

Wenn Sie Unterstützung für mandocformatierte Troff-Quellen von FreeBSD und ähnlichem benötigen , habe ich eine Reihe von Mandoc-Makros erstellt, die für diese funktionieren troff. Überprüfen Sie die SchilliX-Quellen unter: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ Der betreffende Code ist in den Dateien andocund doc*.

Die manProgrammquellen in SchilliX-ON wurden geändert, um nroff -mandocstatt aufzurufen nroff -man.

Die Probleme von OP mit PNG-Dateien stimmen mit meiner Erfahrung mit groff für die xterm-Handbuchseite und die Dokumentation der Kontrollsequenzen überein. Das Problem ist, dass groff versucht, Tabellen als aus der PDF-Datei ausgeschnittenes Bild zu rendern , und dass es seit mehreren Jahren fehlerhaft ist . Während ich das Perl-Skript man2html seit den 1990er Jahren für die Dokumentation von ncurses verwendet habe, war es für andere Programme einfacher, Ad-hoc-HTML- und PDF-Dateien mit groff zu generieren. PDF-Dateien funktionieren einwandfrei; die HTML-Dateien nicht.

Gleichzeitig hatte das Perl-Skript seine eigenen Probleme.

Da beides nicht verschwand (und weil die vorgeschlagenen Alternativen keine Verbesserung darstellten, weil Abhängigkeiten hinzugefügt oder andere Einschränkungen eingeführt wurden), löste ich das Problem, indem ich Verbesserungen an man2html vornahm (zusätzlich zu denen, die ich im Laufe mehrerer vorgenommen hatte) Jahre) und fügte für jedes Programm eine neue Konfigurationsskriptoption hinzu, um die Verwendung von groff als Standard-Manpage-zu-HTML-Konverter zu ermöglichen, aber man2html zu verwenden, wenn ich die Option einstelle. Nachdem ich dies getan hatte, entfernte ich dieses Jahr alle von groff generierten HTML-Dateien von meiner Website . Auf der Website gibt es eine "man2html" -Seite, die dies dokumentiert. Das eigentliche Skript ist auf meiner Seite mit verschiedenen Skripten verfügbar .

Einige der Vorschläge und Kommentare scheinen nicht bemerkt zu haben, dass es (mindestens) zwei Programme mit dem Namen man2html gibt:

• das Perl-Skript von Earl Hood (verlinkt von @ criveti-mihai ) und
• ein C-Programm, das ursprünglich von Richard Verhoeven geschrieben wurde (und in dem Beispiel von @ criveti-mihai angenommen wurde ).

Das C-Programm führt seine eigene Formatierung durch und ist nicht auf nroff / groff / Whatever angewiesen. Es kann eine Manpage von der Standardeingabe oder als tatsächliche Datei lesen (unter anderem - siehe Handbuchseite ). Mit einer nroff-Syntax-Handbuchseite "foo.1" können Sie sie mit einem der folgenden Befehle formatieren:

man2html - <foo.1 >foo.1.html
cat foo.1 |man2html - >foo.1.html
man2html foo.1 >foo.1.html

Das Perl-Skript liest formatierte Handbuchseiten, z. B. von nroff(für die OP-Frage ist es ein Wrapper groff). Sie könnten es so verwenden:

nroff -man foo.1 |man2html >foo.1.html

Ich habe untersucht, ob ich das C-Programm als Alternative zum Perl-Skript verwenden kann, habe es aber verworfen, weil

• Die Formatierung der Ausgabe ist nicht gut . Bei einer kurzen Überprüfung mit der terminfo.5-Datei von ncurses kann ich Fehler in der Ausgabeformatierung feststellen.
• Das C-Programm verfügt über einen integrierten Begriff für die Manpage-Makros, der nicht die verschiedenen Fälle (einschließlich des Schreibens neuer Makros) abdeckt, die ich für die Handbuchseiten auf meiner Website benötige.

Im Übrigen werden die in dieser Datei verwendeten Mehrfachumleitungen behandelt (was ein Problem mit Legacy-Troff darstellt - der Grund, warum in den Installationsanweisungen von ncurses die Verwendung von groff in den letzten 20 Jahren empfohlen wurde).