Tutorial completo del comando man en Linux

Si llevas un tiempo trasteando con GNU/Linux, seguro que más de una vez has tirado del comando man para sacarte de un apuro con la sintaxis de algún programa, una opción rara o un fichero de configuración. Aun así, mucha gente lo usa solo por encima y desconoce todo lo que tiene detrás: secciones, formatos, atajos, e incluso la posibilidad de crear sus propios manuales.

En las siguientes líneas vas a encontrar un tutorial completo sobre man en Linux: qué es exactamente, cómo están organizadas las páginas del manual, cómo consultarlas de forma eficaz, dónde se guardan, cómo se crean a mano con macros groff y cómo generarlas de forma cómoda con herramientas como pandoc. La idea es que termines no solo leyendo manuales, sino también escribiendo los tuyos para documentar scripts y aplicaciones.

Qué es man y por qué es tan importante en Linux

En los sistemas tipo UNIX, incluido GNU/Linux, la documentación principal se organiza en las llamadas páginas del manual o páginas man, accesibles mediante el comando man. Estas páginas describen de forma detallada comandos, utilidades, llamadas al sistema, funciones de librería, ficheros especiales y mucho más.

Cada entrada de man proporciona la sinopsis del uso del comando, una descripción extensa, la lista de opciones, ejemplos y a menudo información adicional como ficheros relacionados, variables de entorno, errores conocidos o referencias a otras páginas man relacionadas.

Para consultar la ayuda de cualquier herramienta instalada, basta con teclear algo tan sencillo como man nombre_comando en la terminal. El resultado se muestra de forma paginada (normalmente mediante el visor less), lo que permite moverse cómodamente por documentos largos sin saturar la pantalla.

En muchas distribuciones, las páginas están disponibles en varios idiomas y se almacenan en directorios distintos según el idioma. No todo el contenido está traducido al castellano, pero en Debian y derivadas puedes instalar paquetes como manpages-es y manpages-es-extra para disponer de una buena parte del manual en español.

Dentro del ecosistema GNU existe además el conocido The Linux Documentation Project (TLDP), que coordina documentación oficial en inglés y cuenta con una versión en español (es.tldp.org). También puedes consultar la guía completa de manuales de servidores. Aunque no se limita solo a páginas man, ha sido un proyecto clave en la difusión de documentación técnica en Linux.

Organización del manual por secciones

El manual de UNIX y Linux está dividido en secciones numeradas que agrupan tipos concretos de información. Esto evita mezclar, por ejemplo, un comando de usuario con una llamada al sistema del kernel que se llama igual.

Las secciones clásicas (y más extendidas) del manual son las siguientes, cada una asociada a un tipo de contenido bien definido dentro de man:

• Sección 1: comandos ejecutables de usuario (programas que se lanzan desde la shell).
• Sección 2: llamadas al sistema o syscalls que proporciona el kernel.
• Sección 3: funciones de librería (C, C++, Perl, etc.).
• Sección 4: ficheros especiales de dispositivos, normalmente en /dev.
• Sección 5: formatos de ficheros y convenciones (por ejemplo /etc/passwd).
• Sección 6: juegos y salvapantallas.
• Sección 7: miscelánea (protocolos, estándares, convenciones varias, etc.).
• Sección 8: comandos de administración del sistema y demonios (pensados para root).
• Sección 9: rutinas internas del kernel (no siempre presente o estandarizada).

Esta división se refleja tanto en la estructura lógica del manual como en los directorios del sistema: cada sección tiene su propia carpeta manN (man1, man2, man3, etc.), donde se almacenan las páginas correspondientes comprimidas normalmente con gzip.

Es habitual encontrarse nombres repetidos en distintas secciones. Por ejemplo, chmod existe como comando de usuario y como llamada al sistema. En esos casos, la sección es lo que marca la diferencia entre una página y otra, y es fundamental saber a cuál de ellas queremos acceder.

Cómo usar man de forma eficaz

El uso básico del comando es muy sencillo: si queremos consultar la ayuda de un programa cualquiera, basta con escribir en la terminal algo como man comando para abrir su página de manual. A partir de ahí, entramos en un visor paginado (generalmente less) que nos permite navegar por el contenido.

Cuando un mismo nombre aparece en varias secciones, man recorre el manual de la sección más baja a la más alta y muestra la primera coincidencia que encuentra. Por ejemplo, si ejecutas man chmod, verás la página del comando de usuario (sección 1) porque se prioriza esa sección frente a la 2.

Si necesitas forzar una sección concreta, puedes indicarla de forma explícita delante del nombre: al ejecutar man 1 chmod obtienes el manual del comando, mientras que con man 2 chmod accedes a la descripción de la llamada al sistema chmod del kernel.

El formato general que sigue el comando es muy fácil de recordar: man nombre…. Si omites la sección, man buscará por orden ascendente; si la incluyes, irás directo a la página adecuada sin ambigüedades.

Dentro de la página, la salida se presenta paginada usando habitualmente less como visor interno. Puedes desplazarte con las flechas del cursor, con AvPág y RePág, con la barra espaciadora o usando los atajos típicos de less. Para salir y volver a la línea de comandos, basta con pulsar la tecla q.

Atajos útiles al consultar manuales con less

Como man se apoya en less, hereda toda una batería de atajos que facilitan la lectura de manuales largos. Algunos de ellos pasan desapercibidos, pero una vez que los usas cuesta vivir sin ellos.

Si estás hojeando una página particularmente extensa y encuentras un punto clave al que quieres volver más tarde, puedes marcar la posición actual dentro del documento. Solo tienes que pulsar la tecla m seguida de una letra (a-z o A-Z) para crear un marcador.

Cuando quieras regresar a esa marca, simplemente presiona la comilla simple ‘ seguida de la misma letra que utilizaste al crearla. De esta forma puedes saltar rápidamente entre posiciones importantes sin romperte la cabeza recordando dónde estaba cada cosa.

Ten en cuenta que las marcas solo viven mientras tienes abierta esa página. En cuanto cierres man (y, con ello, less), se pierden. Eso sí, este truco sirve también para cualquier otro archivo que abras directamente con less, no solo para páginas man.

Otro detalle muy práctico es la posibilidad de ejecutar comandos de shell sin cerrar la página del manual. Igual que en editores como vi o vim, puedes pulsar ! dentro de less, escribir el comando que quieras probar y ejecutarlo; al terminar, vuelves a donde estabas en el manual simplemente pulsando Intro.

Cómo se describe la sintaxis en las páginas man

Una de las partes más importantes de cualquier página del manual es la sección SYNOPSIS o SINOPSIS, donde se muestra la sintaxis del comando, función o fichero. Para que sea compacta pero precisa, se utilizan una serie de convenciones que conviene dominar.

Cuando veas un elemento entre significa que es opcional. Si el texto aparece como , puedes indicar esa opción o no hacerlo; en cambio si se muestra como {x,y}, los elementos entre llaves son alternativos, pero debes elegir uno de ellos de forma obligatoria.

Si la sinopsis incluye algo del estilo , se indica que puedes usar x, y o nada, precisamente porque toda la expresión va entre corchetes. A su vez, si aparece x…, quiere decir que x puede repetirse tantas veces como necesites en la línea de comandos.

Las opciones se resumen a veces con sintaxis del tipo , lo que sugiere que ninguna de ellas es obligatoria, pero si las usas, puedes combinar cualquiera de las letras en cualquier orden. Así, serían válidos -x, -y, -z, -xy, -zx, etc., siempre que el programa acepte esa combinación.

Esta forma compacta de expresar la sintaxis permite condensar todas las posibilidades en una sola línea, aunque al principio pueda parecer algo críptica. Una vez la interiorizas, leer manuales se vuelve mucho más ágil.

Estructura típica de una página de manual

Detrás de cada página man hay un archivo de texto en un formato específico basado en groff y en un conjunto de macros que definen secciones, títulos, estilos, párrafos, etc. Aunque a simple vista el resultado sea “sólo texto”, por debajo hay bastante más chicha.

La anatomía básica de una página de manual suele incluir varias secciones bien conocidas como NAME, SYNOPSIS y DESCRIPTION, a las que se pueden añadir otras según lo que se quiera documentar. No existe una obligación rígida, pero sí una serie de convenciones muy extendidas.

Las secciones más habituales que te podrás encontrar (o que deberías usar al crear tus propias páginas) son, entre otras, las siguientes, agrupando la información de forma predecible para el usuario:

• NAME / NOMBRE: nombre del comando o fichero y una breve descripción.
• SYNOPSIS / SINOPSIS: línea o líneas que resumen parámetros y opciones.
• DESCRIPTION / DESCRIPCIÓN: explicación detallada del funcionamiento.
• OPTIONS / OPCIONES: descripción de todas las opciones de la línea de comandos (principalmente en secciones 1 y 8).
• COMMANDS / COMANDOS: lista de subcomandos o acciones internas, si la herramienta los tiene.
• ENVIRONMENT / ENTORNO: variables de entorno relevantes y cómo las utiliza el programa.
• FILES / ARCHIVOS: ficheros que usa o modifica la herramienta (configuración, logs, etc.).
• BUGS / ERRORES: problemas conocidos o limitaciones.
• EXAMPLE / EJEMPLO: ejemplos de uso reales, muy útiles para el día a día.
• AUTHORS / AUTORES: autores del programa o del propio manual, a menudo con correo.
• SEE ALSO / VÉASE TAMBIÉN: referencias a otras páginas man relacionadas.

Además de estas, es habitual incluir otras como EXIT STATUS, CAVEATS, NOTES, RETURN VALUE o DIAGNOSTICS cuando se quiere profundizar en códigos de salida, advertencias, notas adicionales o mensajes de error específicos.

Aunque pueda dar algo de pereza al principio, respetar estas secciones al escribir tus manuales hará que los usuarios se sientan “como en casa”, ya que sabrán dónde buscar cada tipo de información sin necesidad de explorar a ciegas.

Macros de formato groff usadas en las páginas man

Si abres el archivo fuente de una página man clásica (por ejemplo, descomprimiendo gpg.1.gz), verás un texto bastante crudo lleno de líneas que empiezan por un punto seguidas de siglas. Esas siglas son precisamente las macros de formato que entiende el sistema de manuales.

La macro que abre la página se llama .TH y define el encabezado principal. La estructura general que sigue es algo como: .TH nombre-comando número-sección fecha Autor título, todo en una única línea, con mayúsculas para el nombre del comando.

Un ejemplo real podría parecerse a algo tipo .TH GPG 1 2015-03-08 «GnuPG 1.4.12» «GNU Privacy Guard», donde se especifica el nombre del programa, la sección, la fecha de la revisión del manual, el nombre de la versión y un título descriptivo.

Las diferentes partes del contenido se estructuran con la macro .SH, que introduce nuevas secciones en el documento. Su forma básica es muy simple: .SH NOMBRE_SECCION, y a continuación el texto que compone esa sección, hasta que se declare una nueva.

Para formatear fragmentos concretos de texto, se utilizan macros como .B, .I y .R, que indican negrita, itálica/subrayado y tipografía “romana” (texto normal) respectivamente. También existen combinaciones como .BI o .IR para mezclar estilos en una misma línea.

Un ejemplo muy sencillo sería algo del tipo .B esto es una .I prueba, que se mostraría aproximadamente como “esto es una” destacado y “prueba” en itálica. El inconveniente es que estas macros suelen afectar al resto de la línea completa si no se controlan con cuidado.

Para tener un control más fino, es frecuente recurrir a las secuencias de cambio de fuente como \fB, \fI y \fR, que cambian el estilo de forma puntual dentro de una línea. Así podrías escribir algo como \fBesto es una \fIprueba para obtener un resultado más preciso.

Los saltos de línea explícitos se indican con .br, mientras que los nuevos párrafos se crean con .PP. De esta forma, el autor del manual decide cómo se estructura visualmente el texto al mostrarse con man, sin depender solo de espacios en blanco.

Si hace falta dejar comentarios internos que no verán los usuarios al ejecutar man, se puede usar una macro de comentario (por ejemplo con líneas que comienzan por un punto y una barra invertida), útil para dar pistas a futuros mantenedores del manual sin que se muestre en la versión final.

Localización y organización de las páginas man en el sistema

Para entender bien cómo funcionan las páginas del manual, viene de perlas saber dónde se guardan físicamente los archivos en el sistema. Esto es especialmente útil cuando quieres inspeccionar, copiar o crear tus propios manuales.

Una ruta muy típica donde residen estas páginas es /usr/share/man, aunque también puedes encontrar otras ubicaciones como /usr/man, /usr/local/man o /usr/local/share/man, según la distribución o si se trata de software instalado localmente.

Cada sección del manual se corresponde con un subdirectorio llamado manN (man1, man2, man3, etc.). Por ejemplo, un programa habitual de usuario podría tener su manual en /usr/share/man/man1/programa.1.gz, mientras que una página de administración podría residir en man8.

Si quieres localizar los ficheros asociados a un programa concreto (incluida su página man), puedes usar whereis nombre_programa para que el sistema te indique rutas relevantes. Entre la salida aparecerá normalmente la ruta exacta del fichero .N.gz de la página del manual.

Cuando necesites “diseccionar” un manual para aprender cómo está hecho sin arriesgarte a estropear nada, puedes copiar el archivo desde /usr/share/man a un directorio seguro como /usr/src, y allí descomprimirlo con gzip para analizar su contenido con tu editor favorito.

Ten presente que la numeración de secciones no es decorativa: al inspeccionar /usr/share/man verás directorios man1 a man8 (y a veces man9), y cada uno agrupa manuales de un tipo específico. De esta forma, se mantiene una estructura coherente y fácil de mantener.

Cómo crear tus propias páginas man “a mano”

Una vez entiendes la estructura y las macros básicas, puedes lanzarte a crear tu propio manual para scripts o programas (por ejemplo, un manual de Bash). El proceso no es tan farragoso como pueda parecer, aunque requiere algo de mimo para que quede limpio y útil.

Un enfoque clásico consiste en escoger una página man existente como referencia (por ejemplo, la de gpg o iptables), copiarla a otro directorio, descomprimirla y usarla como plantilla para aprender la sintaxis real. A partir de ahí, vas eliminando contenido y dejando solo la estructura que necesites.

A la hora de nombrar el archivo, se sigue la convención de nombre.sección. Si tu script se llama test y es un programa de usuario normal, lo habitual será llamarlo test.1 porque va a la sección 1. Luego, en su interior, definirás el título con .TH, las secciones con .SH y el contenido formateado con las macros que ya conoces.

Cuando lo tengas listo, el siguiente paso es comprimir el archivo con gzip, lo que generará test.1.gz listo para ser instalado en la ubicación correspondiente. El formato comprimido es el que utiliza el sistema de manuales por defecto.

Para dejarlo disponible al resto de usuarios, bastará con copiar el fichero comprimido al directorio de la sección adecuada, por ejemplo /usr/share/man/man1/ si es un comando normal, o man8 si es un comando de administración.

Con el archivo colocado en el sitio correcto, podrás abrir tu manual simplemente escribiendo man test desde cualquier terminal del sistema. A partir de ahí, se comportará como cualquier otra página man instalada de forma estándar.

Creación de manuales con pandoc y Markdown

Editar directamente en formato groff está bien para aprender, pero puede ser un poco áspero. Si prefieres algo más amigable, puedes usar Markdown y convertirlo a formato man con herramientas como pandoc, lo que agiliza muchísimo el proceso de documentación.

El primer paso es instalar pandoc mediante el gestor de paquetes de tu distribución (apt, dnf, pacman, etc.). Una vez instalado, puedes crear tu página de manual en un archivo con extensión .N.md, por ejemplo hola.1.md para un comando llamado hola.

En ese archivo Markdown puedes escribir tu documentación con secciones que reflejen NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES y cualquier otra que necesites. Cualquier editor de texto sencillo como vim, nano, gedit o similares te sirve para esta tarea.

Cuando termines de redactar el contenido en Markdown, es hora de decirle a pandoc que lo convierta al formato de manual que entiende man. Para ello, se utiliza una orden del estilo: pandoc -s -t man -o hola.1 hola.1.md, donde el nombre de salida lleva la sección como extensión.

La opción -s (standalone) le indica a pandoc que genere una página de manual completa, con toda la estructura necesaria, y no solo un fragmento de texto sin cabecera. Por su parte, la opción -t man especifica que el tipo de salida debe ser precisamente el formato del manual que luego entiende el sistema.

Una vez generado el archivo hola.1, puedes comprimirlo si lo deseas, copiarlo a /usr/local/man/man1 o a otra ruta apropiada y comprobar que funciona escribiendo man hola. Así tendrás un manual limpio y mantenible, con la comodidad de haberlo escrito en Markdown.

Instalación, ubicación y eliminación de tus man pages

Cuando desarrollas un script o programa propio, tiene sentido no solo instalar el binario, sino también colocar su página man en la ruta correcta para que cualquier usuario pueda llamarla sin complicaciones desde la terminal.

Si has creado, por ejemplo, un ejecutable llamado hola, una ubicación típica para el binario sería /usr/bin/hola, de modo que puedas llamarlo simplemente escribiendo hola sin tener que ir a su carpeta de origen ni modificar el PATH.

La página de manual correspondiente debería ir a /usr/share/man/man1/hola.1.gz o a un directorio similar acorde a la sección y a la política de tu distribución. Si se trata de una herramienta de administración, puede que prefieras ubicarla en man8.

En entornos donde distribuyes tu software a terceros, resulta muy cómodo incluir scripts de instalación y desinstalación que copien o eliminen tanto el binario como la man page. Así, si el usuario decide borrar tu herramienta, no se quedarán restos de documentación huérfanos por el sistema.

Para desinstalar manualmente bastaría con eliminar el binario de su ruta (por ejemplo /usr/bin/hola) y la página de manual de su directorio man correspondiente. Tras ello, cualquier intento de ejecutar man hola devolverá un error de que no existe esa entrada.

Usar de forma coherente estas ubicaciones hace que tu software se integre de manera “nativa” en el sistema, siguiendo los mismos patrones que utilizan las herramientas incluidas en la distribución.

Al final, dominar el comando man y el formato de las páginas del manual te permite no solo consultar de manera muy eficiente la documentación de Linux, sino también convertir tus propios scripts y aplicaciones en herramientas bien documentadas y fáciles de usar. Cuando incorporas manuales con secciones claras, ejemplos y referencias, estás mejorando muchísimo la experiencia de quien vaya a usar tu trabajo, sea otra persona o tú mismo dentro de unos meses cuando ya no recuerdes los detalles.