![[LinuxFocus-icon]](../../common/images/logolftop_319x45.gif){kind=small} |
|
|
 |
|
| Este documento está disponible en los siguientes idiomas: English Castellano Deutsch Francais Italiano Nederlands Russian Turkce |
![[Photo of the Author]](../../common/images/Guido-S.gif)
por Guido Socher (homepage) Sobre el autor: A Guido le gusta Linux porque es muy flexible y ofrece muchas más posibilidades que cualquier otro sistema operativo. Taducido al español por: Roberto Hernando Velasco (homepage) Contenidos: |
Escribiendo páginas de manual
Resumen:
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.
|
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
> whichman -0 printf /usr/share/man/man1/printf.1.bz2 /usr/share/man/man3/printf.3.bz2Las 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á:
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.
.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
.nf _el_texto_pre_formateado_ _va_aquí_____ .fiTengamos 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.
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)
.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).
nroff -man nuestra_página_de_manual.1 | lesso
groff -man -Tascii nuestra_página_de_manual.1 | lessPara 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.txtPara 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.psSe puede convertir la página de manual a html mediante:
man2html nuestra_página_de_manual.1
pod2man nuestra_página_de_manual.pod > nuestra_página_de_manual.1La 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)
|
|
Contactar con el equipo de LinuFocus
© Guido Socher, FDL LinuxFocus.org |
Información sobre la traducción:
|
2003-11-24, generated by lfparser version 2.34