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í).

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:

• troffcvt hace casi lo mismo.
• Lo 'real' troff: voy a probar http://heirloom.sourceforge.net/doctools.html . Sospecho que schily tiene OpenSolaris y sus amigos en mente :-).

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

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.

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.

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.

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).