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á).
man
conversion
html
BH2017
fonte
fonte
troff
? É de graça.warning: can't find font `b'
mensagem - isso pode ser a causa, pois os arquivos png criados tendem a ser apenas texto em formato gráfico. possivelmente um pacote de fontes ausente que precise ser instalado.Respostas:
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:
roffit exemplo:
Outras ferramentas:
troff
- Experimente http://heirloom.sourceforge.net/doctools.html . Suspeito que schily tenha o OpenSolaris e os amigos em mente :-).fonte
man2html
exemplo? E por que redirecionar para um arquivo/var/www/html
? Não há necessidade de um servidor da Web, basta redirecionar para um arquivo local e você pode apontar seu navegador para ele. Além disso, você verificou suaman2html
saída? Eu tentei no meu Arch e não produz saída formatada..bz2
formato em vez de.gz
, então você poderia reescrever sua resposta de acordo? Como modificar as linhas do zcat com aquelas que funcionarão com as páginas de manual compactadas pelo bzip2.Este primeiro bit é uma cópia desavergonhada do site oficial :
pacman
informa que meumdocml
tamanho do pacote instalado localmente é 3,28mb e que inclui os seguintes/usr/bin
binários localizados:Com ele eu posso fazer:
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
.fonte
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 detroff
ounroff
saída. Este programa foi adicionado à suíte de homens de Frederico Lucifredi.O programa compreende a semântica do
man
emandoc
macros, e produz uma estrutura HTML razoável. Por exemplo, quando você usa parágrafos recuados, assim: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
):Quando eu precisei converter isso para HTML, há cinco anos, a única coisa que achei que fez um trabalho razoável foi o
man2html
programa 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
troff
macros. 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 umM2
registro por meio do qual você pode escrever um código que detecta que está sendo executadoman2html
e pode fazer algumas coisas condicionalmente de maneira diferente (role para baixo, por exemplo). Também adicionei um.M2SS
comando 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 meugenman.txr
programa, 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
:Para um exemplo de como a saída é condicionalmente diferente entre HTML e
nroff
podemos ver uma seção daman
saída: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:
que são todas as macros personalizadas definidas no mesmo documento. Sob
.mets
,< b
meiosb
é uma variável meta-sintática.>> a b
meiosa
é uma sintaxe concreta, ao lado da qual é a meta-sintática,b
sem nenhum espaço intermediário, e<> a b c
meiosb
é uma meta-sintática triturada entrea
ec
literais.Minha versão aprimorada do
man2html
compreende 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
man2html
compreende.fonte
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:
isso faz parte do sistema de arquivos make nas ferramentas inteligentes. Observe os arquivos
../conf/pre.html
e../conf/post.html
o sistema de makefiles que são necessários para o título e outros. Você pode alterar essas quatro necessidades.Um aprimorado
man2thml
faz parte das ferramentas inteligentes (consulte a parte inferior dabosh
página do manual).BTW: a informação engraçado: todo o
troff
código-fonte, mais todas as fontes para todos os programas auxiliares comosoelim
,tbl
... mais oman
código fonte do programa é apenas metade do código que você precisa para omandoc
programa emandoc
tem apenas um muito limitadotbl
apoio que breaks mais homem Solaris Páginas.Se você precisar de suporte para
mandoc
fontes de troff formatadas do FreeBSD e similares, criei um conjunto de macros mandoc que funcionamtroff
. 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 arquivosandoc
edoc*
.As
man
fontes do programa no SchilliX-ON foram alteradas para chamar emnroff -mandoc
vez denroff -man
.fonte
heirloom-doctools
também. Teve que mexermk.config
:-).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 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:
O script Perl lê páginas de manual formatadas , por exemplo, de
nroff
(para a qual a pergunta do OP é um invólucrogroff
). Você poderia usá-lo assim:Eu investiguei usando o programa C como uma alternativa ao script Perl, mas o descartei porque
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).
fonte
man2html
recebe nroff como entrada, portanto, você não pode fornecer um arquivo de origem da página de manual como entrada.man2html
você está falando.