man: ¿Cómo crear páginas de manual en Linux?
Seguro que has consultado multitud de ocasiones las páginas del manual de algún programa en Linux usando man. Pues en este tutorial aprenderás a documentar y dotar a tus desarrollos de un manual. Así, incluso si son scripts o pequeñas herramientas, los usuarios que las utilicen podrán obtener información cuando la instalen en sus equipos.
Para poder crear las páginas del manual hay varias formas posibles, algunas manuales algo más lentas y complejas. Pero también existen herramientas que te facilitarán mucho el trabajo.
ÍNDICE:
man (manual)
Como ya sabrás, la herramienta man te permite consultar las páginas del manual en Linux. Así puedes obtener información de cualquier comando o herramienta, así como de llamadas al sistema, ficheros, etc.
#Ejemplo, consultar las páginas del manual del propio man man man #Consultar el manual de touch man touch
Una vez dentro, podrás navegar por él mediante las flechas arriba y abajo del teclado o haciendo scroll con el ratón. Además, podrás presionar la tecla Q para salir.
Layout de las páginas del manual
En cuanto al manual, sigue un layout o arquitectura bien definida. Su fisionomía básica es:
NAME
El nombre del comando o función, seguida por una descripción de qué es.
SYNOPSIS
En caso de ser un comando, debes aportar una descripción formal cómo ejecutar éste y de las opciones.
DESCRIPTION
Descripción textual del comando o función.
OPTIONS
Un listado de las posibles opciones y qué hace cada una.
EXAMPLES
Un ejemplo de cómo se usa.
EXIT VALUES
Posibles códigos de retorno y su significado.
SEE ALSO
Una lista de comandos relacionados o funciones.
BUGS
Lista de bugs conocidos.
FILES
Lista de archivos incluidos en el paquete.
HISTORY
Historial de cambios.
AUTHOR
Información del desarrollador o contacto.
COPYRIGHT
Especificar la información del copyright.
También podrías añadir otras secciones adicionales como EXIT STATUS, ENVIRONMENT, FILES, CAVEATS, etc.
Además, conocer el macro formato groff, que no es fácil para visualizar, pero que se emplea en man.
Secciones del manual (páginas)
Como sabrás, man puede mostrar por páginas o secciones. Cada una de ellas destinada a un tipo de información concreta:
| Sección | Descripción |
|---|---|
| 1 | Comando ejecutable. |
| 2 | Llamadas al sistema (syscalls) que provee el kernel. |
| 3 | Llamadas a bibliotecas. |
| 4 | Ficheros especiales (p.e.: en /dev). |
| 5 | Formatos de archivos y convenciones (p.e.: /etc/passwd). |
| 6 | Juegos |
| 7 | Miscelanea. |
| 8 | Comandos de administración del sistema (usualmente solo para root). |
| 9 | Rutinas del kernel (no estándar). |
Localización de las páginas del manual
Es importante que conozcas dónde se alojan las páginas del manual para que puedas alojarlas en el lugar adecuado cuando la crees. Si necesitas saber los path o rutas, puedes usar:
#Mostrar las rutas configuradas actualmente manpath #Más información man manpath #También puedes usar la variable de entorno que apunta a las rutas $MANPATH
Por ejemplo, algunas rutas usuales suelen ser:
- /usr/man
- /usr/share/man
- /usr/local/man
- /usr/local/share/man
- /usr/X11/man
Además, tienes que comprimir tus páginas con gzip. Por tanto, imagina que tienes una página llamada proyecto y la vas a alojar en /usr/local/man/. Podrías usar:
#Opción 1 cp proyecto /usr/local/man/proyecto.1 gzip /usr/local/man/proyecto.1 man proyecto #Opción 2 install -g 0 -o 0 -m 0644 proyecto.1 /usr/local/man/ gzip /usr/local/man/proyecto.1
Crear tus propias páginas documentadas para man
Para comenzar a crear páginas de manual de una forma más sencilla, puedes valerte de la herramienta pandoc. Para ello, lo primero es instalarla en tu distro:
#Puedes usar alguna de estas herramientas de gestión de paquetes para instalarlo en tu distro (Debian/Ubuntu/derivados, Fedora/Derivados y Arch/derivados respectivamente) sudo apt-get install pandoc sudo dnf install pandoc sudo pacman -Syu pandoc
Una vez lo tienes instalado, podrías comenzar a editar las páginas de tu manual, documentando todo lo necesario para la herramienta o programa que has desarrollado. Puedes usar cualquier editor de texto que prefieras. Por ejemplo, puedes usar vim, o nano, gedit, etc., y crear un manual llamado hola.1.md con el siguiente contenido:
# NAME hola - Programa que muestra un Hola por el terminal, como saludo. # SYNOPSIS **hola** [*OPTION*]... # DESCRIPTION **hola** es un simple programa escrito en C para poder mostrar el mensaje Hola <nombre> como ejemplo. # OPTIONS **-h** : muestra ayuda del comando **-n** : puedes especificar un nombre para decir Hola a esa persona. # EXAMPLES **hola -n Isaac** : Muestra "Hola, Isaac!" y sale. # AUTHORS Escrito por Isaac de AT. # BUGS Reportar errores a <ejemplo@correo.es> # SEE ALSO Más información: <https://architecnologia.es/blog>
Puedes agregar las secciones que necesites. Y una vez terminas, lo guardas y listo. Lo siguiente será usar pandoc para crear las páginas como tal y que puedan ser reconocidas por man:
#Ejecuta el siguiente comando para crear la página del manual pandoc hola.1.md -s -t man -o hola.1 #Para ver el resultado man -l hola.1 #Recuerda lo que comenté anteriormente, que debes comprimir el fichero de manual #y moverlo a la ruta adecuada. De esa forma, podrás usar simplemente: man hola
La opción -s (standalone) sirve para generar una completa página del manual de arriba a bajo en vez de texto en formato manual. Y la opción -t (output type) le dice que debe generar la salida en formato del manual.
En cuanto al binario del programa hola, puedes alojarlo también en alguna de las rutas adecuadas. Por ejemplo, podrías ponerlo en /usr/bin/hola, para así invocarlo solo con su nombre, y no tener que moverte al directorio donde se encuentra o especificar el path completo.
Eliminar tu man page
Por último, también podrías eliminar el programa que has creado y la página de manual correspondiente si ya no lo quieres. Podrías crear un script uninstall para hacerlo automáticamente o ejecutar los comandos:
sudo rm /usr/bin/hola sudo rm /usr/share/man/hola.1.gz sudo mandb
Espero haberte ayudado…
