RTFM “Read The Fucking Manual”

Guía practica para leer man pages

Los man pages es un sistema de ayuda integrado en Linux llamando man, casi todos los programas de comandos y utilidades de Linux tienen una documentación de apoyo. Una página de manual típica cubre el resumen, la descripción y los ejemplos del comando en cuestión.

La sinopsis te muestra la estructura de un comando. La descripción describe lo que hace el comando, así como las opciones disponibles y los indicadores para el comando. La sección de ejemplos te muestra diferentes formas en las que puede usar el comando.

👇🏼 Aquí habrá un dato curioso sobre el acrónimo RTFM, te invito a leerlo sino puedes saltártelo con gusto. (:

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Es una expresión que se remonta a varias décadas. Fue utilizado durante la década de 1940 por los soldados de EE. UU., Y luego se convirtió en un término informático desde que el software de álgebra lineal de 1979 apareció en el idioma Fortran.

La primera impresión registrada de RTFM fue la guía del usuario de LINPACK que se publicó en 1979:

https://en.wikipedia.org/wiki/RTFM#/media/File:Linpack_manual_intro_1979.png

Si bien no hay un origen verificable del acrónimo RTFM, se cree que se originó con el Ejército de los EE. UU. en 1939, después de haber producido documentos llamados “Manuales de campo”. Estos manuales explicaban cómo los soldados realizarían muchas tareas regulares, como disparar sus armas, lanzar granadas de mano, limpiar sus prendas, doblar la ropa y preparar sus uniformes para la inspección.

Como sucedería naturalmente, los soldados que fueron entrenados a través de estos manuales gritarían ‘RTFM’ y ‘Lea el manual de instrucciones’ a los nuevos reclutas cada vez que los reclutas hicieran preguntas tontas.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Si ingresamos al manual del manual, podremos ver que nos describe ciertos intereses de como leer los manuales, entre otras cosas que nos pueden ser de ayuda.

La forma de salir de los man pages, es usando la tecla “q”. Si usamos el comando “h” estando en cualquier manual, este desplegara los comandos que puedes usar para moverte en el y otras utilidades.

Los manuales constan de varias secciones

Si seguimos desplazándonos por el man, vamos a ver que significan diferentes convenciones, para que podamos poner lo que vemos en una pagina de manual realmente en acción.

  • Texto en negrita, se deberá escribir exactamente como se muestra.
  • Texto en subrayado o cursiva, se debe reemplazar con el argumento. apropiado
  • Texto dentro de [-abc] corchetes, recordar que es opcional.
  • Si se encuentra con dos opciones que son separados por | barra vertical, simplemente sepa que no pueden ser usados juntos, familiarizados con el operador lógico OR en el ejemplo vemos que puede usar a ó b, simplemente no puede usar ambas opciones al mismo tiempo.
  • El argumento de tres puntos suspensivos (…) también llamados elipsis significa que puede repetirlo.
  • Texto dentro de [expression] … corchetes y seguido de puntos suspensivos, es repetible.

los puntos suspensivos nos dice que puede ejecutar el comando ‘ls’ con uno o mas opciones y / o uno o mas archivos [FILE]

por cierto cuando vea la palabra archivo, puede ser archivo o directorio

[OPTION] esta entre paréntesis lo que significa que es opcional, dicho de otra manera, no se requiere una opción puede o no utilizar una opción cuando ejecuta el comando ‘ls’, así que se puede deducir de la sinopsis es que puede ejecutar este comando por si solo, ya que todo es opcional. Si continuamos leyendo encontraremos que sucede cuando no proporciona ningún argumento así como las opciones con formato corto o largo que puede utilizar con sus respectivas descripciones de uso.

Los comandos que busquemos estarán en la sección uno (1), si estamos haciendo alguna programación de Linux de bajo nivel, podríamos buscar las secciones dos (2) o tres (3) por ejemplo. Puede saber en que sección se encuentra actualmente mirando en la parte superior izquierda de la pagina de manual.

Este dato no puede resultarte útil, pero en realidad solo hay un momento en el que esto importa y es cuando hay paginas de manual para una cosa en múltiples secciones de forma predeterminada, man usa un orden predefinido para buscar en las paginas de manual y solo te dará la primera que encuentra.

Podríamos saber cuantas secciones tiene un comando usando la opción de búsqueda [man -k + comando] ó algunas palabras claves entre comillas dobles “ ” este te traerá el manual correspondiente con su descripción y su sección. Si queremos ingresar a una sección especifica solo se colocaría el numero después de la palabra man (man 2 comando).

Supongamos que se te olvida el comando de como listar lo que se encuentra en tu directorio pero sabes que es lo que quieres hacer o que realiza este comando, que en este caso es listar el contenido de un directorio, si somos un poco vagos con lo que ponemos el simplemente traerá todo lo que contenga la palabra “list” que créeme son muchas, así que debemos poner algo mas significativo ejemplo, “list directory”.

Si llegamos a ver una sección de la siguiente manera (3p) es por que son parte de la documentación POSIX que significa interfaz portable del sistema operativo y es un conjunto de estándares utilizados por UNIX y sistemas operativos tipo Unix por lo que la implementación podría ser diferente.

y por ultimo, también podemos ver la pagina de manual que describe las convenciones para escribir paginas de manual

En esta describe las secciones que normalmente tienen los manuales, para que puedas escribir tu propio manual.

man (7) puedes encontrar las macros para formatear paginas del manual, una vez creadas con tu IDE como un archivo de texto simple pero usando las macros, solo tendrás que ejecutarlo escribiendo

$ man ./tu_propio_manual

Si, consideras que le falta algo mas a esta publicación o crees que hay un posible error. Te invito a contactarme ✉️ por Twitter Paola (@p_ycc) para solucionarlo.

Software Engineer in progress

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store