Em primeiro lugar, deve-se notar que há mais de um programa chamado man2html .
Um utilitário chamado man2html é originalmente um programa C escrito no final dos anos 90 por Richard Verhoeven na Universidade de Tecnologia de Eindhoven no final dos anos 90. O programa tem internals substancialmente peculiares. No entanto, ele tem a vantagem de funcionar com a origem da página de manual bruta, em vez de troff ou nroff output. Este programa foi adicionado ao homem de Frederico Lucifredi.
O programa compreende a semântica das macros man e mandoc e gera uma estrutura HTML razoável. Por exemplo, quando você usa parágrafos recuados, assim:
.IP word
Definition of
word.
.RS
o programa colocará uma lista de definições HTML.
Eu mantenho uma página de manual muito grande (a maioria de um megabyte de fonte e quase 400 páginas, quando convertida para PDF em tamanho de letra por groff ):
$ ls -l txr.1
-rw-rw-r-- 1 kaz kaz 980549 Jan 3 11:38 txr.1
Quando precisei converter isso em HTML, há cinco anos, a única coisa que encontrei que fez um trabalho razoável foi o programa man2html C, além de pós-processamento de sua saída para "temperar a gosto".
Eventualmente, eu queria um documento HTML de qualidade muito melhor, então comecei escrevendo troff macros. As limitações do programa C tornaram-se dolorosamente aparentes, então eu o forcei. No meu site git, você pode encontrar um git repo com 30 patches para man2html . Esses patches corrigem vários bugs e aprimoram o programa com uma capacidade muito melhor de interpretar macros de troff, condicionais, loops e outras construções. Eu também adicionei um M2 register por meio do qual você pode escrever código que detecta que ele está sendo executado em man2html e pode condicionalmente fazer algumas coisas de forma diferente (role para baixo para ver um exemplo). Além disso, adicionei um comando .M2SS que permite emitir uma seção de cabeçalho HTML personalizada.
Minha grande página de manual é hospedada aqui . Isso é produzido com man2html , pós-processado pelo meu programa genman.txr , que reorganiza as seções e adiciona hiperlinks em todo o documento. Ele também reescreve os links internos no índice para serem URLs estáveis (com base em hashing em vez de enumeração arbitrária) e torna o índice recolhível através de algum Javascript.
Os comandos exatos usados pelo meu Makefile :
man2html txr.1 | ./txr genman.txr - > txr-manpage.html
tbl txr.1 | pdfroff -man --no-toc - > txr-manpage.pdf
Para um exemplo de como a saída é condicionalmente diferente entre HTML e nroff , podemos ver uma seção da man output:
9.19.4 Macro defstruct
Syntax:
(defstruct {<name> | (<name> <arg>*)} <super>
<slot-specifier>*)
The defstruct macro defines a new structure type and registers
it under <name>, which must be a bindable symbol, according to
the bindable function. Likewise, the name of every <slot> must
also be a bindable symbol.
Acima, observe como os parâmetros são indicados em <angle> <brackets> . Na versão HTML, eles aparecem em itálico .
A seção de sintaxe aparece no código-fonte assim:
.coNP Macro @ defstruct
.synb
.mets (defstruct >> { name | >> ( name << arg *)} < super
.mets \ \ << slot-specifier *)
.syne
, que são todas as macros personalizadas definidas no mesmo documento. Em .mets , < b significa b é uma variável meta-sintática. >> a b significa a é uma sintaxe concreta, ao lado da qual é a meta-sintática b sem nenhum espaço intermediário e <> a b c significa b é uma metassintática triturada entre a e c literais.
Minha versão aprimorada de man2html entende a macro bastante complicada que implementa essas convenções de marcação.
Além disso, observe como o manual tem seções numeradas automaticamente: isso é feito pelo código troff, que man2html entende.
