Gostaria de converter algumas páginas de manual do Linux em HTML sem usar o groff. Meu preconceito contra o groff deve-se a alguns problemas de renderização PNG que estão me dando a impressão de estar localizado no Sabayon (pois esses problemas não parecem ocorrer nas minhas VMs do VirtualBox para outras distribuições). Sei que isso é um bug, mas uma solução parece não estar no futuro próximo, então gostaria de perguntar se existem outras maneiras de converter as páginas de manual do Linux em HTML. Usar as páginas HTML em http://linux.die.net/man não é uma solução aceitável, pois algumas das páginas de manual nas quais estou interessado não estão lá (por exemplo, emerge(1)não estão lá).

Existem muitas alternativas, como roffit , troff , man2html . Também há navegadores de páginas de manual online baseados em perl, como o manServer .

O meu favorito é que pandoc, embora infelizmente não pareça suportar a entrada ROFF por padrão (embora você provavelmente possa usá-la se precisar encadear vários filtros de transformação).

exemplo man2html:

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

roffit exemplo:

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

Outras ferramentas:

• O troffcvt faz a mesma coisa.
• O 'real' troff- Experimente http://heirloom.sourceforge.net/doctools.html . Suspeito que schily tenha o OpenSolaris e os amigos em mente :-).

Este primeiro bit é uma cópia desavergonhada do site oficial :

mandocé um conjunto de ferramentas compiladas mdoc, o roffidioma de macro preferido nas páginas de manual do BSD e mano idioma histórico predominante nos manuais do UNIX. É pequeno, com licença ISO C, ISC e bastante rápido. O principal componente do conjunto de ferramentas é o mandocprograma utilitário, baseado no libmandoccompilador de validação, para formatar a saída dos terminais UNIX (com suporte para localidades de caracteres largos) , XHTML, HTML, PostScript e PDF.

mandocfoi desenvolvido predominantemente no OpenBSD e é um projeto do OpenBSD e do BSD.lv. Nós nos esforçamos para oferecer suporte a todos os sistemas operacionais gratuitos interessados, em particular FreeBSD, NetBSD, DragonFly, illumos, Minix 3 e GNU / Linux, bem como todos os sistemas executando o pkgsrcsistema de compilação de pacotes portáteis. Para apoiar o mandocdesenvolvimento, considere fazer uma doação para a fundação OpenBSD.

pacmaninforma que meu mdocmltamanho do pacote instalado localmente é 3,28mb e que inclui os seguintes /usr/binbinários localizados:

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

Com ele eu posso fazer:

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

Você pode aplicar suas próprias folhas de estilo como desejar. Toda a documentação está online também. E tudo isso, como eu acho, também é compilado mandoc.

Em primeiro lugar, deve-se notar que há mais de um programa chamado man2html.

Um utilitário chamado man2htmlé um programa C originalmente escrito no final dos anos 90 por Richard Verhoeven na Universidade de Tecnologia de Eindhoven no final dos anos 90. O programa possui internos substancialmente peculiares. No entanto, tem a vantagem de que ele funciona com o código fonte da página homem cru, em vez de troffou nroffsaída. Este programa foi adicionado à suíte de homens de Frederico Lucifredi.

O programa compreende a semântica do mane mandocmacros, e produz uma estrutura HTML razoável. Por exemplo, quando você usa parágrafos recuados, assim:

Palavra .IP
Definição de
palavra.
.RS

o programa publicará uma lista de definições HTML.

Eu mantenho uma página de manual muito grande (a maioria com um megabyte de origem e quase 400 páginas, quando convertida em PDF em tamanho Carta groff):

$ ls -l txr.1
-rw-rw-r-- 1 kaz kaz 980549 3 de janeiro às 11:38 txr.1

Quando eu precisei converter isso para HTML, há cinco anos, a única coisa que achei que fez um trabalho razoável foi o man2htmlprograma C, além do pós-processamento de sua saída para "temperar a gosto".

Eventualmente, eu queria um documento HTML de qualidade muito melhor, então comecei a escrever troffmacros. As limitações do programa C se tornaram dolorosamente aparentes, então eu bifurei. No meu site git, você pode encontrar um repositório git com 30 patches para man2html . Esses patches corrigem vários bugs e aprimoram o programa com uma capacidade muito melhorada de interpretar macros, condicionais, loops e outras construções. Também adicionei um M2registro por meio do qual você pode escrever um código que detecta que está sendo executado man2htmle pode fazer algumas coisas condicionalmente de maneira diferente (role para baixo, por exemplo). Também adicionei um .M2SScomando que permite emitir uma seção de cabeçalho HTML personalizada.

Minha grande página de manual está hospedada aqui . Isso é produzido com man2html, pós-processado pelo meu genman.txrprograma, que reorganiza as seções e adiciona hiperlinks ao longo do documento. Ele também reescreve os links internos no índice para ser URLs estáveis ​​(com base no hash e não na enumeração arbitrária) e torna o índice recolhível por meio 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 nroffpodemos ver uma seção da mansaída:

       9.19.4 Desfiguração de macro

       Sintaxe:

                (defstruct {<name> | (<name> <arg> *)} <super>
                   <especificador de slot> *)

              A macro defstruct define um novo tipo de estrutura e registra
              sob <name>, que deve ser um símbolo vinculável, de acordo com
              a função vinculável. Da mesma forma, o nome de cada <slot> deve
              também ser um símbolo vinculável.

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:

Macro .coNP @ defstruct
.synb
.mets (defstruct >> {name | >> (nome << arg *)} <super
.mets \ \ << especificador de slot *)
.syne

que são todas as macros personalizadas definidas no mesmo documento. Sob .mets, < bmeios bé uma variável meta-sintática. >> a bmeios aé uma sintaxe concreta, ao lado da qual é a meta-sintática, bsem nenhum espaço intermediário, e <> a b cmeios bé uma meta-sintática triturada entre ae cliterais.

Minha versão aprimorada do man2htmlcompreende a macro bastante complicada que implementa essas convenções de marcação.

Além disso, observe como o manual numerou automaticamente as seções: tudo isso é feito pelo código de troff, que man2htmlcompreende.

Como o OpenSolaris foi disponibilizado como OSS, existe um serviço gratuito troff.

Um conjunto de fontes portadas está aqui:

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

mas Heirloom é um projeto morto desde aprox. 2007. Você pode verificar

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

onde algumas pessoas continuam o projeto da herança morta.

Juntamente com man2html, o troff permite criar automaticamente boas páginas de manual html.

Veja, por exemplo, as páginas de manual do SchilliX:

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

com o Schily Bourne Shell:

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

Estou feliz com isso e com as opções corretas, você recebe páginas de manual vinculadas a outras documentações do mesmo grupo. Eu uso, por exemplo, este comando:

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

isso faz parte do sistema de arquivos make nas ferramentas inteligentes. Observe os arquivos ../conf/pre.htmle ../conf/post.htmlo sistema de makefiles que são necessários para o título e outros. Você pode alterar essas quatro necessidades.

Um aprimorado man2thmlfaz parte das ferramentas inteligentes (consulte a parte inferior da boshpágina do manual).

BTW: a informação engraçado: todo o troffcódigo-fonte, mais todas as fontes para todos os programas auxiliares como soelim, tbl... mais o mancódigo fonte do programa é apenas metade do código que você precisa para o mandocprograma e mandoctem apenas um muito limitado tblapoio que breaks mais homem Solaris Páginas.

Se você precisar de suporte para mandocfontes de troff formatadas do FreeBSD e similares, criei um conjunto de macros mandoc que funcionam troff. Verifique as fontes do SchilliX em: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ O código em questão está nos arquivos andoce doc*.

As manfontes do programa no SchilliX-ON foram alteradas para chamar em nroff -mandocvez de nroff -man.

Os problemas do OP com arquivos PNG correspondem à minha experiência usando o groff para a página de manual do xterm e a documentação das seqüências de controle. O problema é que o groff está tentando renderizar tabelas como uma imagem cortada do arquivo PDF e que está com erros há vários anos. Embora eu tenha usado o script Perl man2html desde os anos 90 para documentação de ncurses, em outros programas achei mais simples gerar arquivos ad hoc html e pdf usando groff. Arquivos PDF funcionam bem; os arquivos html não.

Ao mesmo tempo, o script Perl tinha seus próprios problemas.

Como nenhum dos dois estava indo embora (e como as alternativas sugeridas não foram uma melhoria, devido à adição de dependências ou à introdução de outras limitações), resolvi o problema realizando melhorias no man2html (além daquelas que eu havia feito ao longo de várias anos) e adicionou uma nova opção de script de configuração para cada programa para permitir o uso do groff como uma página de manual padrão para o conversor html, mas usando o man2html quando eu definir a opção. Tendo feito isso, removi todos os arquivos html gerados por groff deste ano do meu site . Há uma página "man2html" no site que documenta isso; o script real está disponível na minha página de scripts diversos .

Algumas das sugestões e comentários parecem não ter percebido que existem (pelo menos) dois programas chamados man2html:

• o script Perl de Earl Hood (vinculado por @ criveti-mihai ) e
• um programa em C originalmente escrito por Richard Verhoeven (e assumido no exemplo dado por @ criveti-mihai ).

O programa C faz sua própria formatação, não depende de nroff / groff / seja o que for. Ele pode ler uma página de manual a partir da entrada padrão ou como um arquivo real (entre outras coisas - consulte sua página de manual ). Dada uma página de manual nroff-syntax "foo.1", você pode formatá-la usando qualquer um destes comandos:

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

O script Perl lê páginas de manual formatadas , por exemplo, de nroff(para a qual a pergunta do OP é um invólucro groff). Você poderia usá-lo assim:

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

Eu investiguei usando o programa C como uma alternativa ao script Perl, mas o descartei porque

• não faz um bom trabalho de formatar a saída. Em uma verificação rápida do arquivo terminfo.5 do ncurses, posso ver erros na formatação da saída.
• o programa C possui uma noção interna das macros da página de manual, que não abrange os vários casos (incluindo a gravação de novas macros), necessários para as páginas de manual do meu site.

Aliás, ele lida com os vários redirecionamentos usados ​​neste arquivo (o que é um problema com a troff legada - o motivo pelo qual as instruções de instalação do ncurses recomendam o uso do groff nos últimos 20 anos).