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.
Las páginas de manual, aunque de estilo escueto, contienen gran cantidad de información esencial. Repasaremos rápidamente el programa para verlas, proporcionado por el paquete
man-db. Simplemente ejecute
man página_de_manual — la página de manual generalmente tiene el mismo nombre que el programa sobre el que busca documentación. Por ejemplo, para aprender sobre las opciones posibles de
cp utilizaría
man cp en una terminal (revise el recuadro
VOLVER A LOS CIMIENTOS La consola, un intérprete de línea de órdenes).
Las páginas de manual no sólo documentan órdenes y programas en la línea de órdenes, también archivos de configuración, llamadas de sistema, funciones de bibliotecas 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:
- 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
cp (1posix) - copy files
cpio (1) - copy files to and from archives
exec (1posix) - execute commands and open, close, or copy file descriptors
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
khelpcenter y
konqueror (de 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 después de seguir las instrucciones en
/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.
Por último, pero no menos importante, puede ver todas las páginas de manual disponibles en Debian (incluso aquellas que no están instaladas en su máquina) en el servicio
manpages.debian.org. Ofrece cada página de manual en múltiples versiones, una para cada publicación de Debian.
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.
En la orden
pinfo la navegación se controla con las teclas del cursos. Puede utilizar, alternativamente, un navegador gráfico que es mucho más amigable. Nuevamente,
konqueror y
yelp funcionan; el paquete
info2www también provee una interfaz web.
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.
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 (véase
Sección 6.7.2, “Manejo de problemas tras una actualización”).
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.
Si no conoce la dirección del sitio web del software hay varias formas de obtenerla. Primero, revise si hay un campo
Homepage entre la metainformación del paquete (
apt show paquete). La descripción del paquete también podría contener un enlace al sitio oficial del programa. Si no se indica una URL, revise
/usr/share/doc/paquete/copyright. El desarrollador Debian generalmente indica en este archivo de dónde obtuvo el código fuente del programa y es probable que sea el sitio web que busca. Si en esta etapa de su búsqueda aún no obtuvo resultados, consulte un directorio de software libre como el Directorio de Software Libre de la FSF o busque directamente con un motor de búsqueda como DuckDuckGo, Yahoo, etc.
You might also want to check the Debian wiki, a collaborative website where anybody, even new 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)
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:
Debian también ofrece tutoriales a sus usuarios:
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 personal 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…
