Cuando ejecutas man ls por primera vez, la pantalla se llena de texto y la reacción natural es pulsar q y buscar la respuesta en internet. Es un error que vale la pena corregir pronto, porque la man page de cualquier herramienta es la documentación escrita por quien la programó, no una paráfrasis de terceros.
Una man page (página del manual) es un documento estructurado que describe con precisión un comando, una llamada al sistema, un formato de archivo, o un servicio del sistema. El formato viene de los tiempos de Unix, y esa antigüedad es una ventaja: cada man page sigue la misma estructura, así que una vez que aprendes a leerla en un sitio la lees en todos.
El sistema de manual está dividido en secciones numeradas. No todas las secciones importan igual al principio, pero conviene conocerlas porque el número aparece en referencias cruzadas. Las más usadas son:
- Sección 1: comandos de usuario (
ls,grep,find) - Sección 2: llamadas al sistema del kernel (
open,fork,read) - Sección 5: formatos de archivos de configuración (
passwd,fstab,crontab) - Sección 8: comandos de administración del sistema (
mount,iptables,useradd)
Cuando ves escrito crontab(5) en una página, significa “la man page de crontab en la sección 5″, o sea, la que describe el formato del archivo, no el comando. Para acceder a ella directamente usas man 5 crontab. Sin número, man crontab te muestra la sección 1 por defecto si existe. Si un nombre existe en varias secciones y no especificas cuál, el sistema elige la de número más bajo.
¿Y si no sabes el nombre exacto del comando? Para eso existe man -k, que busca en las descripciones cortas de todas las man pages instaladas. man -k crontab devuelve todas las entradas que mencionan esa palabra. Internamente usa la misma base de datos que apropos, que es un alias de ese mismo comportamiento. Si la búsqueda no devuelve resultados, ejecuta sudo mandb para regenerar el índice, algo que Debian hace automáticamente al instalar paquetes pero que puede quedar desactualizado en sistemas recién instalados o con paquetes añadidos a mano.
Lo más importante cuando abres una man page es entender qué sección estás leyendo, porque el documento no se lee de arriba a abajo como un tutorial: se consulta.
Ejemplo completo: leer la man page de cp
# Abrir la man page del comando cp (sección 1, comandos de usuario) man cp # Si hubiera ambigüedad de sección, se especifica explícitamente: man 1 cp
Dentro del visor (que en Debian es less por defecto), los controles de navegación son:
Tecla Acción ────────────────────────────────────────── ↑ / ↓ Subir o bajar una línea Espacio Avanzar una pantalla completa b Retroceder una pantalla completa /texto Buscar "texto" hacia adelante n Siguiente coincidencia de búsqueda N Coincidencia anterior g Ir al principio del documento G Ir al final del documento q Salir
# Buscar páginas relacionadas con "copy" cuando no recuerdas el nombre man -k copy # La salida incluye líneas como: # cp (1) - copy files and directories # install (1) - copy files and set attributes # rsync (1) - a fast, versatile, remote (and local) file-copying tool # Para ir directamente a una sección concreta dentro del visor, # busca el nombre de la sección con /EXAMPLES o /OPTIONS
Ahora vamos a ver qué contiene cada bloque de la man page de cp cuando la abres.
Lo que encuentras dentro, sección por sección
NAME es la primera línea útil: cp - copy files and directories. Una sola línea. Es exactamente lo que man -k usa para sus búsquedas. Si el texto de NAME no responde tu pregunta, ya sabes que necesitas otro comando.
SYNOPSIS es el bloque que más cuesta leer al principio porque tiene su propia notación. En cp aparece algo así:
SYNOPSIS
cp [OPTION]... [-T] SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY
cp [OPTION]... -t DIRECTORY SOURCE...
Las reglas de esta notación son fijas en todo el sistema de manual:
- Lo que va entre corchetes
[]es opcional. Puedes omitirlo. - Lo que va en MAYÚSCULAS es un valor que tú proporcionas (un nombre de archivo, un directorio, un número).
- Los puntos suspensivos
...significan que ese elemento puede repetirse. - Lo que aparece sin corchetes y en minúsculas es literal y obligatorio.
Entonces cp [OPTION]... SOURCE... DIRECTORY se lee: “cero o más opciones, uno o más archivos de origen, un directorio destino”.
DESCRIPTION explica el comportamiento general con los detalles que el SYNOPSIS no puede expresar. Aquí aprenderás, por ejemplo, que cp sin -r no copia directorios. Esta sección es larga en comandos complejos; no tienes que leerla entera cada vez, úsala como referencia.
OPTIONS lista cada flag con su explicación. En cp encontrarás -r o --recursive con la descripción de qué hace exactamente. Fíjate en que muchas opciones tienen forma corta (-r) y larga (--recursive): la man page las documenta juntas. Cuando algo no funciona como esperas con una opción, la respuesta está aquí antes que en cualquier foro.
FILES aparece en páginas de servicios y comandos de administración, listando los archivos de configuración o estado que el programa lee o escribe. La man page de sshd, por ejemplo, lista ahí /etc/ssh/sshd_config.
EXAMPLES no siempre existe, pero cuando aparece es el mejor punto de entrada para comandos que tienen muchas formas de invocación.
SEE ALSO al final apunta a man pages relacionadas. En cp verás referencias a mv(1), ln(1), install(1). Seguir esas referencias es como navegar una wiki bien enlazada, pero con información precisa.
La razón por la que el manual lleva décadas con este formato es exactamente porque funciona para consulta rápida: sabes dónde está cada tipo de información sin tener que leer todo el documento. Cuando tengas una opción que no entiendes del todo, buscar su nombre con / dentro del visor te lleva directamente a la línea exacta donde está documentada.
N° 12