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, provided by the
man-db package. 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).
Man pages not only document commands and programs accessible from the command line, but also configuration files, system calls, library functions, and so forth. Sometimes names can collide. For example, the shell's read
command has the same name as the read
system call. This is why manual pages are organized in numbered sections:
- 1
órdenes que pueden ser ejecutadas desde la línea de órdenes;
- 2
llamadas de sistema (funciones proporcionadas por el núcleo);
- 3
funciones de biblioteca (proporcionadas por las bibliotecas del sistema);
- 4
dispositivos (en Unix éstos son archivos especiales generalmente ubicados en el directorio /dev/
);
- 5
archivos de configuración (formatos y convenciones);
- 6
juegos;
- 7
conjuntos de «macros» y estándares;
- 8
órdenes de administración del sistema;
- 9
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
hpcopy (1) - copy files from an HFS+ volume
install (1) - copy files and set attributes
ntfscp (8) - copy file to an NTFS volume.
The
man
command is not the only means of consulting the manual pages, since
khelpcenter
and
konqueror
(by KDE) and
yelp
(under GNOME) programs also offer this possibility. There is also a web interface, provided by the
man2html
package, which allows you to view manual pages in a web browser. On a computer where this package is installed, use this URL after following the instructions in
/usr/share/doc/man2html/README.Debian
:
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.
Last but not least, you can view all manual pages available in Debian (even those that are not installed on your machine) on the
manpages.debian.org
service. It offers each manual page in multiple versions, one for each Debian release.
El proyecto GNU escribió manuales para la mayoría de sus programas en el formato info; es por esto que muchas páginas de manual hacen referencia a la documentación info correspondiente. El formato tiene ciertas ventajas, pero el programa por defecto para visualizar estos documentos (llamado info
) es también ligeramente más complejo. En vez de éste se le recomienda usar pinfo
(del paquete pinfo).
La documentación info tiene una estructura jerárquica y si ejecuta pinfo
sin parámetros mostrará una lista de los nodos disponibles en el primer nivel. Generalmente los nodos tienen el nombre del programa correspondiente.
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
package also provides a web interface.
Note que el sistema info, a diferencia del sistea de páginas man
, no permite traducciones. Los documentos info estarán, por lo tanto, siempre en inglés. Sin embargo, cuando le pida a pinfo
una página info que no exista, éste buscará la página de man con el mismo nombre (si es que existe) y ésta puede que sí esté traducida.
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.
The
/usr/share/doc/package/
directory also contains some files provided by Debian which complete the documentation by specifying the package's particularities or improvements compared to a traditional installation of the software. The
README.Debian
file also indicates all of the adaptations that were made to comply with the Debian Policy. The
changelog.Debian.gz
file allows the user to follow the modifications made to the package over time: it is very useful to try to understand what has changed between two installed versions that do not have the same behavior. Finally, there is sometimes a
NEWS.Debian.gz
file which documents the major changes in the program that may directly concern the administrator (see
Sección 6.7.2, “Manejo de problemas tras una actualización”).
En la mayoría de los casos, los programas de software libre tienen sitios web que se utilizan para distribuirlo y reunir la comunidad de desarrolladores y usuarios. Estos sitios generalmente están llenos de información relevante en varias formas: documentación oficial, preguntas frecuentes (FAQ: «Frequently Asked Questions»), archivos de listas de correo, etc. Los problemas que podría tener ya han sido objeto de varias preguntas; los FAQ o los archivos de las listas de correos pueden tener una solución. Dominar los motores de búsqueda será de gran valor para encontrar las páginas relevantes rápidamente (restringiendo la búsqueda al dominio o subdominio de Internet dedicado al programa). Si la búsqueda devuelve demasiados resultados o éstos no coinciden con lo que desea, puede agregar la palabra clave debian
para limitar los resultados y obtener información relevante.
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 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.
You might also want to check the Debian wiki, a collaborative website where anybody, even simple visitors, can make suggestions directly from their browsers. It is used equally by developers who design and specify their projects, and by users who share their knowledge by writing documents collaboratively.
7.1.5. Tutoriales (HOWTO)
A HOWTO is a document that describes, in concrete terms and step by step, “how to” reach a predefined goal. The covered goals are relatively varied, but often technical in nature: for example, setting up IP Masquerading, configuring software RAID, installing a Samba server, etc. These documents often attempt to cover all of the potential problems likely to occur during the implementation of a given technology.
Many such tutorials are managed by the Linux Documentation Project (LDP), whose website hosts all of these documents:
Debian also provides tutorials for its users:
All these documents should be taken with a grain of salt. They are often several years old; the information they contain is sometimes obsolete. This phenomenon is even more frequent for their translations, since updates are neither systematic nor instant after the publication of a new version of the original documents. Further many tutorials nowadays are provided by bloggers, sharing their individual solution with the interested reader. They often lack important information, i.e. the reason why some configuration has been chosen over another, or why some option has been enabled or disabled. Because blogging and creating own websites made it so easy to share, many of these often short tutorials exist, but only a few are actively maintained and well-kept. This can make it hard, to find the "right" one for you. This is all part of the joys of working in a volunteer environment and without constraints…