Man pages y documentación off-line

0
132

¡Hola amigas y amigos!

La mayoría de los usuarios de Linux, cuando necesitan una documentación determinada, casi siempre y como primera opción la buscan en la Aldea www. Vale la pena preguntarse: ¿es un buen hábito?.

Siempre me ha llamado la atención la enorme cantidad de documentación disponible en las diversas distribuciones Linux en forma de páginas del manual o man pages, paquetes doc, documentación ubicada generalmente en el directorio /usr/share/doc, etcétera. Documentación que, con mucho esfuerzo y dedicación, confeccionaron muchos voluntarios para que al menos fuese leída y en el mejor de los casos, estudiada.

Empecé a usar el Debian 3 “Sarge” a partir de sus 14 CDROMs de instalación y sin acceso a Internet, allá por el año 2006. Aprendí preguntando directamente a mi amigo y colega Julio Cesar, y buscando en la documentación disponible localmente. Confieso que al principio las páginas del manual me parecían cifradas. 😉

Este artículo va dirigido a los interesados en conocer lo mas general y básico sobre la Documentación Fuera de LíneaOff-Line que pueden encontrar en su propio equipo.

man

La mejor explicación sobre la utilidad man la proporciona ella misma:

buzz@sysadmin:~$ man man
MAN(1)                    Útiles de Páginas de Manual                   MAN(1)

NOMBRE
       man - una interfaz de los manuales de referencia electrónicos

SINOPSIS
       man  [-c|-w|-tZT  dispositivo] [-adhu7V] [-m sistema[,...]] [-L locale]
       [-p cadena] [-M  ruta]  [-P  paginador]  [-r  prompt]  [-S  lista]  [-e
       extension] [[sección] pagina ...] ...
       man  -l  [-7] [-tZT dispositivo] [-p cadena] [-P paginador] [-r prompt]
       fichero ...
       man -k [-M ruta] palabra_clave ...
       man -f [-M ruta] pagina ...

DESCRIPCIÓN
       man es el paginador del manual del sistema.  Las  páginas  usadas  como
       argumentos al ejecutar man suelen ser normalmente nombres de programas,
       útiles o funciones.  La página de manual associada con cada uno de esos
       argumentos  es  buscada  y  presentada.   Si  la  llamada da también la
       sección, man buscará sólo en dicha sección del manual.  Normalmente, la
       búsqueda  se  lleva a cabo en todas las secciones de manual disponibles
       según un orden predeterminado, y sólo se  presenta  la  primera  página
       encontrada, incluso si esa página se encuentra en varias secciones.

       La  siguiente  tabla  muestra  los  números de sección del manual y los
       tipos de páginas que contienen.

       1   Programas ejecutables y guiones del intérprete de órdenes
       2   Llamadas del sistema (funciones servidas por el núcleo)
       3   Llamadas de la biblioteca (funciones contenidas en las  bibliotecas
           del sistema)
       4   Ficheros especiales (se encuentran generalmente en /dev)
       5   Formato de ficheros y convenios p.ej. I/etc/passwd
       6   Juegos
       7   Paquetes de macros y convenios p.ej. man(7), groff(7).
       8   Órdenes  de  admistración  del  sistema (generalmente solo son para
           root)
       9   Rutinas del núcleo [No es estándar]
       n   nuevo [obsoleto]
       l   local [obsoleto]
       p   público [obsoleto]
       o   viejo [obsoleto]

       Una página de manual tiene varias partes.

       Éstas están etiquetadas como NOMBRE, SINOPSIS,  DESCRIPCIÓN,  OPCIONES,
       FICHEROS, VÉASE TAMBIÉN, BUGS, y AUTOR.

       En  la  sección  SINOPSIS se siguen los siguientes convenios que pueden
       servir de guía para otras secciones.

       texto en negrita   debe teclear esto exactamente.
       texto en cursiva   reemplace esto por el argumento apropiado.
       [-abc]             uno o  todos  los  argumentos  entre  corchetes  son
                          opcionales.
       -a|-b              las  opciones  separadas  por  |  no  pueden  usarse
                          conjuntamente.
       argumento ...      argumento es repetible.
       [expresión] ...    la expresión entre corchetes completa es repetible.

       El ejemplo del empleo de la orden o función  debe  recogerá  todos  los
       posibles  usos.  En algunos casos es recomendable ilustrar algunos usos
       exclusivos como se puede ver en la SINOPSIS de esta página de manual.

Solo transcribo un fragmento. Directamente en la consola se lee mucho mejor.

  • Si queremos guardar en un archivo de texto plano el contenido de cualquier man page, lo logramos mediante el siguiente comando:
buzz@sysadmin:~$ man man > man.man
  • Para estudiar su contenido –lo cual es muy instructivo– lo abrimos con el editor de nuestra preferencia:
buzz@sysadmin:~$ pluma man.man
  • Los ejemplos de uso de man lo encontramos en la misma salida del comando man man:
EJEMPLOS
       man ls
           Presenta la página de manual del elemento (programa) ls.

       man -a intro
           Presenta, secuencialmente, todas las páginas de  intro  disponibles
           en  el  manual.  Entre página y página se puede decidir saltar a la
           siguiente o salir del paginador completamente.


       man -t alias | lpr -Pps
           Formatea la página de manual referenciada por `alias', generalmente
           una   página   de   manual   de   tipo  shell,  usando  el  formato
           predeterminado troff o groff y redirige la salida  a  la  impresora
           llamada  ps.   La  salida  predeterminada  de groff generalmente es
           PostScript.  man --help debería informarle de que  procesador  está
           siendo usado con la opción -t

       man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi
           Esta  orden  descomprime  y  formatea el fichero fuente nroff de la
           página de manual ./foo.1x.gz y  lo  convierte  en  un  fichero  con
           formato  independiente  de dispositivo (dvi).  Es necesario usar la
           redirección pues la opción  -T  dirige  la  salida  al  stdout  sin
           paginador.  La  salida puede verse mediante un programa como xdvi o
           puede incluso convertirse al formato PostScript usando un  programa
           como dvips.

       man -k printf
           Busca  la palabra clave printf entre las descripciones breves y las
           páginas de manual y presenta todas las que casen.

       man -f smail
           Busca las páginas de manual referenciadas por smail  e  imprime  la
           descripcion breve de las que encuentre.

whatis

Quién mejor que el propio man whatis nos ofrece la explicación de esta utilidad:

buzz@sysadmin:~$ man whatis
WHATIS(1)                 Útiles de Páginas de Manual                WHATIS(1)

NOMBRE
       whatis - imprime descripciones de páginas de manual

SINOPSIS
       whatis [-dhV] [-r|-w] [-m sistema[,...]] [-M ruta] nombre ...

DESCRIPCIÓN
       Cada página de manual contiene una pequeña descripción.  whatis realiza
       una búsqueda entre los nombres de  las  páginas  de  manual,  mostrando
       aquellos que se asemejen al nombre dado.

       nombre  puede  contener caracteres comodín (-w) o puede tratarse de una
       expresión regular (-r).   Si  se  usa  una  de  estas  opciones,  puede
       resultar  necesario  entrecomillar  el  nombre o anteponer `\' a dichos
       caracteres para evitar que el intérprete de órdenes los sustituya.

       Las bases de datos  índices  son  usadas  durante  la  búsqueda.   Para
       generar  una  base  de datos whatis antigua tipo texto de la base index
       índice, basta usar la orden:

       whatis -M ruta_de_manual -w '*' | sort > ruta_de_manual/whatis

       donde ruta_de_manual es una jerarquía de páginas de  manual  como,  por
       ejemplo, /usr/man.
  • Ejemplos:
buzz@sysadmin:~$ whatis cat
cat (1)              - concatenate files and print on the standard output
buzz@sysadmin:~$ whatis ls
ls (1)               - list directory contents
buzz@sysadmin:~$ whatis nano
nano (1)             - Nano's ANOther editor, an enhanced free Pico clone

apropos

Seguimos con la tónica del comando anterior:

buzz@sysadmin:~$ man apropos
APROPOS(1)                Útiles de Páginas de Manual               APROPOS(1)

NOMBRE
       apropos - buscar entre las páginas del manual y las descripciones

SINOPSIS
       apropos  [-dhV]  [-e|-w|-r]  [-m sistema[,...]] [-M ruta] palabra_clave
       ...

DESCRIPCIÓN
       Cada página de manual contiene una pequeña descripción.  apropos  busca
       dentro de esas descripciones la presencia de la palabra_clave.

       La  palabra_clave  es  normalmente  una  expresión  regular, como si se
       hubiese usado (-r) , puede contener caracteres comodín (-w) , o ser  la
       palabra  clave  exacta (-e)  . Cuando se usan estas opciones, puede ser
       necesario  entrecomillar  la  palabra_clave  o  anteponer  (\)  a   los
       caracteres especiales para evitar que la shell los interprete.

       Las  reglas  estándar  permiten  buscar  en  nombres de página y en las
       palabras completas de la descripción de cada página.
  • Ejemplos:
buzz@sysadmin:~$ apropos mount

buzz@sysadmin:~$ apropos -e mount
mount (2)            - mount filesystem
mount (8)            - mount a filesystem
mount.cifs (8)       - mount using the Common Internet File System (CIFS)
mount.nfs (8)        - mount a Network File System
mountd (8)           - NFS mount daemon
mountstats (8)       - Displays NFS client per-mount statistics
nfsiostat (8)        - Emulate iostat for NFS mount points using /proc/self/m...
rpc.mountd (8)       - NFS mount daemon
setup (2)            - setup devices and filesystems, mount root filesystem
showmount (8)        - show mount information for an NFS server
switch_root (8)      - switch to another filesystem as the root of the mount ...
systemd.mount (5)    - Mount unit configuration

buzz@sysadmin:~$ apropos xyzl xzless
xzless (1)           - view xz or lzma compressed (text) files
xyzl: nada apropiado.

gman

buzz@sysadmin:~$ man gman
NAME
       gman - GTK+ based front-end for man, a good replacment for xman.

SYNOPSIS
       gman

DESCRIPTION
       Gman  is a front-end for the manual page system. gman builds a database
       of all the available man pages and displays them in a list. Clicking on
       an  entry  in the list makes gman launch another window with the manual
       page displayed in it.

       Gman can launch more than one window at same time. The user can use the
       index/key  word  search  function  to  look for the man pages that they
       need.

       It is simple, but it is useful.

OPTIONS
       There are no command line options for gman, for now.

Utilidad gráfica que reemplaza al visor y buscador xman de páginas del manual para el sistema X Windows. gman construye una base de datos de todas las man pages y muestra una lista para la búsqueda fácil de comandos, programas y utilidades. Cuando hacemos clic sobre un elemento de la lista, se abre una consola con la página del manual solicitada. En su menú encontraremos varias opciones de configuración las cuales nos pueden ser útiles.

  • La mejor forma de aprender sobre gman es precisamente usándolo. 😉

gmanedit

buzz@sysadmin:~$ man gmanedit
gmanedit(1)                  Gnome manpages editor                 gmanedit(1)

NAME
       gmanedit - GTK+ program for editing manual pages.

SYNOPSIS
       gmanedit

DESCRIPTION
       gmanedit  can be used to edit existing manual pages or create new pages
       with the help of a wizard. Created pages can be viewed with the help of
       an external application.

BUGS
       Report bugs to the Joop Stakenborg <pg4i@amsat.org>

                                March 10, 2008                     gmanedit(1)

Editor gráfico de las páginas del manual. Se utiliza para la edición de páginas existentes o para la creación de nuevas mediante la ayuda de un asistente o wizard. Con la ayuda de un visor externo podemos visualizar las páginas recién creadas.

Ayuda off-line sobre comandos

Por regla general encontramos una corta ayuda sobre los comandos si ejecutamos:

<comando> --help.
  • Ejemplos:
buzz@sysadmin:~$ man --help
buzz@sysadmin:~$ whatis --help
buzz@sysadmin:~$ apropos --help

buzz@sysadmin:~$ cat --help
Modo de empleo: cat [OPCIÓN]... [FICHERO]...
Concatena FICHERO(s), o la entrada estándar, en la salida estándar.

  -A, --show-all           lo mismo que -vET
  -b, --number-nonblank    numera las líneas que no están vacías, desactiva -n
  -e                       lo mismo que -vE
  -E, --show-ends          muestra un $ al final de cada línea
  -n, --number             numera todas las líneas
  -s, --squeeze-blank      suprime líneas vacías repetidas
  -t                       equivalente a -vT
  -T, --show-tabs          muestra los caracteres de tabulación como ^I
  -u                       (sin efecto)
  -v, --show-nonprinting   utiliza la notación ^ y M-, salvo para LFD y TAB
      --help     muestra esta ayuda y finaliza
      --version  informa de la versión y finaliza

Sin FICHERO, o cuando FICHERO es -, lee la entrada estándar.

Ejemplos:

   cat f - g Muestra los contenidos de f, luego la entrada estándar,
              luego los contenidos de g.
   cat       Copia la entrada estándar en la salida estándar.

ayuda en línea sobre GNU coreutils: <http://www.gnu.org/software/coreutils/>
Informe de errores de traducción en cat a <http://translationproject.org/team/es.html>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'
  • De igual forma procedemos con los comandos que necesitemos:
buzz@sysadmin:~$ less --help
buzz@sysadmin:~$ ls --help
buzz@sysadmin:~$ dir --help
buzz@sysadmin:~$ nano --help
buzz@sysadmin:~$ pluma --help

Directorio /usr/share/doc

La mayoría de los programas instalados tienen una carpeta dentro de este directorio donde se almacena la documentación que por defecto se instala con el programa. Mi carpeta /usr/share/doc consta actualmente de 1920 directorios, mientras que el sistema tiene 1914 paquetes instalados.

Para acceder al directorio de referencia podemos emplear el navegador de archivos o el navegador www de nuestra preferencia. Por ejemplo, el contenido de la carpeta /usr/share/doc/apache2 es el siguiente:

buzz@sysadmin:~$ ls -l /usr/share/doc/apache2
total 180
drwxr-xr-x 2 root root  4096 feb  8  2017 examples
-rw-r--r-- 1 root root 20822 ago  7  2016 copyright
-rw-r--r-- 1 root root 57739 sep 15  2016 changelog.Debian.gz
-rw-r--r-- 1 root root 56632 sep 15  2016 changelog.gz
-rw-r--r-- 1 root root  1512 ago  7  2016 migrate-sites.pl
-rw-r--r-- 1 root root  4511 jul  5  2016 NEWS.Debian.gz
-rw-r--r-- 1 root root  6894 jul  5  2016 PACKAGING.gz
-rw-r--r-- 1 root root  1210 ago  7  2016 README.backtrace
-rw-r--r-- 1 root root  5975 jul  5  2016 README.Debian.gz
-rw-r--r-- 1 root root  3356 ago  7  2016 README.multiple-instances
  • Para visualizar el contenido del archivo README.Debian.gz ejecutamos:
buzz@sysadmin:~$ zless /usr/share/doc/apache2/README.Debian.gz
Contents
========

        Apache2 Configuration under Debian GNU/Linux
                Files and Directories in '/etc/apache2'
                Tools

        Using mod_cache_disk

        SSL
                Enabling SSL
                Creating self-signed certificates
                SSL workaround for MSIE

        Suexec

        Documentation

        Upgrades

        Common Problems

        For Developers

Apache2 Configuration under Debian GNU/Linux
============================================

Debian's default Apache2 installation attempts to make adding and
removing modules, virtual hosts, and extra configuration directives as
flexible as possible, in order to make automating the changes and
administering the server as easy as possible.

Please be aware that this layout is quite different from the standard
Apache configuration. Due to the use of environment variables, apache2
needs to be started/stopped with '/etc/init.d/apache2', apachectl, or
apache2ctl. Calling '/usr/bin/apache2' directly will not work with the
default configuration. To call apache2 with specific command line
arguments, just call apache2ctl with the same arguments.

Files and Directories in '/etc/apache2':
---------------------------------------

apache2.conf

        This is the main configuration file. It does not include any
        actual configuration we expect to be adapted on your site, so
        where possible please do not touch it. This file is the
        foundation stone of the Apache configuration in Debian and should
        be up to date after upgrades to make sure all configuration pieces
    ----
/usr/share/doc/apache2/README.Debian.gz
  • Solo agregaremos que ésta documentación a la que personalmente denomino “cautiva”, me ha sido de extrema utilidad en numerosas ocasiones y me ha facilitado la instalación y configuración inicial de muchos programas, sin acudir a una búsqueda en la Aldea WWW.

Paquetes de documentación

Una de las fuentes de documentación off-line mas importante, la encontramos en los paquetes de documentación existentes en el repositorio. Por regla general, los nombres de esos paquetes contienen la cadena “-doc” o “-manual“. Pueden ser muy útil cuando necesitemos conocer la disponibilidad de documentación de un programa en específico antes de instalarlo, o cuando la queremos leer sin instalar el programa.

  • Paquetes de documentación del Nginx web/proxy server
buzz@sysadmin:~$ apt-cache search nginx --names-only | grep doc
nginx-doc - small, powerful, scalable web/proxy server - documentation
  • Instalamos el paquete nginx-doc sin instalar el programa
buzz@sysadmin:~$ sudo apt install nginx-doc
  • Determinamos la ubicación de los archivos instalados por nginx-doc
buzz@sysadmin:~$ sudo dpkg -L nginx-doc
/.
/usr
/usr/share
/usr/share/doc
/usr/share/doc/nginx-doc
/usr/share/doc/nginx-doc/copyright
/usr/share/doc/nginx-doc/upstream
/usr/share/doc/nginx-doc/fcgiwrap
/usr/share/doc/nginx-doc/changelog.Debian.gz
/usr/share/doc/nginx-doc/examples
/usr/share/doc/nginx-doc/examples/virtual_hosts.gz
/usr/share/doc/nginx-doc/examples/mail
/usr/share/doc/nginx-doc/examples/mailman
/usr/share/doc/nginx-doc/examples/http
/usr/share/doc/nginx-doc/examples/nginx_modsite.gz
/usr/share/doc/nginx-doc/examples/nginx.conf
/usr/share/doc/nginx-doc/examples/wordpress
/usr/share/doc/nginx-doc/examples/drupal.gz
/usr/share/doc/nginx-doc/changelog.gz
/usr/share/doc/nginx-doc/README
/usr/share/doc/nginx-doc/php
/usr/share/doc/nginx-doc/support-irc

De ésta forma podemos consultar la documentación sobre el Nginx antes de su instalación definitiva. Observemos los ejemplos de configuración disponibles sin necesidad de acudir a Internet. Por otra parte y como reza en su archivo README, la documentación es oficial ya que hace referencia al sitio “Documentation is available at http://nginx.org“.

De igual forma procedemos con otros programas que sean de nuestro interés.

  • ¿Cúales paquetes con documentación sobre el Apache HTTP Server están disponibles en el repositorio?
buzz@sysadmin:~$ apt-cache search apache --names-only | grep doc
libapache-mime4j-java-doc - MIME and RFC822 parser for Java - documentation
apache2-doc - Apache HTTP Server (on-site documentation)
libapache-mod-jk-doc - Documentation of libapache2-mod-jk package
libapache-poi-java-doc - Apache POI - Java API for Microsoft Documents (Documentation)
libapache2-mod-perl2-doc - Integration of perl with the Apache2 web server - documentation
libapache2-mod-python-doc - Python-embedding module for Apache 2 - documentation
libapache2-mod-rivet-doc - Documentation for Rivet, a server-side Tcl programming system
  • ¿Cuáles son los paquetes que contienen la cadena “-doc” o la cadena “-manual” en su nombre?
buzz@sysadmin:~$ apt-cache search '[-]doc|[-]manual' --names-only
buzz@sysadmin:~$ aptitude search '[-]doc|[-]manual'

Resumen

  • Existen mas utilidades relacionadas con las man pages, manuales y documentación general que no mencionamos para no alargar mas este documento, o porque no conocemos de su existencia.
  • Aunque el artículo resulte un poco largo, hemos escrito la mayor parte de la salida de cada comando, para hacer énfasis en lo importante y exacta que es la ayuda y documentación a nuestro alcance sin necesidad de navegar por Internet. Usted debe estudiar detenidamente el contenido completo de cada una de ellas como buena práctica de aprendizaje.
  • Como hábito, debemos primero consultar a esta documentación y sino nos satisface, acudir a una búsqueda en Internet.
  • Siéntase libre de probar con cualquier página del manual, comando, paquete de documentación, etcétera.

¡Hasta la próxima entrega!

Dejar respuesta

Please enter your comment!
Please enter your name here