Escribiendo p�ginas de manual

ArticleCategory: Hardware

UNIXBasics

AuthorImage:[Here we need a little image from you]

TranslationInfo:[Author + translation history. mailto: or http://homepage]

original in en Guido Socher

en to es Roberto Hernando Velasco

AboutTheAuthor:[A small biography about the author]

A Guido le gusta Linux porque es muy flexible y ofrece muchas m�s posibilidades que cualquier otro sistema operativo.

Abstract:

Todo buen programa que se pueda usar desde la shell de UNIX deber�a estar documentado en su propia p�gina de manual. Este tutorial es una breve introducci�n a la creaci�n de p�ginas de manual.

ArticleIllustration:

ArticleBody:

Introducci�n

A menudo la documentaci�n es m�s importante que el propio software, especialmente cuando el autor no sea el �nico que va a utilizar dicho software. Incluso cuando escribo un programa que no pienso publicar tambi�n escribo su documentaci�n, ya que varios meses despu�s podr�a olvidar c�mo usar el programa y con una buena documentaci�n sabr� en pocos segundos c�mo hacerlo.

Las utilidades tradicionales de Linux en l�nea de comandos siempre se han documentado en p�ginas de manual. Un simple man comando nos dir� c�mo utilizar el comando.

Las ventajas de las p�ginas de manual sobre otras formas de documentaci�n son

Se pueden ver en pocos segundos en un terminal Linux
Se pueden convertir f�cilmente a otros formatos: HTML, PDF, Postscript, Texto,...
Las p�ginas de manual no s�lo se pueden ver en ventanas de terminal, sino tambi�n desde otros programas como konqueror (basta con teclear: man:comando)

Las secciones

Las p�ginas de manual est�n estructuradas en secciones, de la misma forma que un libro est� estructurado en cap�tulos. Por ejemplo, existen dos p�ginas de manual de printf. Una para la funci�n de biblioteca C (secci�n 3) y la otra para el comando de shell (secci�n 1):

> whichman -0 printf
/usr/share/man/man1/printf.1.bz2
/usr/share/man/man3/printf.3.bz2

Las diferentes secciones son:

Secci�n
   1    Comandos de usuario.
   2    Llamadas al sistema, es decir, funciones
        provistas por el kernel.
   3    Subrutinas, es decir, funciones de biblioteca.
   4    Dispositivos, es decir, ficheros especiales en el
        directorio /dev.
   5    Descripciones de formato de ficheros, e.g. /etc/passwd.
   6    Juegos, auto-explicativo.
   7    Miscel�nea, e.g. paquetes de macro, convenciones.
   8    Herramientas de administraci�n del sistema que s�lo
        puede ejecutar el superusuario.
   9    Otros.
   n    Nueva documentaci�n, que deber�a cambiarse a una secci�n
        m�s apropiada.
   l    Documentaci�n local sobre este sistema en particular.

De esta forma con "man 1 printf" obtenemos la documentaci�n sobre el comando de shell printf y con "man 3 printf" se mostrar� la descripci�n de la funci�n de biblioteca C. Ejecutando exactamente "man printf" se imprimir� la p�gina que primero se encuentre (normalmente printf de la secci�n 1).

Para comprobar si existen varias versiones de p�ginas de manual se puede utilizar el comando wichman como se ha mostrado anteriormente (descargable desde mi p�gina, o bien tecleando simplemente "man:printf" en konqueror que nos devolver�:

MANPATH

El comando man busca las p�ginas de manual seg�n el valor de la variable de entorno MANPATH. Desgraciadamente muchas distribuciones Linux establecen esta variable de forma incorrecta. A menudo no se incluye /usr/lib/perl5/man, que contiene un valioso conjunto de documentaci�n sobre todas las funciones perl. Puede a�adirlo a su MANPATH (en .bashrc o .tcshrc o ...) as�:

Bash:
  MANPATH="/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"
  export MANPATH

Tcsh:
  setenv MANPATH "/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"

Despu�s de definir la variable MANPATH se puede probar "man Pod::Man" para ver si se accede a las p�ginas de Perl.

Macros de formato

Escribir una p�gina de manual es muy f�cil. Es un sencillo lenguaje de composici�n donde las palabras clave del lenguaje de composici�n empiezan con un punto en el inicio de la l�nea. Estas palabras clave tambi�n se llaman macros. Las macros m�s importantes son:

.TH -> Inicia el t�tulo/cabecera de la p�gina de manual
.SH -> Encabezado de secci�n
.PP -> Nuevo p�rrafo
."  -> Comentario
.TP -> Sangrado del texto que est� 2 l�neas por debajo de esta macro

La sintaxis de .TH es:
.TH [nombre del programa] [n�mero de secci�n] [centro pie de p�gina] [izquierda pie de p�gina] [centro encabezado]

La sintaxis .SH es:
.SH encabezamiento

La sintaxis de .PP es muy sencilla. Simplemente produce un avance de l�nea.

He visto que a veces es �til incluir texto preformateado para ejemplos de c�digo de programas. Esto se puede hacer con:

.nf
_el_texto_pre_formateado_
_va_aqu�_____
.fi

Tengamos en cuenta que �stas son macros groff/nroff y debido a esto no pertenecen a las macros especiales de p�ginas de manual. Sin embargo, deber�an funcionar bien en todos los sistemas Unix.

Todas las macros para formatear p�ginas de manual est�n documentadas en la p�gina de manual llamada groff_man(7) (Aqu� se puede ver una versi�n en html de la p�gina de manual groff_man(7)). No voy a explicar estas macros, sino que sugiero que se lea la p�gina de manual de groff_man. La p�gina groff_man est� muy detallada y contiene todo lo que se necesita saber.

Los cap�tulos

Antes de empezar a escribir nuestra propia p�gina deber�amos saber que las p�ginas de manual normalmente se estructuran en cap�tulos. Por convenci�n los posibles encabezamientos de los cap�tulos son los siguientes:

NOMBRE         Nombre de secci�n, el nombre de la funci�n o el comando.
SINOPSIS       Uso.
DESCRIPCION    Descripci�n general.
OPCIONES       Descripciones y par�metros.
VALOR DEVUELTO Secciones dos y tres llamadas a funciones.
ENTORNO        Describe variables de entorno.
FICHEROS       Ficheros asociados.
EJEMPLOS       Ejemplos y consejos.
DIAGNOSTICOS   Normalmente usado por la secci�n 4 diagn�sticos de dispositivos
               e interfaces.
ERRORES        Secciones dos y tres errores y se�ales de manejadores.
VEASE TAMBIEN  Referencias cruzadas y citas.
CONFORME A     Conformidad con est�ndares, en su caso.
FALLOS         Errores y advertencias.
SEGURIDAD      Aspectos de seguridad a tener en cuenta.
otros          Se pueden a�adir cabeceras hechas a medida por los autores.

(N.T. en ingl�s estos encabezamientos son respectivamente NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUES, ENVIRONMENT, FILES, EXAMPLES, DIAGNOSTICS, ERRORS, SEE ALSO, STANDARDS, BUGS, SECURITY CONSIDERATIONS)

Una p�gina de manual de ejemplo

Aqu� tenemos una p�gina de manual de ejemplo. Hay que tener en cuenta que se necesita \- para distinguir la raya de los guiones. Teclee todo esto en su editor de texto y gu�rdelo como cdspeed.1.

.TH cdspeed 1  "10 de Septiembre de 2003" "version 0.3" "COMANDOS DE USUARIO"
.SH NOMBRE
cdspeed \- reduce la velocidad del cdrom para obtener un tiempo de
acceso m�s r�pido
.SH SINOPSIS
.B cdspeed
[\-h] [\-d dispositivo] \-s velocidad
.SH DESCRIPCION
Las unidades de cdrom modernas son demasiado r�pidas. Puede
llevar bastantes segundos en una unidad de cdrom de velocidad 60x
empezar a girar y leer datos de la unidad. El resultado en estas
unidades es precisamente mucho m�s lento que en unidades a 8x o 24x.
Esto es particularmente cierto si s�lo se lee ocasionalmente (e.g.
cada 5 segundos) ficheros peque�os. Esta utilidad limita la velocidad
y hace que la unidad responda mejor cuando se accede a ficheros peque�os.
.PP
cdspeed tambi�n hace a la unidad menos ruidosa lo que es muy
�til para escuchar m�sica en el ordenador.
.SH OPCIONES
.TP
\-h
presenta un peque�o texto de ayuda
.TP
\-d
usa el dispositivo dado en lugar de /dev/cdrom
.TP
\-s
establece la velocidad. El argumento es un entero. Cero significa restaurar
a la velocidad m�xima
.SH EJEMPLOS
.TP
Establecer la velocidad m�xima del cdrom a 8:
.B cdspeed
\-s 8
.PP
.TP
Restaurar la velocidad m�xima:
.B cdspeed
\-s 0
.PP
.SH ESTADO DE SALIDA
cdspeed devuelve un cero si consigue cambiar la velocidad m�xima de la
unidad de cdrom a la establecida. Se devuelve no cero en caso de fallo.
.SH AUTOR
Guido Socher (guido (at) linuxfocus.org)
.SH VEASE TAMBIEN
eject(1)

Pulse aqu� (cdspeed.html) para ver la p�gina anterior (N.T. en su versi�n inglesa).

Viendo y formateando nuestra p�gina de manual

Mientras escribimos la p�gina de manual podemos ir viendo de vez en cuando qu� aspecto tiene. Tecleando:

nroff -man nuestra_p�gina_de_manual.1 | less

groff -man -Tascii nuestra_p�gina_de_manual.1 | less

Para convertir una p�gina de manual en texto plano preformateado (e.g. para comprobar la ortograf�a) se utiliza:

nroff -man nuestra_p�gina_de_manual.1 | col -b > xxxx.txt

Para convertirlo en Postscript (para imprimir o para una conversi�n posterior a pdf) se usa:

groff -man -Tps nuestra_p�gina_de_manual.1 > nuestra_p�gina_de_manual.ps

Se puede convertir la p�gina de manual a html mediante:

man2html nuestra_p�gina_de_manual.1

Usando perl POD para generar p�ginas de manual

S� que a muchos les estar� extra�ando el hecho de s�lo poder editar la p�gina de manual en un editor de texto. Lo que quieren es generar la p�gina de manual. El formato de documentaci�n POD de perl es una buena elecci�n. Podemos escribir la p�gina en sintaxis POD y entonces ejecutar el comando

pod2man nuestra_p�gina_de_manual.pod > nuestra_p�gina_de_manual.1

La sintaxis del lenguaje de documentaci�n pod de perl se describe en una p�gina de manual llamada perlpod. La p�gina de manual del ejemplo anterior se podr�a ver en formato pod como se muestra a continuaci�n. Hay que tener en cuenta que POD es sensitivo a los espacios por lo que las l�neas en blanco alrededor de "=head" son necesarias.

=head1 NOMBRE

cdspeed -  reduce la velocidad del cdrom para obtener un tiempo de
           acceso m�s r�pido

=head1 SINOPSIS

cdspeed [-h] [-d dispositivo] -s velocidad

=head1 DESCRIPCION

Las unidades de cdrom modernas son demasiado r�pidas. Puede
llevar bastantes segundos en una unidad de cdrom de velocidad 60x
empezar a girar y leer datos de la unidad. El resultado en estas
unidades es precisamente mucho m�s lento que en unidades a 8x o 24x.
Esto es particularmente cierto si s�lo se lee ocasionalmente (e.g.
cada 5 segundos) ficheros peque�os. Esta utilidad limita la velocidad
y hace que la unidad responda mejor cuando se accede a ficheros peque�os.

cdspeed tambi�n hace a la unidad menos ruidosa lo que es muy
�til para escuchar m�sica en el ordenador.

=head1 OPCIONES

B<-h> presenta un peque�o texto de ayuda

B<-d> usa el dispositivo dado en lugar de /dev/cdrom

B<-s> establece la velocidad. El argumento es un entero. Cero significa restaurar
a la velocidad m�xima

=head1 EJEMPLOS

Establecer la velocidad m�xima del cdrom a 8:

          cdspeed -s 8

Restaurar la velocidad m�xima:

          cdspeed -s 0


=head1 ESTADO DE SALIDA

cdspeed devuelve un cero si consigue cambiar la velocidad m�xima de la
unidad de cdrom a la establecida. Se devuelve no cero en caso de fallo.

=head1 AUTOR

Guido Socher

=head1 VEASE TAMBIEN

eject(1)