Je voudrais convertir certaines pages de manuel Linux en HTML sans utiliser groff. Mon préjugé contre groff est dû à certains problèmes de rendu PNG qu'il me donne qui semblent être localisés sur Sabayon (car ces problèmes ne semblent pas se produire sur mes machines virtuelles VirtualBox pour d'autres distributions). Je me rends compte que c'est un bug, mais une solution ne semble pas être dans un proche avenir, donc je voudrais demander s'il existe d'autres façons de convertir les pages de manuel Linux en HTML. L'utilisation des pages HTML à http://linux.die.net/man n'est pas une solution acceptable car certaines des pages de manuel qui m'intéressent ne sont pas là (par exemple, emerge(1)n'est pas là).

Il existe de nombreuses alternatives telles que roffit , troff , man2html . Il existe également des navigateurs de pages de manuel en ligne basés sur Perl, tels que manServer .

Mon préféré est pandoc, bien qu'il ne semble malheureusement pas prendre en charge l'entrée ROFF par défaut (bien que vous puissiez probablement l'utiliser si vous devez chaîner plusieurs filtres de transformation ensemble.

exemple man2html:

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

exemple de roffit:

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

Autres outils:

• troffcvt fait à peu près la même chose.
• Le «vrai» troff- Je vais essayer http://heirloom.sourceforge.net/doctools.html . Je pense que Schily a en tête OpenSolaris et ses amis :-).

Ce premier morceau est une déchirure éhontée du site officiel :

mandocest une suite d'outils de compilation mdoc, le rofflangage macro de choix pour les pages de manuel BSD et manle langage historique prédominant pour les manuels UNIX. Il est petit, ISO C, sous licence ISC et assez rapide. Le composant principal de l'ensemble d'outils est le mandocprogramme utilitaire, basé sur le libmandoccompilateur de validation, pour formater la sortie pour les terminaux UNIX (avec prise en charge des paramètres régionaux à caractères larges) , XHTML, HTML, PostScript et PDF.

mandoca été principalement développé sur OpenBSD et est à la fois un projet OpenBSD et BSD.lv. Nous nous efforçons de prendre en charge tous les systèmes d'exploitation libres intéressés, en particulier FreeBSD, NetBSD, DragonFly, illumos, Minix 3 et GNU / Linux, ainsi que tous les systèmes exécutant le pkgsrcsystème de construction de packages portable. Pour soutenir le mandocdéveloppement, pensez à faire un don à la fondation OpenBSD.

pacmanm'informe que la mdocmltaille de mon package installé localement est de 3,28 Mo et qu'il inclut les /usr/binbinaires localisés suivants :

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

Avec ça je peux faire:

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

Vous pouvez appliquer vos propres feuilles de style à votre guise. Toute la documentation est également en ligne . Et tout cela, je pense, est également compilé avec mandoc.

Tout d'abord, il convient de noter qu'il existe plus d'un programme appelé man2html.

Un utilitaire appelé man2htmlest un programme C écrit à la fin des années 1990 par Richard Verhoeven à l'Université de technologie d'Eindhoven à la fin des années 1990. Le programme a des internes sensiblement excentriques. Cependant, il a l'avantage de fonctionner avec la source de la page de manuel brute, plutôt qu'avec troffou en nroffsortie. Ce programme a été ajouté à la suite homme de Frederico Lucifredi.

Le programme comprend la sémantique des manet mandocmacros, et fournit une structure HTML raisonnable. Par exemple, lorsque vous utilisez des paragraphes en retrait, comme ceci:

Mot IP
Définition de
mot.
.RS

le programme affichera une liste de définitions HTML.

Je gère une très grande page de manuel (la plupart d'un mégaoctet de source et près de 400 pages de long, une fois convertie en format PDF de format lettre par groff):

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

Quand j'ai eu besoin de convertir cela en HTML, il y a environ cinq ans, la seule chose que j'ai trouvée qui a fait un travail raisonnable était le man2htmlprogramme C, plus le post-traitement de sa sortie en "saison au goût".

Finalement, je voulais un document HTML de bien meilleure qualité, alors j'ai commencé à écrire des troffmacros. Les limites du programme C sont devenues douloureusement apparentes, alors je l'ai fourché. Sur mon site git, vous pouvez trouver un repo git avec 30 patchs pour man2html . Ces correctifs corrigent un certain nombre de bogues et améliorent le programme avec une capacité bien améliorée d'interpréter les macros troff, les conditions, les boucles et d'autres constructions. J'ai également ajouté un M2registre au moyen duquel vous pouvez écrire du code qui détecte qu'il fonctionne sous man2htmlet peut conditionnellement faire certaines choses différemment (faites défiler vers le bas pour un exemple). De plus, j'ai ajouté une .M2SScommande qui vous permet d'émettre une section d'en-tête HTML personnalisée.

Ma grande page de manuel est hébergée ici . Ceci est produit avec man2html, post-traité par mon genman.txrprogramme, qui réorganise les sections et ajoute des hyperliens dans tout le document. Il réécrit également les liens internes dans la table des matières pour en faire des URL stables (basées sur le hachage plutôt que sur une énumération arbitraire) et rend la table des matières pliable via du Javascript.

Les commandes exactes utilisées par mon Makefile:

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

Pour un exemple de la façon dont la sortie est conditionnellement différente entre HTML et nroffnous pouvons regarder une section de la mansortie:

       9.19.4 Défaillance macro

       Syntaxe:

                (défstruct {<name> | (<name> <arg> *)} <super>
                   <slot-specifier> *)

              La macro defstruct définit un nouveau type de structure et enregistre
              sous <nom>, qui doit être un symbole pouvant être lié, selon
              la fonction de liaison. De même, le nom de chaque <slot> doit
              être également un symbole obligatoire.

Ci-dessus, notez comment les paramètres sont indiqués <angle> <brackets>. Dans la version HTML, ils apparaissent en italique .

La section de syntaxe apparaît dans le code source comme ceci:

.coNP Macro @ defstruct
.synb
.mets (defstruct >> {nom | >> (nom << arg *)} <super
.mets \ \ << slot-specifier *)
.syne

qui est toutes les macros personnalisées définies dans le même document. Sous .mets, < bmoyens best une variable méta-syntaxique. >> a bmoyen aest une syntaxe concrète, à côté de laquelle se trouve la méta-syntaxique bsans espace intermédiaire, et <> a b cmoyen best une méta-syntaxique croisée entre aet clittéraux.

Ma version améliorée de man2htmlcomprend la macro assez compliquée qui implémente ces conventions de balisage.

Notez également comment le manuel a numéroté automatiquement les sections: tout est fait par du code troff, qui man2htmlcomprend.

Depuis OpenSolaris a été mis à disposition en tant que OSS, il existe un gratuit troff.

Un ensemble de sources portées sont ici:

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

mais Heirloom est un projet mort depuis aprox. 2007. Vous aimerez peut-être vérifier

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

où certaines personnes continuent le projet d'héritage mort.

Avec man2htmltroff, vous pouvez créer automatiquement de belles pages de manuel html.

Voir par exemple les pages de manuel SchilliX:

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

avec le Schily Bourne Shell:

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

J'en suis satisfait et avec les bonnes options, vous obtenez des pages de manuel liées à d'autres documents du même groupe. J'utilise par exemple cette commande:

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

qui fait partie du système de fichiers make dans les outils schily. Notez les fichiers ../conf/pre.htmlet le système de fichiers ../conf/post.htmlschily nécessaires au titre et aux autres. Vous voudrez peut-être modifier ces quatre besoins.

Une version améliorée man2thmlfait partie des outils schily (voir en bas de la boshpage de manuel).

BTW: une information drôle: l'ensemble du troffcode source ainsi que toutes les sources pour tous les programmes d'aide comme soelim, tbl... plus la mansource de programme est seulement la moitié du code dont vous avez besoin pour le mandocprogramme et mandocne dispose que d' un très limité tblsoutien pauses homme le plus Solaris pages.

Si vous avez besoin d'un support pour les mandocsources troff formatées de FreeBSD et similaires, j'ai créé un ensemble de macros mandoc qui fonctionnent troff. Vérifiez les sources SchilliX sur: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ Le code en question est dans les fichiers andocet doc*.

Les mansources du programme dans SchilliX-ON ont été modifiées pour appeler nroff -mandocau lieu de nroff -man.

Les problèmes d'OP avec les fichiers PNG correspondent à mon expérience de l'utilisation de groff pour la page de manuel de xterm et la documentation des séquences de contrôle. Le problème est que groff tente de restituer les tableaux sous forme d'image découpée à partir du fichier PDF et qu'il est bogué depuis plusieurs années. Bien que j'utilise le script Perl man2html depuis les années 1990 pour la documentation de ncurses, pour d'autres programmes, j'ai trouvé plus simple de générer des fichiers html et pdf ad hoc à l'aide de groff. Les fichiers PDF fonctionnent bien; les fichiers html ne le font pas.

Dans le même temps, le script Perl avait ses propres problèmes.

Puisque ni l'un ni l'autre ne s'en allait (et parce que les alternatives suggérées n'ont pas été une amélioration, en raison de l'ajout de dépendances ou de l'introduction d'autres limitations), j'ai résolu le problème en apportant des améliorations à man2html (en plus de celles que j'avais apportées au cours de plusieurs ans) et a ajouté une nouvelle option de script de configuration pour chaque programme pour permettre d'utiliser groff comme convertisseur par défaut de page de manuel en html, mais en utilisant man2html lorsque j'ai défini l'option. Après avoir fait cela, j'ai supprimé tous les fichiers HTML générés par groff cette année de mon site Web . Il y a une page "man2html" sur le site Web documentant cela; le script réel est disponible sur ma page de scripts divers .

Certaines suggestions et commentaires ne semblent pas avoir remarqué qu'il existe (au moins) deux programmes nommés man2html:

• le script Perl d'Earl Hood (lié par @ criveti-mihai ), et
• un programme C écrit à l'origine par Richard Verhoeven (et supposé dans l'exemple donné par @ criveti-mihai ).

Le programme C fait son propre formatage, ne dépend pas de nroff / groff / que ce soit. Il peut lire une page de manuel à partir de l'entrée standard, ou comme un fichier réel (entre autres - voir sa page de manuel ). Étant donné la page de manuel nroff-syntax "foo.1", vous pouvez la formater à l'aide de l'une de ces commandes:

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

Le script Perl lit les pages de manuel formatées , par exemple,nroff (pour lesquelles la question OP est un wrapper groff). Vous pouvez l'utiliser comme ceci:

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

J'ai étudié l'utilisation du programme C comme alternative au script Perl, mais je l'ai rejeté parce que

• ça ne fait pas bon travail de formatage de la sortie. Dans une vérification rapide avec le fichier terminfo.5 de ncurses, je peux voir des erreurs dans le formatage de sortie.
• le programme C a une notion intégrée des macros de pages de manuel qui ne couvre pas les différents cas (y compris l'écriture de nouvelles macros) dont j'ai besoin pour les pages de manuel sur mon site Web.

Soit dit en passant, il gère les multiples redirections utilisées dans ce fichier (ce qui est un problème avec troff hérité - la raison pour laquelle les instructions d'installation de ncurses ont conseillé d'utiliser groff depuis 20 ans).