Linux Lexicon — Anatomía de una página man
Publicado: 2016-11-01
Bytes cortos: las páginas de manual y la documentación del software pueden ser lo suficientemente gruesas y difíciles para cualquier principiante sin las convenciones crípticas asociadas con todo tipo de corchetes y paréntesis. Aquí, intentaremos atenuar la complejidad de las páginas man de Linux y hacer que sea más fácil de entender.
NOMBRE
Primero está el encabezado del nombre, y eso lo resume todo. Esta sección incluye el nombre de la utilidad, así como una breve descripción.
SINOPSIS
Hay diversos grados de legibilidad de una página de manual a otra, pero una cosa es segura, la parte más difícil suele ser descifrar una sinopsis peluda. Hay varias convenciones para indicar la información requerida para cualquier comando dado. Estas convenciones consisten en diferentes corchetes y paréntesis, así como otras formas de notación. Todas estas diferentes convenciones pueden ser extremadamente confusas para un principiante y aún abrumadoras para alguien que tiene experiencia pero no es versado en el arte de los manuales. A continuación, desglosaremos el galimatías en reglas digeribles.
| envalentonado | Escriba exactamente como se muestra. |
| cursiva o subrayado | Reemplace con el argumento apropiado. |
| [-abcxyz] | Todas las banderas entre corchetes son opcionales. |
| -a | -B | Las opciones separadas por tubería no se pueden usar juntas. |
| <obligatorio> | Argumento obligatorio, que normalmente se encuentra en las descripciones de las opciones. |
| {sí No} | Opciones limitadas, solo funcionarán las especificadas. |
| … | Los argumentos seguidos de puntos suspensivos se pueden repetir. |
Estas reglas son bastante simples, pero se vuelven más difíciles e incluso intimidantes cuando se usan en definiciones de funciones largas, especialmente cuando están anidadas. Por lo tanto, veremos algunos anidamientos a continuación para construir lo que hemos desglosado.
tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ ARG ...]
El comando tar tiene muchas opciones. Vemos el nombre del comando tar en negrita porque debe escribirse como se muestra. Luego vemos que las llaves se abren con opciones separadas por tuberías que indican que estamos limitados a esas y debemos elegir solo una. A continuación están las banderas opcionales, podemos usar cualquier número, aunque es posible que no todas funcionen juntas, leer más en la página de manual arrojará luz sobre cualquier posible conflicto de opciones. Y, por último, tenemos el argumento repetible, en el caso de tar, esto para los archivos en los que está operando.
su [opciones] [-] [ usuario [ argumento …]]
De nuevo, vemos su en negrita porque es el nombre del comando. En segundo lugar, vemos que en realidad no se especifican banderas, solo que son opcionales. En tercer lugar, se especifica un solo indicador, pero también es opcional. Por último, vemos un argumento opcional que se puede repetir dentro de un argumento opcional. Ahora, lo que solía parecer muy misterioso tiene más sentido.
whois [{-h|–host } HOST ] [{-p|–port} PORT ] [-abBcdGHKlLmMrRx] [-g SOURCE:FIRST-LAST ] [-i ATTR [, ATTR ]…] [-s SOURCE [, FUENTE ]…] [-T TIPO [, TIPO ]…] [–detallado] OBJETO
Este es uno particularmente denso. Cópielo en su editor de texto favorito y agregue algunos espacios adicionales allí si le ayuda a leerlo. Después de escanear esto, debería comenzar a ver un par de patrones. Las porciones de host y puerto usan el mismo formato para la forma corta y larga de la opción seguida por el argumento para esa opción, mientras que ambas son opcionales. Luego vemos la cadena de banderas opcionales. El siguiente bit sobre las fuentes de la primera a la última es la sintaxis que espera whois que se explica más adelante en la página del manual. Ahora vemos este triplete de banderas opcionales que toman un solo argumento o argumentos repetitivos opcionales, este es el tipo de combinación de convenciones que puede ser muy difícil de entender completamente al principio. Por último, hay una opción detallada y el objeto (el host/dominio).
Y así es como se lee la sinopsis de una página man. Hay algunas otras convenciones, pero son demasiado oscuras para cubrirlas en este artículo.
DESCRIPCIÓN
Por lo general, aquí es donde se describe el uso previsto del programa o la utilidad. Algunos manuales serán mucho más detallados bajo este encabezado que otros.
OPCIONES
¿Recuerdas todas esas banderas y diferentes argumentos que podrían ser opcionales u obligatorios? Aquí es donde se explican todos. Por lo general, hay buena información aquí y, a menudo, es donde encontrará la convención <argument>, que indica que un indicador dado requiere un argumento correspondiente. A veces encontrará que las opciones estarán en la parte de descripción porque no hay una regla estricta que defina las páginas de manual, solo convenciones y la voluntad de cumplir con los estándares.
EJEMPLOS
Esta es una de las partes más útiles que, lamentablemente, no se incluye en todos los manuales. También encontrará que la cantidad de información y la cantidad de ejemplos varía significativamente, y no todos los ejemplos realmente ayudan con el uso del comando.
Además, encontrará regularmente secciones para el autor, información de derechos de autor, informes de errores y ver también (a propósito).
Más allá de esto, existen las secciones formalmente definidas de las páginas man como se define a continuación.
| 1 | Programas ejecutables o comandos de shell |
| 2 | Llamadas al sistema (funciones proporcionadas por el kernel) |
| 3 | Llamadas de biblioteca (funciones dentro de bibliotecas de programas) |
| 4 | Archivos especiales (normalmente se encuentran en /dev) |
| 5 | Formatos de archivo y convenciones, por ejemplo, /etc/passwd |
| 6 | Juegos |
| 7 | Varios (incluidos paquetes de macros y convenciones), por ejemplo, man(7), groff(7) |
| 8 | Comandos de administración del sistema (generalmente solo para root) |
| 9 | Rutinas del kernel (normalmente no se encuentran en Linux) |
Muchos comandos no tienen manuales en más de una sección, pero para los que los tienen, o para algunos que pueden tener un nombre ambiguo, puede especificar la sección como en el ejemplo a continuación.
Los comandos no son las únicas cosas que tienen manuales, como puede ver en las secciones disponibles. Las llamadas de sistemas, los archivos de configuración y los dispositivos especiales pueden tener una página de manual correspondiente. La cantidad de información sobre una instalación típica de Linux solo en las páginas de manual es sorprendente, y lo mismo se aplica a otros sistemas operativos de código abierto similares a UNIX.
Si encuentra que la página de manual no es suficiente y aún no comprende un comando, siempre verifique en línea porque muchas personas ofrecen explicaciones más detalladas de ciertas herramientas, pero también, muchas distribuciones tienen sus propias páginas de manual para diferentes paquetes de software. Una vez que haya descubierto que se siente cómodo con una pieza de software, pero aún siente que falta el manual, siempre puede contribuir escribiendo el suyo propio y enviándolo al proyecto respectivo. La documentación suele ser la parte más descuidada de los proyectos de software, por lo que incluso si no puede escribir código, puede escribir manuales, artículos Wiki y tutoriales para ayudar a otros.
Ahora que conoces la anatomía de una página de manual, no tienes más excusa que usar RTFM (y eso es leer el manual gratuito para los menores de 18 años) ;)
Lea también: Léxico de Linux: use el comando Watch para ejecutar un comando cada X segundos