¿Cómo convierto páginas de manual de Linux a HTML sin usar groff?

11

Me gustaría convertir algunas páginas de manual de Linux a HTML sin usar groff. Mi prejuicio contra groff se debe a algunos problemas de representación PNG que me está dando que parece estar localizado en Sabayon (ya que estos problemas no parecen ocurrir en mis máquinas virtuales VirtualBox para otras distribuciones). Me doy cuenta de que esto es un error, pero parece que no habrá una solución en el futuro cercano, por lo que me gustaría preguntar si hay otras formas de convertir páginas de manual de Linux a HTML. El uso de las páginas HTML en http://linux.die.net/man no es una solución aceptable ya que algunas de las páginas de manual que me interesan no están allí (por ejemplo, emerge(1)no están allí).

BH2017
fuente
¿Por qué no lo usas troff? Es gratis.
schily
No sé cómo, aprendí a usar groff leyendo algunas respuestas en este sitio y sitios relacionados. Si escribe una respuesta relacionada con troff, puedo aceptarla, dependiendo de la calidad de las otras respuestas a esta pregunta.
BH2017
¿Por qué no enviar un informe de error a Sabayon y hacer que solucionen sus errores?
cas
@cas El primer enlace (los problemas de representación de PNG) es un informe de error de Sabayon que presenté cuando hice esta pregunta.
BH2017
intente encontrar y corregir la fuente del warning: can't find font `b'mensaje; esa puede ser la causa, ya que los archivos png creados tienden a ser solo texto en formato gráfico. posiblemente falta un paquete de fuentes que necesita ser instalado.
cas

Respuestas:

10

Hay muchas alternativas como roffit , troff , man2html . También hay navegadores de páginas de manual en línea basados ​​en Perl, como manServer .

Mi favorito es pandoc, aunque lamentablemente no parece admitir la entrada ROFF de forma predeterminada (aunque probablemente pueda usarlo si necesita encadenar múltiples filtros de transformación juntos).

Ejemplo de man2html:

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

roffit ejemplo:

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

Otras herramientas:

Criveti Mihai
fuente
Ah, debo aclarar que no solo estoy interesado en el nombre de los programas, sino en cómo usarlos para convertir páginas de manual a HTML. Por lo tanto, elija al menos uno de estos programas y muéstreme cómo convertir páginas de manual a HTML con él.
BH2017
Gracias por la edición, mucho mejor! Aunque tengo un par de preguntas. ¿Por qué redirigir stderr al archivo html en el man2htmlejemplo? ¿Y por qué redirigir a un archivo /var/www/html? No hay necesidad de un servidor web, solo redirija a un archivo local y puede apuntar su navegador a él. Además, ¿verificaste tu man2htmlsalida? Lo probé en mi Arch y no produce resultados formateados.
terdon
No es necesario redirigir stderr, ignore eso :-). Lo redirigí a / var / www / html para poder ver los resultados durante mis pruebas (estoy usando un sistema remoto a través de ssh). No tiene que hacerlo: usar un navegador localmente funciona bien. He verificado ambos, y se ven bien en mi sistema. Sin embargo, no verifiqué si pueden producir PNG (o cualquiera que sea el problema con Arch).
Criveti Mihai
Me gusta esta respuesta, creo que terminaré aceptando, pero hay un último problema con esta respuesta. Ver Sabayon usa páginas de manual en .bz2formato en lugar de .gz, ¿podría reescribir su respuesta en consecuencia? Como modificar las líneas zcat con las que funcionarán con páginas man comprimidas con bzip2.
BH2017
man2html necesita salida nroff y no funciona en la entrada trodd Su ejemplo es incorrecto.
schily
6

Este primer bit es un desgarro desvergonzado del sitio web oficial :

mandoces un conjunto de herramientas de compilación mdoc, el rofflenguaje macro preferido para las páginas de manual de BSD y manel lenguaje histórico predominante para los manuales de UNIX. Es pequeño, ISO C, con licencia ISC y bastante rápido. El componente principal del conjunto de herramientas es el mandocprograma de utilidad, basado en el libmandoccompilador de validación, para formatear la salida para terminales UNIX (con soporte para configuraciones regionales de caracteres anchos) , XHTML, HTML, PostScript y PDF.

mandocse ha desarrollado principalmente en OpenBSD y es tanto un proyecto OpenBSD como un proyecto BSD.lv. Nos esforzamos por admitir todos los sistemas operativos gratuitos interesados, en particular FreeBSD, NetBSD, DragonFly, illumos, Minix 3 y GNU / Linux, así como todos los sistemas que ejecutan el pkgsrcsistema portátil de compilación de paquetes. Para apoyar el mandocdesarrollo, considere donar a la fundación OpenBSD.

pacmanme informa que mi mdocmltamaño de paquete instalado localmente es 3.28mb, y que incluye los siguientes /usr/binbinarios ubicados:

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

Con ella puedo hacer:

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

ingrese la descripción de la imagen aquí

Puede aplicar sus propias hojas de estilo a su gusto. Toda la documentación también está en línea . Y todo eso, como creo, también se compila mandoc.

mikeserv
fuente
El proyecto ha sido renombrado a mandoc.
Franklin Yu
5

En primer lugar, debe tenerse en cuenta que hay más de un programa llamado man2html.

Una utilidad llamada man2htmles un programa en C originalmente escrito a fines de la década de 1990 por Richard Verhoeven en la Universidad Tecnológica de Eindhoven a fines de la década de 1990. El programa tiene partes internas sustancialmente extravagantes. Sin embargo, tiene la ventaja de que funciona con la fuente de página del manual de crudo, en lugar de troffo nroffsalida. Este programa se agregó a la suite de hombre de Frederico Lucifredi.

El programa entiende la semántica de la many mandocmacros, y emite una estructura HTML razonable. Por ejemplo, cuando usa párrafos sangrados, así:

Palabra .IP
Definicion de
palabra.
.RS

el programa publicará una lista de definiciones HTML.

Mantengo una página de manual muy grande (la mayoría de un megabyte de fuente, y casi 400 páginas de largo, cuando se convierte a PDF de tamaño carta por groff):

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

Cuando necesitaba convertir esto a HTML, hace unos cinco años, lo único que encontré que hizo un trabajo razonable fue el man2htmlprograma C, más el procesamiento posterior de su salida a "temporada al gusto".

Eventualmente, quería un documento HTML de mejor calidad, así que comencé a escribir troffmacros. Las limitaciones del programa C se volvieron dolorosamente aparentes, así que lo bifurqué. En mi sitio de git, puede encontrar un repositorio de git con 30 parches para man2html . Estos parches corrigen una serie de errores y mejoran el programa con una capacidad mucho mejor para interpretar macros de troff, condicionales, bucles y otras construcciones. También agregué un M2registro mediante el cual puede escribir código que detecta que se está ejecutando man2htmly puede hacer condicionalmente algunas cosas de manera diferente (desplácese hacia abajo para ver un ejemplo). Además, agregué un .M2SScomando que le permite emitir una sección de encabezado HTML personalizado.

Mi página de manual grande está alojada aquí . Esto se produce con man2htmlpostprocesado por mi genman.txrprograma, que reorganiza las secciones y agrega hipervínculos en todo el documento. También reescribe los enlaces internos en la tabla de contenido para que sean URL estables (basadas en hashing en lugar de enumeración arbitraria) y hace que la tabla de contenido se pueda contraer mediante algún Javascript.

Los comandos exactos utilizados por mi Makefile:

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

Para ver un ejemplo de cómo la salida es condicionalmente diferente entre HTML y nroffpodemos ver una sección de la mansalida:

       9.19.4 Macrodestrucción

       Sintaxis:

                (defstruct {<name> | (<name> <arg> *)} <super>
                   <slot-specifier> *)

              La macro defstruct define un nuevo tipo de estructura y registra
              debajo de <nombre>, que debe ser un símbolo enlazable, de acuerdo con
              La función enlazable. Del mismo modo, el nombre de cada <slot> debe
              también sea un símbolo enlazable.

Arriba, observe cómo se denotan los parámetros <angle> <brackets>. En la versión HTML, aparecen en cursiva .

La sección de sintaxis aparece en el código fuente de esta manera:

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

que son todas las macros personalizadas definidas en el mismo documento. Debajo .mets, < bmedias bes una variable meta-sintáctica. >> a bsignifica aes una sintaxis concreta, junto a la cual está la meta-sintaxis bsin ningún espacio intermedio, y <> a b csignifica bes una meta- sintaxis crujida entre ay cliterales.

Mi versión mejorada de man2htmlcomprende la macro bastante complicada que implementa estas convenciones de marcado.

Además, tenga en cuenta cómo el manual ha numerado automáticamente las secciones: todo esto se hace por código troff, que man2htmlcomprende.

Kaz
fuente
1

Desde que OpenSolaris se puso a disposición como OSS, existe una versión gratuita troff.

Aquí hay un conjunto de fuentes portadas:

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

pero Heirloom es un proyecto muerto desde aprox. 2007. Puede que desee consultar

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

donde algunas personas continúan el proyecto de la herencia muerta.

Junto con man2html, troff le permite crear automáticamente páginas de manual html agradables.

Consulte, por ejemplo, las páginas de manual de SchilliX:

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

con el Schily Bourne Shell:

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

Estoy contento con esto y con las opciones correctas, obtienes páginas man vinculadas a otra documentación del mismo grupo. Yo uso, por ejemplo, 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

eso es parte del sistema de archivos make en las herramientas schily. Tenga en cuenta los archivos ../conf/pre.htmly ../conf/post.htmldel schily makefilesystem que se necesitan para el título y otros. Es posible que desee cambiar estas cuatro necesidades.

Un mejorado man2thmles parte de las herramientas inteligentes (ver la parte inferior de la boshpágina del manual).

Por cierto: una información divertida: el troffcódigo fuente completo más todas las fuentes para todos los programas auxiliares como soelim, tbl... más la manfuente del programa es solo la mitad del código que necesita para el mandocprograma y mandoctiene solo un tblsoporte muy limitado que rompe la mayoría del hombre de Solaris páginas

Si necesita soporte para mandocfuentes de troff formateadas de FreeBSD y similares, creé un conjunto de macros mandoc que funcionan troff. Consulte las fuentes de SchilliX en: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ El código en cuestión está en los archivos andocy doc*.

Las manfuentes del programa en SchilliX-ON se han cambiado para llamar en nroff -mandoclugar de nroff -man.

astuto
fuente
¡Ah, me ganaste! Acabo de instalar heirloom-doctoolstambién. Tuve que tocar el violín mk.config:-).
Criveti Mihai
0

Los problemas de OP con los archivos PNG coinciden con mi experiencia al usar groff para la página del manual de xterm y la documentación de las secuencias de control. El problema es que Groff está tratando de representar tablas como una imagen recortada del archivo PDF, y que ha tenido errores durante varios años. Si bien he usado el script manlhtml de Perl desde la década de 1990 para la documentación de ncurses, para otros programas me resultó más sencillo generar archivos html y pdf ad hoc utilizando groff. Los archivos PDF funcionan bien; los archivos html no.

Al mismo tiempo, el script de Perl tenía sus propios problemas.

Como ninguno de los dos iba a desaparecer (y debido a que las alternativas sugeridas no han sido una mejora, debido a la adición de dependencias o la introducción de otras limitaciones), resolví el problema haciendo mejoras en man2html (además de las que había hecho en el transcurso de varios años) y agregó una nueva opción de script de configuración para cada programa para permitir el uso de groff como una página de manual predeterminada para el convertidor html, pero usando man2html cuando configuro la opción. Una vez hecho esto, eliminé todos los archivos html generados por groff este año de mi sitio web . Hay una página "man2html" en el sitio web que documenta esto; el script real está disponible en mi página de varios scripts .

Parece que algunas de las sugerencias y comentarios no han notado que hay (al menos) dos programas llamados man2html:

  • el guión Perl de Earl Hood (vinculado por @ criveti-mihai ), y
  • un programa en C originalmente escrito por Richard Verhoeven (y asumido en el ejemplo dado por @ criveti-mihai ).

El programa C tiene su propio formato, no se basa en nroff / groff / lo que sea. Se puede leer una página de manual de la entrada estándar, o como un archivo real (entre otras cosas - véase la página del manual ). Dada una página de manual de sintaxis nroff "foo.1", puede formatearla usando cualquiera de estos comandos:

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

El script de Perl lee páginas de manual formateadas , por ejemplo, de nroff(que para la pregunta de OP es un contenedor groff). Podrías usarlo así:

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

Investigué el uso del programa C como alternativa al script Perl, pero lo descarté porque

  • no hace un buen trabajo formateando la salida. En una comprobación rápida con el archivo terminfo.5 de ncurses, puedo ver errores en el formato de salida.
  • el programa C tiene una noción incorporada de las macros de la página de manual que no cubre los diversos casos (incluida la escritura de nuevas macros) que necesito para las páginas del manual en mi sitio web.

Por cierto, maneja los múltiples redireccionamientos utilizados en este archivo (lo cual es un problema con troff heredado, la razón por la cual las instrucciones de instalación de ncurses han aconsejado usar groff durante los últimos 20 años).

Thomas Dickey
fuente
Como se mencionó anteriormente: man2htmltoma la salida nroff como entrada, por lo tanto, no puede darle un archivo fuente de página de manual como entrada.
schily
1
@shily Eso depende de lo man2htmlque estés hablando.
Kaz
> el programa C tiene una noción incorporada de las macros de la página de manual que no cubre los diversos casos (incluida la escritura de nuevas macros) que necesito para las páginas del manual en mi sitio web. Mire aquí: kylheku.com/cgit/man/log
Kaz