7.1. Fuentes de documentación
Antes de que pueda entender lo que realmente está pasando cuando hay un problema, necesita saber el rol que cumple en teoría cada programa involucrado en el problema. Para hacerlo, lo mejor que puede hacer es consultar su documentación; pero ya que dichos documentos son numerosos y muy dispersos debe saber todos los lugares donde puede encontrarlos.
Manual pages, while relatively terse in style, contain a great deal of essential information. We will quickly go over the command for viewing them. Simply type
man manual-page
— the manual page usually goes by the same name as the command whose documentation is sought. For example, to learn about the possible options for the
cp
command, you would type the
man cp
command at the shell prompt (see sidebar
VOLVER A LOS CIMIENTOS La consola, un intérprete de línea de órdenes).
Las páginas de manual no sólo documentan programas en la línea de órdenes, también archivos de configuración, llamadas de sistema, funciones de la biblioteca C y más. A veces pueden coincidir ciertos nombres. Por ejemplo, la orden de la consola read
tiene el mismo nombre que la llamada de sistema read
. Es por eso que las páginas de manual están organizadas en secciones numeradas:
órdenes que pueden ser ejecutadas desde la línea de órdenes;
llamadas de sistema (funciones proporcionadas por el núcleo);
funciones de biblioteca (proporcionadas por las bibliotecas del sistema);
dispositivos (en Unix éstos son archivos especiales generalmente ubicados en el directorio /dev/
);
archivos de configuración (formatos y convenciones);
juegos;
conjuntos de «macros» y estándares;
órdenes de administración del sistema;
rutinas del núcleo.
Es posible especificar la página del manual que está buscando: para visualizar la documentación de la llamada de sistema read
utilizaría man 2 read
. Cuando no se especifique una sección explícitamente, se mostrará la primera sección que posea una página de manual con el nombre pedido. Por lo tanto, man shadow
mostrará shadow(5) porque no hay páginas de manual para shadow en las secciones 1 a 4.
Por supuesto, si no sabe el nombre del programa, el manual no le será de mucha utilidad. Éste es el propósito del programa apropos
que le ayuda a buscar en las páginas de manual, más específicamente en sus descripciones cortas. Cada página de manual comienza esencialmente con un resumen de una línea. apropos
devuelve una lista de las páginas de manual que mencionan en su resumen la palabra clave pedida (o todas las ingresadas). Si las selecciona correctamente encontrará el nombre del programa que necesita.
Ejemplo 7.1. Encontrar cp
con apropos
$
apropos "copy file"
cp (1) - copy files and directories
cpio (1) - copy files to and from archives
gvfs-copy (1) - Copy files
gvfs-move (1) - Copy files
hcopy (1) - copy files from or to an HFS volume
install (1) - copy files and set attributes
ntfscp (8) - copy file to an NTFS volume.
El programa
man
no es la única forma de consultar las páginas de manual ya que los programas
konqueror
(en KDE) y
yelp
(en GNOME) también ofrecen esta funcionalidad. Existe también una interfaz web provista por el paquete
man2html
que le permite ver las páginas de manual en un navegador web. En un equipo donde esté instalado este paquete, utilice la siguiente URL:
Esta herramienta necesita un servidor web. Es por esto que si debería elegir instalar este paquete en uno de sus servidores: todos los usuarios de la red local se beneficiarán de este servicio (incluyendo máquinas que no tienen Linux) y le evitará tener que configurar un servidor HTTP en cada estación de trabajo. Si puede acceder a su servidor desde otras redes podría desear restringir el acceso a este servicio sólo a los usuarios de la red local.
The GNU project has written manuals for most of its programs in the info format; this is why many manual pages refer to the corresponding info documentation. This format offers some advantages, but the default program to view these documents (it is called info
) is also slightly more complex. You would be well advised to use pinfo
instead (from the pinfo package).
The info documentation has a hierarchical structure, and if you invoke pinfo
without parameters, it will display a list of the nodes available at the first level. Usually, nodes bear the name of the corresponding commands.
With
pinfo
navigating between these nodes is easy to achieve with the arrow keys. Alternatively, you could also use a graphical browser, which is a lot more user-friendly. Again,
konqueror
and
yelp
work; the
info2www
also provides a web interface.
Note that the info system is not suitable for translation, unlike the man
page system. info documents are thus almost always in English. However, when you ask the pinfo
program to display a non-existing info page, it will fall back on the man page by the same name (if it exists), which might be translated.
7.1.3. Documentación específica
Cada paquete incluye su propia documentación. Aún los programas menos documentados generalmente tienen un archivo README
que contiene información interesante y/o importante. Esta documentación se instala en el directorio /usr/share/doc/paquete/
(donde paquete representa el nombre del paquete). Si la documentación es particularmente grande puede no estar incluida en el paquete principal del programa sino que puede haber sido separada a un paquete dedicado que generalmente es llamado paquete-doc
. El paquete principal por lo general recomendará el paquete de documentación para que pueda encontrarlo fácilmente.
El directorio /usr/share/doc/paquete/
también contiene algunos archivos provistos por Debian que completan la documentación especificando las particularidades o mejoras del paquete comparándolo con una instalación tradicional del software. El archivo README.Debian
también indica todas las adaptaciones que se realizaron para cumplir con la Normativa Debian. El archivo changelog.Debian.gz
le permite al usuario seguir las modificaciones realizadas al paquete con el tiempo: es muy útil intentar entender lo que cambió entre dos versiones instaladas que no tienen el mismo comportamiento. Por último, a veces habrá un archivo NEWS.Debian.gz
que documentará los cambios importantes en el programa que podrían interesar al administrador.
In most cases, free software programs have websites that are used to distribute it and to bring together the community of its developers and users. These sites are frequently loaded with relevant information in various forms: official documentation, FAQ (Frequently Asked Questions), mailing list archives, etc. Problems that you may encounter have often already been the subject of many questions; the FAQ or mailing list archives may have a solution for it. A good mastery of search engines will prove immensely valuable to find relevant pages quickly (by restricting the search to the Internet domain or sub-domain dedicated to the program). If the search returns too many pages or if the results do not match what you seek, you can add the keyword debian
to limit results and target relevant information.
If you do not know the address for the software's website, there are various means of getting it. First, check if there is a
Homepage
field in the package's meta-information (
apt-cache show package
). Alternately, the package description may contain a link to the program's official website. If no URL is indicated, look at
/usr/share/doc/package/copyright
. The Debian maintainer generally indicates in this file where they got the program's source code, and this is likely to be the website that you need to find. If at this stage your search is still unfruitful, consult a free software directory, such as FSF's Free Software Directory, or search directly with a search engine, such as Google, DuckDuckGo, Yahoo, etc.
También podría desear revisar el wiki de Debian, un sitio web colaborativo donde cualquiera, inclusive simples visitantes, pueden hacer sugerencias directamente desde sus navegadores. Es utilizado tanto por desarrolladores para diseñar y especificar sus proyectos como por usuarios para compartir su conocimiento escribiendo documentos colaborativamente.
7.1.5. Tutoriales (HOWTO)
Un «howto» es un documento que describe, en términos concretos y paso a paso, «cómo» (en inglés «how to») llegar a un objetivo predefinido. Los objetivos cubiertos son relativamente variados pero generalmente de naturaleza técnica; por ejemplo: configurar «IP Masquerading», instalar un servidor Samba, etc. Estos documentos generalmente intentan cubrir todos los problemas potenciales que podrían ocurrir durante la implementación de una tecnología dada.
Many such tutorials are managed by the Linux Documentation Project (LDP), whose website hosts all of these documents:
Tome estos documentos con un grano de sal. Generalmente tienen varios años; la información que contienen a veces está obsoleta. Este fenómeno es aún más frecuente para sus traducciones ya que las actualizaciones no son ni sistemáticas ni instantáneas luego de la publicación de nuevas versiones de los documentos originales. Esta es parte de la alegría de trabajar en un entorno de voluntarios y sin limitaciones…