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.

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…

Isaac

Apasionado de la computación y la tecnología en general. Siempre intentando desaprender para apreHender.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

A %d blogueros les gusta esto:

Si continuas utilizando este sitio aceptas el uso de cookies. más información

Los ajustes de cookies de esta web están configurados para "permitir cookies" y así ofrecerte la mejor experiencia de navegación posible. Si sigues utilizando esta web sin cambiar tus ajustes de cookies o haces clic en "Aceptar" estarás dando tu consentimiento a esto.

Cerrar