Tout d'abord, il convient de noter qu'il existe plus d'un programme appelé man2html
.
Un utilitaire appelé man2html
est 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 troff
ou en nroff
sortie. Ce programme a été ajouté à la suite homme de Frederico Lucifredi.
Le programme comprend la sémantique des man
et mandoc
macros, 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 man2html
programme 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 troff
macros. 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 M2
registre au moyen duquel vous pouvez écrire du code qui détecte qu'il fonctionne sous man2html
et peut conditionnellement faire certaines choses différemment (faites défiler vers le bas pour un exemple). De plus, j'ai ajouté une .M2SS
commande 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.txr
programme, 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 nroff
nous pouvons regarder une section de la man
sortie:
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
, < b
moyens b
est une variable méta-syntaxique. >> a b
moyen a
est une syntaxe concrète, à côté de laquelle se trouve la méta-syntaxique b
sans espace intermédiaire, et <> a b c
moyen b
est une méta-syntaxique croisée entre a
et c
littéraux.
Ma version améliorée de man2html
comprend 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 man2html
comprend.
troff
? Ce est gratuit.