5. Leer el manual: man, --help y tldr

Descripción

Al terminar esta lección vas a poder averiguar por tu cuenta cómo funciona cualquier comando de tu sistema —uno que esta guía nunca mencionó— sin salir de la terminal: abrir su manual completo, pedirle un resumen rápido de sus opciones, encontrar ejemplos de uso real, y hasta descubrir el nombre de un comando que no conoces todavía a partir de lo que quieres lograr.

Esto importa porque tarde o temprano vas a estar conectado por SSH a un servidor sin navegador, o un compañero te va a pasar un comando con una opción que nunca viste, y la única fuente de verdad disponible ahí mismo, sin salir de esa terminal, es la documentación que ya vive instalada en esa máquina. Saber leerla es la diferencia entre quedarte trabado y resolver solo.

Conexión con el módulo: la lección anterior te enseñó la anatomía de un comando —qué es una opción, qué es un argumento, cómo se combinan—. Esta lección te da la fuente oficial de esa anatomía para cualquier comando nuevo. La siguiente cambia de tema por completo: deja atrás los comandos individuales y arranca el modelo mental central de la guía, el sistema de archivos como árbol.

El manual como fuente de la verdad: man

Piensa en un técnico que repara un modelo de motor que nunca vio antes. No adivina por prueba y error, y no confía en un video de YouTube de hace tres años sobre "un motor parecido": busca el manual del fabricante para ese modelo exacto. man es exactamente eso para un comando: el manual que instaló el mismo paquete que instaló el comando, para la versión exacta que corre en tu máquina —no un artículo de blog que puede describir una versión distinta, y no lo que un modelo de lenguaje "recuerda" haber visto en su entrenamiento, que puede estar desactualizado o simplemente equivocado para tu sistema.

Técnicamente, man (de manual) abre la página de documentación de un comando dentro de un paginador de texto —casi siempre less— para que puedas desplazarte, buscar y salir sin que el contenido se derrame fuera de tu pantalla. Las páginas de manual están organizadas en secciones numeradas, y las que vas a encontrar casi siempre son:

Esto no es trivia: algunos nombres existen en más de una sección con contenido completamente distinto. El caso clásico es passwd: man passwd abre la sección 1, el comando que usas para cambiar tu contraseña. Pero también existe passwd(5), la sección 5, que describe el formato del archivo /etc/passwd —no cómo cambiar tu clave, sino cómo está estructurado ese archivo línea por línea. Para pedir una sección específica, el número va antes del nombre:

man 5 passwd

Sin el número, man te da la primera sección donde encuentra el nombre —casi siempre la 1—, que no siempre es la que buscas.

Ejemplo trabajado

Abre el manual de un comando que ya conoces de la lección anterior:

man ls

Esto reemplaza tu terminal por el paginador, mostrando algo como esto en las primeras líneas:

LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List information about the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort is
       specified.

Qué esperar: NAME te da, en una línea, qué hace el comando —es lo mismo que devuelve whatis ls. SYNOPSIS es la parte que más vale la pena aprender a leer, porque resume toda la forma de usar el comando en una notación compacta y estándar en casi cualquier página de manual que abras en tu vida:

• Texto en negrita o escrito tal cual (ls, [OPTION], [FILE]): tipéalo exactamente así.
• Texto en cursiva o en MAYÚSCULAS (OPTION, FILE): es un marcador de posición —reemplázalo por tu propio valor. Muchas páginas usan mayúsculas en vez de cursiva real, porque la cursiva no siempre se distingue bien en un paginador de texto plano sin colores.
• Corchetes [ ]: lo que está adentro es opcional. ls funciona sin ninguna opción y sin ningún archivo.
• Puntos suspensivos ...: lo anterior se puede repetir. [FILE]... significa "cero, uno o varios archivos", no solo uno.
• Barra vertical |: separa alternativas mutuamente excluyentes —elige una, no ambas.

Con esas cinco reglas, ls [OPTION]... [FILE]... se lee así: "ls, seguido de cero o más opciones, seguido de cero o más archivos o carpetas". Nada de eso es obligatorio, y por eso ls a secas —sin nada después— también es válido: usa el directorio actual por defecto, tal como dice DESCRIPTION.

Si estás en macOS, tu ls es la versión de BSD, no la de GNU que se ve arriba: la sinopsis agrupa todas las opciones cortas dentro de un mismo corchete y no acepta opciones largas (--algo). El estilo de listado cambia entre implementaciones, pero la notación —corchetes, puntos suspensivos, mayúsculas— es la misma en cualquier página de manual que abras, en cualquier sistema.

Para moverte dentro de la página, ya estás usando less aunque no lo hayas pedido:

• Espacio o f avanza una pantalla, b retrocede una.
• /patrón busca hacia adelante ese texto; Enter confirma la búsqueda, n salta a la siguiente coincidencia, N (mayúscula) a la anterior.
• g va al principio del documento, G (mayúscula) al final.
• q cierra el manual y te devuelve la terminal.

Prueba buscar la opción que ordena por tamaño: dentro de man ls, escribe /-S y presiona Enter. less salta directo a la línea que documenta -S, en vez de que la busques leyendo de arriba a abajo.

--help: la respuesta rápida cuando ya conoces el comando

man es exhaustivo, pero abrir un paginador completo para recordar un solo flag es más trabajo del que hace falta. La mayoría de los comandos —sobre todo los de GNU, comunes en Linux y en WSL— aceptan --help: imprimen un resumen de uso directo en la terminal, sin paginador, y puedes combinarlo con lo que ya sabes de la lección anterior sobre tuberías básicas:

ls --help

Qué esperar (una porción representativa; la lista real de opciones es más larga):

Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).

  -a, --all                  do not ignore entries starting with .
  -l                         use a long listing format
  -S                         sort by file size, largest first
  ...

--help no reemplaza a man: es una nota de uso escrita por el propio programa, mientras que la página de manual es documentación mantenida aparte, más completa, con ejemplos y advertencias que rara vez caben en una pantalla de resumen. Si solo necesitas recordar el nombre exacto de un flag, --help es más rápido; si necesitas entender un comportamiento con matices, man sigue siendo la referencia.

Un detalle de plataforma que conecta con la lección 3: si estás en macOS, muchos comandos del sistema vienen de BSD, no de GNU, y BSD no adoptó la convención --help de forma universal. Es común que ls --help en macOS falle con un error de opción no reconocida en vez de mostrarte algo útil. Ahí es exactamente donde man ls —que sí existe en cualquier Unix— se vuelve indispensable en vez de opcional.

tldr: ejemplos reales como complemento, no como reemplazo

Un manual completo documenta cada flag con precisión, pero no siempre te dice cuál es la combinación que la gente usa en la práctica para la tarea del día a día. Ahí entra tldr (too long; didn't read): un proyecto comunitario (tldr-pages) que mantiene páginas cortas con ejemplos de uso real para miles de comandos, pensadas para complementar el manual —no para sustituirlo.

tldr no viene preinstalado; necesitas un cliente. Hay varios, y cualquiera te sirve —instala el que tu gestor de paquetes tenga más a mano:

# cliente en Python, funciona en cualquier sistema con pipx
pipx install tldr

# cliente en Rust (tlrc), vía Homebrew en macOS/Linux
brew install tlrc

Con el cliente instalado, pide ejemplos de un comando:

tldr tar

Qué esperar (el contenido exacto varía entre versiones de las páginas, pero la forma es siempre esta):

tar

  Archiving utility, often combined with a compression method.

  Create an archive from files:
      tar cf {{target.tar}} {{file1 file2 ...}}

  Create a gzipped archive:
      tar czf {{target.tar.gz}} {{file1 file2 ...}}

  Extract a (compressed) archive into the current directory:
      tar xvf {{source.tar[.gz]}}

  List the contents of a tar file:
      tar tvf {{source.tar}}

Compara esto con abrir man tar: el manual documenta decenas de flags con precisión formal, pero no te dice cuál combinación resuelve "quiero descomprimir esto ahora mismo". tldr sí. Lo que tldr no tiene es la cobertura completa ni la autoridad del manual: son páginas mantenidas por voluntarios, pueden quedar desactualizadas frente a una versión nueva del comando, y casi nunca explican los casos límite. Úsalo para recordar rápido la forma común; vuelve a man cuando necesites la certeza de qué hace exactamente cada opción antes de correr algo que no puedes deshacer.

apropos: buscar un comando cuando no sabes su nombre

Todo lo anterior asume que ya sabes el nombre del comando. apropos resuelve el problema anterior a ese: buscar por palabra clave dentro de la descripción corta de todas las páginas de manual instaladas en tu sistema, para encontrar el nombre que no conoces.

apropos "list directory"

Qué esperar (algo así, exacto según tu sistema):

ls (1)               - list directory contents
dir (1)               - list directory contents
vdir (1)              - list directory contents

man -k palabra hace exactamente lo mismo que apropos palabra —son el mismo mecanismo con dos nombres. Si en cambio ya sabes el nombre exacto y solo quieres su descripción de una línea, whatis nombre es la versión sin búsqueda difusa: coincide con el nombre completo, no con palabras sueltas dentro de la descripción.

apropos busca en una base de datos indexada, no en los archivos de manual directamente, y esa base la construye el programa mandb. Si tu sistema es nuevo o acabas de instalar paquetes, esa base puede no existir todavía o estar desactualizada —lo que produce el mensaje nothing appropriate incluso para una palabra clave que debería tener resultados. Reconstruirla es una sola línea:

sudo mandb

Pedirle un comando a un modelo de lenguaje: legítimo, pero verifica antes de ejecutar

Preguntarle a un asistente de IA "¿cómo borro todos los archivos .tmp de esta carpeta y sus subcarpetas?" es legítimo y, la mayoría de las veces, más rápido que buscar en un manual desde cero. Eso no es el problema. El problema es ejecutar la respuesta sin haber entendido cada parte de ella.

Un modelo de lenguaje puede acertar el comando y también puede equivocarse de sutileza —una opción para una versión distinta del comando, un flag que hace algo ligeramente distinto de lo que crees, una ruta interpretada distinto de lo que esperabas. La regla que te sirve para toda tu carrera con la terminal es simple: un comando que no entiendes no se ejecuta. Primero lo lees en su manual —con man, con --help, o al menos preguntándole al mismo modelo qué hace cada parte— y solo después lo corres. Esto es innegociable cuando el comando incluye rm (borra, y en la mayoría de los casos sin papelera de reciclaje), sudo (lo ejecuta con privilegios de administrador, sobre todo tu sistema) o una redirección > (sobrescribe un archivo entero sin preguntar, algo que verás en detalle en el módulo 3). La terminal no tiene una casilla de "¿estás seguro?" para la mayoría de esos casos: la confirmación tiene que pasar por tu cabeza antes de presionar Enter, no después.

Errores comunes

1. Asumir que man y --help siempre muestran lo mismo (conceptual). Son dos fuentes distintas escritas para propósitos distintos: --help es un resumen que genera el propio programa, mientras que la página de manual es documentación aparte, mantenida por quien empaqueta el sistema operativo o el proyecto, casi siempre más completa. Hay además una asimetría que sorprende: los comandos internos de la shell (cd, export, alias, history) no tienen su propia página de manual independiente, porque no son programas separados —viven dentro de bash o zsh—. Cómo detectarlo: man cd te devuelve "No manual entry for cd" o te abre la página general de tu shell (man bash) en vez de una página dedicada. Cómo corregirlo: para comandos internos de la shell, usa help cd (en bash) o busca dentro de man bash/man zshbuiltins en vez de esperar una página propia.

2. apropos responde "nothing appropriate" y se concluye que el comando no existe (práctico). El mensaje no significa "esto no existe en tu sistema": significa que la base de datos que consulta apropos —construida por mandb— nunca se generó, o quedó desactualizada después de instalar paquetes nuevos. Cómo detectarlo: buscas una palabra que sabes con certeza que debería tener resultados (por ejemplo apropos copy, que debería encontrar cp) y no aparece nada. Cómo corregirlo: sudo mandb reconstruye el índice; vuelve a intentar la búsqueda después.

3. Copiar literalmente un ejemplo de tldr (o de un modelo de lenguaje) sin adaptarlo a tu caso (conceptual). Los ejemplos de tldr son genéricos por diseño —usan marcadores de posición como {{target.tar}}— y un modelo de lenguaje responde a tu pregunta, no conoce el estado exacto de tu sistema. Si el ejemplo incluye rm, sudo o > y lo pegas sin revisar qué ruta o qué archivo estás poniendo en el lugar del marcador, el riesgo no es que el comando esté "mal": es que esté bien para un caso genérico y mal para el tuyo. Cómo detectarlo: te preguntas "¿podría explicar en voz alta qué hace cada palabra de este comando?" y no puedes. Cómo corregirlo: reemplaza cada marcador de posición conscientemente y, si el comando toca algo irreversible, corre primero una versión que solo liste o solo imprima, antes de la versión que actúa.

Ejercicios

1. Leer una sinopsis. Corre man mkdir y mira su línea de SYNOPSIS. Sin ejecutar nada todavía: ¿el argumento de directorio es obligatorio u opcional según la notación? ¿Se puede pasar más de un directorio en una sola llamada? Justifica tu respuesta señalando qué símbolo de la notación te lo dice.

2. Distinguir secciones de manual. Corre apropos passwd (o man -k passwd, es lo mismo). Vas a ver al menos dos entradas con el mismo nombre passwd pero número de sección distinto entre paréntesis. ¿Qué comando abre específicamente la que describe el formato del archivo, y no el comando para cambiar tu contraseña?

man 5 passwd

3. Encontrar un flag con --help y una tubería. Sin abrir el manual completo, usa ls --help combinado con grep (la viste de pasada en la lección anterior como parte de la ergonomía de la terminal; se profundiza en el módulo 3) para encontrar, en una sola línea de salida, qué flag corto ordena por tamaño de archivo de mayor a menor.

ls --help | grep -i size

4. Diagnosticar apropos roto. Un compañero jura que cp no existe en su sistema porque apropos copy no le devuelve nada. Tú sabes que cp sí está instalado —lo usó hace cinco minutos—. ¿Qué es lo más probable que esté pasando, y qué comando se lo arregla?

sudo mandb

Resumen y siguiente paso

Ya puedes abrir el manual completo de cualquier comando con man, leer su sinopsis para saber qué es obligatorio, qué es opcional y qué se repite, pedir un resumen rápido con --help, encontrar ejemplos de uso real con tldr, buscar un comando por lo que hace con apropos cuando no recuerdas su nombre, y verificar en el manual —antes de ejecutar— cualquier comando que te haya sugerido otra persona o un modelo de lenguaje.

Antes de avanzar deberías poder:

• Abrir man de un comando que nunca usaste y decir, solo leyendo la sinopsis, cuáles de sus argumentos son obligatorios.
• Explicar la diferencia entre lo que ofrece man, --help y tldr, y cuándo usarías cada uno.
• Reconstruir la base de datos de apropos cuando responde "nothing appropriate" sin motivo aparente.

Con esto, ya no dependes de esta guía —ni de ningún tutorial— para aprender un comando nuevo: sabes dónde está la fuente oficial y cómo leerla. Lo que te falta ahora es el mapa completo del terreno donde se ejecutan todos esos comandos: la siguiente lección instala el modelo mental central de toda la guía, el sistema de archivos como un único árbol que nace en /, y la diferencia entre moverte por rutas absolutas y relativas dentro de él.

Recursos

• man-pages(7) — Linux manual page — la fuente oficial de las convenciones de notación de la sinopsis (negrita, cursiva, corchetes, puntos suspensivos, barra vertical) usadas en esta lección.
• apropos(1) — Linux manual page — referencia oficial de apropos, incluyendo su relación con la base de datos que construye mandb.
• whatis(1) — Linux manual page — la herramienta hermana de apropos: descripción de una línea a partir del nombre exacto de un comando.
• tldr-pages — repositorio oficial — el proyecto comunitario detrás de tldr, con la lista actualizada de clientes disponibles para instalar.
• GNU Coreutils Manual — Invoking ls — documentación oficial de las opciones de ls usadas en los ejemplos de esta lección.