Prima di comprendere cosa sta relamente succedendo quando c'è un problema, bisogna conoscere il ruolo teorico giocato da ciascun programma coinvolto nel problema. Per fare questo, per avere la migliore visione si deve consultare la loro documentazione; ma dal momento che queste documentazioni molte e posso essere sparse in lungo e in largo, si dovrebbero conoscere tutti i posti in cui si potrebbero trovare.
Le pagine di manuale, sebbene relativamente laconiche, contengono una grande quantità di informazioni importanti. Daremo una rapida occhiata al comando per vederle fornito dal pacchetto
man-db. Si deve scrivere semplicemente
man pagina-di-manuale — di solito la pagina di manuale ha lo stesso nome del comando di cui si cerca la documentazione. Per esempio, per conoscere le possibili opzioni del comando
cp, digitare il comando
man cp al prompt di shell (vedere il riquadro
FONDAMENTALI La shell, un interprete a riga di comando).
Le pagine di manuale non documentano solo i comandi ed i programmi accessibili dalla riga di comando, ma anche i file di configurazione, le chiamate di sistema, le funzioni di libreria e così via. A volte alcuni nomi possono collidere. Per esempio, il comando read della shell ha lo stesso nome della chiamata di sistema read. Per questo le pagine di manuale sono organizzate in sezioni numerate:
- 1
comandi eseguibili dalla riga di comando;
- 2
chiamate di sistema (funzioni fornite dal kernel);
- 3
funzioni di libreria (fornite dalle librerie di sistema);
- 4
dispositivi (sui sistemi Unix-like, questi sono file speciali, di solito posti nella directory /dev/);
- 5
file di configurazione (formati e convenzioni);
- 6
giochi;
- 7
insiemi di macro e standard;
- 8
comandi di amministrazione del sistema;
- 9
routine del kernel.
È possibile specificare la sezione della pagina di manuale che si sta cercando: per vedere la documentazione della chiamata di sistema read, si scriverà man 2 read. Quando non è esplicitamente specificata una sezione, verrà mostrata la prima sezione che ha una pagina di manuale col nome richiesto. Perciò, man shadow restituirà shadow(5) perché non ci sono pagine di manuale per shadow nelle sezioni da 1 a 4.
Ovviamente, se non si conoscono i nomi dei comandi, il manuale non sarà molto utile. Per questo scopo c'è il comando apropos, che aiuta a cercare all'interno delle pagine di manuale, o più precisamente nelle loro descrizioni brevi. Ogni pagina di manuale comincia in pratica con un riassunto di una riga. apropos, restituisce una lista di pagine di manuale che menzionano le parole chiave richieste. Con una scelta oculata, si può trovare il nome del comando che serve.
Esempio 7.1. Trovare 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.
Il comando
man non è l'unico modo di consultare le pagine di manuale; infatti, anche
khelpcenter,
konqueror (in KDE) e
yelp (in GNOME) offrono questa possibilità. Esiste anche un'interfaccia web, fornita dal pacchetto
man2html, che permette di vedere le pagine di manuale in un browser web. In un computer in cui è installato questo pacchetto, si può usare questo URL dopo aver seguito le istruzioni in
/usr/share/doc/man2html/README.Debian:
Questa utilità richiede un server web. Per questo si dovrebbe installare questo pacchetto su uno dei propri server: tutti gli utenti della rete locale potrebbero beneficiare di questo servizio (comprese macchine non Linux) e così non si è obbligati a installare un server HTTP su ogni macchina. Se il proprio server è accessibile anche da altre reti, potrebbe essere opportuno restringere l'accesso a questo servizio solo agli utenti della rete locale.
Ultimo ma non meno importante, è possibile visualizzare tutte le pagine manuali disponibili in Debian (anche quelle che non sono installate sul computer) su
manpages.debian.org. Esso offre ogni pagina di manuale in più versioni, una per ogni versione Debian.
Il progetto GNU ha scritto manuali per la maggior parte dei suoi programmi in formato info; per questo motivo molte pagine di manuale rimandano alla corrispondente documentazione info. Questo formato offre alcuni vantaggi, ma il programma predefinito per visualizzare questi documenti (è chiamato info) è anche leggermente più complesso. Si farebbe bene ad usare invece pinfo (dal pacchetto pinfo).
La documentazione info ha una struttura gerarchica e se si invoca info senza parametri, verrà mostrata una lista dei nodi disponibili al primo livello. Di solito, i nodi riportano i nomi dei comandi corrispondenti.
Con
pinfo è facile effettuare la navigazione tra questi nodi utilizzando i tasti freccia. In alternativa, è anche possibile utilizzare un browser grafico, che è molto più intuitivo. Inoltre, si possono utilizzare
konqueror e
yelp; il pacchetto
info2www fornisce anche un'interfaccia web.
Notare che il sistema info non permette traduzioni, al contrario del sistema di pagine man. Perciò i documenti info sono quasi sempre in Inglese. Tuttavia, quando si chiede al programma pinfo di visualizzare una pagina info non esistente, questo ricadrà sulla pagina man con lo stesso nome (se esiste), che potrebbe essere stata tradotta.
7.1.3. Documentazione specifica
Ogni pacchetto include la propria documentazione. Anche i programmi meno documentati in generale hanno un file README che contiene informazioni interessanti o importanti. Questa documentazione è installata nella directory /usr/share/doc/pacchetto/ (dove pacchetto rappresenta il nome del pacchetto). Se la documentazione è particolarmente grande, potrebbe non essere inclusa nel pacchetto principale del programma, ma piuttosto separata in un pacchetto dedicato che di solito di chiama pacchetto-doc. Di solito il pacchetto principale raccomanda il pacchetto con la documentazione, dimodoché è facile trovarla.
Nella directory
/usr/share/doc/pacchetto/ ci sono inoltre alcuni file forniti da Debian che completano la documentazione specificando le peculiarità del pacchetto o dei miglioramenti rispetto a un'installazione tradizionale del software. Il file
README.Debian indica inoltre tutti gli adattamenti fatti per aderire alla Policy di Debian. Il file
changelog.Debian.gz permette all'utente di seguire le modifiche fatte al pacchetto nel tempo: è molto utile per cercare di capire cos'è cambiato fra due versioni installate che non hanno lo stesso comportamento. Infine, a volte è presente un file
NEWS.Debian.gz che documenta i principali cambiamenti al programma che possono interessare direttamente l'amministratore (vedere
Sezione 6.7.2, «Gestire i problemi dopo un aggiornamento»).
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.
Se non si conosce l'indirizzo del sito web del software, ci sono diversi modi per ottenerlo. Prima di tutto, controllare se esiste un campo
Homepage nelle meta-informazioni del pacchetto (
apt show pacchetto). In alternativa, la descrizione del pacchetto potrebbe contenere un collegamento al sito web ufficiale del programma. Se non è indicato alcun URL, cercare nel file
/usr/share/doc/pacchetto/copyright. Il manutentore Debian, di solito, indica in questo file dove è stato preso il codice sorgente del programma ed è probabile che questo sia il sito web cercato. Qualora la ricerca sia ancora infruttuosa, consultare una directory di software libero, come la Free Software Directory di FSF, oppure utilizzando direttamente un motore di ricerca, come Google, DuckDuckGo, Yahoo, ecc.
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. Esercitazioni (HOWTO)
Un HOWTO è un documento che descrive, in termini concreti e passo dopo passo, "come" raggiungere un obiettivo predefinito. Gli obiettivi trattati sono abbastanza variegati, ma spesso di natura tecnica: per esempio, impostare il mascheramento degli IP, configurare un RAID software, installare un server Samba ecc. Questi documenti spesso cercano di coprire tutti i potenziali problemi che potrebbero verificarsi durante l'implementazione di una determinata tecnologia.
Many such tutorials are managed by the Linux Documentation Project (
LDP), whose website hosts all of these documents:
Debian fornisce anche tutorial per i suoi utenti:
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…
