Man pages: español vs inglés

Estaba revisando la manpage de un comando buscando unas opciones, concretamente la opción -b del comando ping con la idea de hacer un ping a la dirección de broadcast, y ver si me muestra todas las máquinas de la red en el archivo /proc/net/arp junto con su IP y MAC.

Como buen castellano, tengo instalado los paquetes manpages-es y manpages-es-extra para ver por defecto estas en español, pero cual es mi sorpresa al ver que en la página man de pin en español no aparece esta opción. Sin embargo, tras revisar la página man en inglés del comando ping si aparece…

La diferencia está en que la página man en inglés tiene fecha del 9 de Diciembre del 2007, y por el contrario, la traducción de la manpage al español es de la página de 30 de Agosto de 1996, y ha llovido mucho desde entonces.

Sigo pensando que las páginas man son necesarias, y que el proyecto PAMELI de traducción de páginas man es algo vital para el desarrollo y promoción del Software Libre. De hecho, algunos de los libros tan importantes como es Linux un a Nutshell de O’Really, incorpora un listado con todas las páginas man de los distintos comandos, o al menos los más importantes.

Personalmente llevo un tiempo revisando las distintas posibilidades que encuentro para traducir las páginas man al castellano de la forma más sencilla posible y a día de hoy tengo pendiente hacer una prueba, pero por falta de tiempo y recursos aún no me he puesto con ello. Si hay alguien interesado que me quiera echar una mano, que se ponga en contacto conmigo y le comento las diferentes posibilidades que barajo.

Estructura páginas man

No hay mucha información al respecto, de hecho la única fuente que recuerdo es LinuxFocus.org quien publicó un artículo en Nomviembre de 2003 bajo licencia GNU FDL.

[linuxfocus.org] ~$ Escribiendo páginas de manual

info vs man

La verdad es que estoy bastante confuso…

En diversas fuentes de Internet me encuentro textos que indican que el proyecto info sustituye a las páginas man y que se encuentran más actualizadas que estas últimas, y yo me pregunto ¿qué hay de cierto en estas afirmaciones?

En el día a día, a la hora de buscar información prácticamente solo veo referencias a las manpages, y casi nunca se habla de info.De hecho según tengo entendido para empaquetar una aplicación para una distribución un requisito es que los comandos ejecutables incorporen una página man, pero nunca oí nada de info, ¿esto es cierto?.

A ver si averiguo algo…

Referencias:

[es.wikipedia.org] ~$ Man

[es.wikipedia.org] ~$ Texinfo

Manpages

Man es una herramienta de sistemas Unix que se utiliza para documentar y aprender sobre comandos, archivos, llamadas de sistema, etc, en un sistema operativo tal como GNU/Linux. Actualmente se basa en groff y es el sistema más utilizado para la documentación en sistemas Unix, aunque son pocas las características útiles en comparación con el relativamente reciente comando info, que cuenta con características como enlaces que facilitan la interfaz de usuario, ya que al visitar la documentación relativa a un comando se puede saltar a otra página sin tener que salir y ejecutar nuevamente el programa, que es el caso de man.

Utilización

La mayoría de las aplicaciones aportan documentación de manual accesible desde el mismo comando:

man [comando]

Por ejemplo, para saber todo lo relacionado sobre la aplicación man basta con poner en la consola :

man man

Y se mostrará la información necesaria sobre este. En ocasiones el mismo programa posee diversas secciones de manual, cuando esto ocurre suele mostrar un mensaje indicando la sección, como man(1) y man(7), o exit(1) y exit(3). Para acceder a estas secciones basta con indicarlo de la siguiente forma:

man 3 printf

Secciones

El manual normalmente está dividido en ocho secciones numeradas, organizadas como sigue (en BSD, Unix y Linux):

Sección     Descripción
1     Comandos Generales
2     Llamadas al sistema
3     Biblioteca C de funciones
4     Ficheros especiales (normalmente dispositivos, que se pueden encontrar en /dev) y drivers
5     Formatos de fichero y convenciones
6     Juegos y salvapantallas
7     Miscelánea
8     Comandos de administración del sistema y Demonios

En algunos sistemas están disponibles también las siguientes secciones:

Sección     Descripción
0     Archivos de cabecera de la biblioteca estándar de C
9     Rutinas del Kernel
n     Tcl/Tk
x     X Window System

Fuente: Wikipedia
Licencia: GNU FDL

Repositorios manpages

Buscando información sobre las páginas man he encontrado unos repositorios que aunque ya me los había cruzado en alguna ocasión, debido a mi mala cabeza olvido que existen, y puesto que úlimamente he tratado en varias ocasiones el tema de manpages, dejo las referencias para continuar con mi investigación con la mayor cantidad de información posible :p

[manpages.ubuntu.com] ~$ Ubuntu Manpage Repository

[manpages.debian.net] ~$ Debian Hypertext Man Pages

PD. De hecho ya había dejado las referencia hace tan solo unos 15 días :p

[kikuelo.wordpress.com] ~# Linux Man Pages

Algunas dudas sobre lás páginas man (man pages)

Por curiosidad he revisado el código fuente de una página man a voleo para ver qué licencia llevaba, pero no he visto referencia alguna a esta… me pregunto qué licencia llevarán las páginas man y si esta es común a todas ellas. En principio supongo que al venir incluido en la aplicación y no especificarlo, es posible que lleve la misma licencia que esta, que por norma general es GPL, pero también existe la posibilidad de que por ser documentación sea FDL ¿o no?

Por otro lado buscando información sobre la licencia de las páginas man he dado con la Guía Man de Gentoo en la que veo que la estructura seguida en esta distribución para las páginas man no es la misma que para Debian, y por ende que Ubuntu o Guadalinex, por poner algunos ejemplos de distribuciones derivadas de Debian. ¿Y Fedora? ¿Suse?… ¿cada distribución clasifica las manpages de forma diferente?.

Otra duda que me surge es si son la misma página man en distintas distribuciones, por ejemplo, ¿la página man de bash es igual en Debian que en Gentoo?

En fin, espero ir aclarándo mis dudas existenciales :p

manpages de troff a docbook con doclifter

He estado haciendo unas pruebas con doclifter para convertir las páginas man de Troff a Docbook y a modo de log este es el resultado:

$ mkdir temp && cd temp

$ cp /usr/share/man/es/man8/mount.8.gz .

$ gunzip mount.8.gz

$ doclifter mount.8
/usr/bin/doclifter:6373: Warning: ‘with’ will become a reserved keyword in Python 2.6
/usr/bin/doclifter:6374: Warning: ‘with’ will become a reserved keyword in Python 2.6
/usr/bin/doclifter:129: DeprecationWarning: The sre module is deprecated, please import re.
import sys, os, glob, re, sre, string, exceptions, copy, tempfile, time, pprint

Revisando el formato generado, el DOCTYPE es el siguiente:

<?xml version=”1.0″ encoding=”ISO-8859-1″?>
<!DOCTYPE refentry PUBLIC “-//OASIS//DTD DocBook XML V4.1.2//EN” “http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd”>

<refentry id=’mount8′>

<refentryinfo><date>14 Septiembre 1997</date></refentryinfo>
<refmeta>
<refentrytitle>MOUNT</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class=’date’>14 Septiembre 1997</refmiscinfo>
<refmiscinfo class=’source’>Linux 2.0</refmiscinfo>
<refmiscinfo class=’manual’>Manual del Programador</refmiscinfo>
</refmeta>
<refnamediv id=’name’>
<refname>mount</refname>
<refpurpose>monta un sistema de ficheros</refpurpose>
</refnamediv>

<refsect1 id=’sección’><title>Sección</title>
<para></para>
</refsect1>

</refentry>

Suponiendo que la conversión pudiera ser reversible, de forma que se volvieran a poder usar dentro del sistema de páginas man de cualquier Linux (lo cual aún no lo he probado), he probado a convertir a pdf con objeto de ver si el la salida de doclifter está “bien formado”, y este es el resultado:

$ xmlto pdf mount.8.xml
Making portrait pages on a4 paper (210mmx297mm)
PassiveTeX is needed for this format, but it is not installed. Please install
the passivetex package.

Con esta solución no me realiza la conversión, y el paquete PassiveTeX no lo encuentro en la distribución, y tampoco he indagado más en este aspecto (*)

$ docbook2pdf mount.8.xml
Using catalogs: /etc/sgml/catalog
Using stylesheet: /usr/share/docbook-utils/docbook-utils.dsl#print
Working on: /home/enramos/Temp/manpages/doclifter/mount.8.xml
Done.

Me convierte sin problemas a pdf.

$ xsltproc -o mount.fo /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl mount.8.xml
Making portrait pages on A4 paper (210mmx297mm)
Read /usr/share/doc/docbook-xsl/README.Debian.gz section 5(a).

$ fop mount.fo -pdf fop_mount.8.pdf
23-dic-2008 15:40:12 org.apache.fop.hyphenation.Hyphenator getHyphenationTree
GRAVE: Couldn’t find hyphenation pattern en

También obtengo un pdf

(*) Al parecer la conversión de Docbook a pdf no funciona de forma automática con xmlto pero podemos hacerlo en dos pasos:

$ xmlto fo ___.xml

$ fop -fo ___.fo -pdf ___.pdf

Proyecto Paraíso: hacia un mejor sistema de documentación

Revisando formatos de documentación, y como no las ya míticas manpages, he seguido el rastro de doclifter, una herramienta que al parecer convierte el formato Troff, Groff o como se llame a Docbook XML, la cual conozco a raíz de las publicaciones de Ismael Olea en su página personal y en diversas listas de distribución..

Aunque ya había hecho varias indagaciones al respecto, hoy me he encontrado con una página cuyo título “Project Paradise: Towards a Better Documentation System” me ha llamado la atención (¿me estaré soltando ‘algo’ con el Ingles?).

Aunque no lo he leído a fondo, parece ser un proyecto que puso en marcha por Eryc Raymond, a quien tengo pendiente llamar cuando hable Inglés :p, para convertir las páginas man (manpages) a Docbook XML con el objetivo de facilitar su mantenimiento. Para ello se pensaba utilizar una herramienta desarrollada por el mismo llamada doclifter, mayormente la misma que he comentado antes.

The doclifter program translates documents written in troff macros to DocBook. Lifting documents from presentation level to semantic level is difficult, and a really good job requires human polishing, but this tool does about 95% of the work. It aims to do everything that can be mechanized, and to preserve in XML comments any troff-level information that might have structural implications. Also includes manlifter, a driver script that can be used to convert entire manual-page hierarchies.

Desconozco en que quedó el proyecto, pero parece ser que estaba prácticamente conseguido o al menos eso quiero entender el artículo publicado.

On a stock Fedora Core 2 system, doclifter successfully converts over 96% of 10,897 manual pages to validated XML-DocBook . I have about 270 trivial patches for broken markup that push the clean-conversion rate to over 99%, leaving only about 80 pages that cannot be converted. Of these patches, about 40 have been accepted by upstream maintainers.

En fin, habrá que intentar retomarlo… ¿no?

[catb.org]~$ Project Paradise: Towards a Better Documentation System

Linux Man Pages

Mucho se ha hablado sobre las páginas man, utilidad y estructura, pero desde mi punto de vista son una gran fuente de ayuda a la hora de ver las opciones de los distintos comandos que podemos utilizar para shell. Personalmente las utilizo a menudo, y si no las uso más es porque la mayoría de páginas man están en Inglés.

A menudo voy revisando algunos proyectos relacionados con las manpages. Algunos de ellos son:

• [linuxmanpages.com] ~$ Linux Man Pages
• [linux.die.net] ~$ Linux man pages
• [man.he.net] ~$ Linux Man Pages Online
  

DISTRIBUCIONES:

• [manpages.debian.net] ~$ Debian Hypertext Man Pages
• [manpages.ubuntu.com] ~$ Ubuntu Manpage Repository
• [freebsd.org] ~$ FreeBSD Man Pages

Por otro lado también existe info, pero por costumbre suelo utilizar man, y en muy rara ocasión he utilizado info…

Linux Documentation & man pages

Buscando por la red varias utilidades para consola me he cruzado varias referencias hacia una página que al parecer tiene las manpages colgadas de forma online.

Desconozco si están actualizadas o que procedimiento siguen para actualizar sus bases de datos pero posiblemente lo revise cuando empiece a trabajar con las manpages.

[die.net] ~$ Online since 1996, die.net hosts the collective ‘net projects of a few dozen friends in the U.S.