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. Si deve scrivere semplicemente
man pagina-di-manuale — di solito la pagina di manuale ha lo stesso nome del comando di cui si cerca documentazione. Per esempio, per imparare le possibili opzioni del comando
cp, si scriverà 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 programmi accessibili dalla riga di comando, ma anche i file di configurazione, le chiamate di sistema, le funzioni di libreria, C 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:
comandi eseguibili dalla riga di comando;
chiamate di sistema (funzioni fornite dal kernel);
funzioni di libreria (fornite dalle librerie di sistema);
dispositivi (sui sistemi Unix-like, questi sono file speciali, di solito posti nella directory /dev/);
file di configurazione (formati e convenzioni);
giochi;
insiemi di macro e standard;
comandi di amministrazione del sistema;
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
cpio (1) - copia i file in e da un archivio
gvfs-copy (1) - Copia i file
gvfs-move (1) - Copia i file
hcopy (1) - copia i files da o in un volume HFS
install (1) - copia i file ed imposta gli attributi
ntfscp (8) - copia i file in un volume NTFS.
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:
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.
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.
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ù user-friendly. Ancora, si possono utilizzare
konqueror e
yelp;
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.
Nella maggior parte dei casi, i programmi di software libero hanno dei siti web che sono usati per distribuirli e unire la comunità dei loro sviluppatori e utenti. Questi siti sono spesso pieni di informazioni importanti in varie forme: documentazione ufficiale, FAQ (Frequently Asked Questions, domande poste frequentemente), archivi delle mailing list, ecc.I problemi che si possono incontrare sono spesso già stati oggetto di molte domande; le FAQ o gli archivi delle mailing list potrebbero contenere una soluzione. Una buona padronanza dei motori di ricerca risulterà molto preziosa per trovare rapidamente le pagine di interesse (restringendo la ricerca al dominio o sotto-dominio Internet dedicato al programma). Se la ricerca restituisce troppe pagine o se i risultati non sono attinenti a ciò che si cerca, si può aggiungere la parola chiave debian per limitare i risultati e trovare le informazioni pertinenti.
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.
È anche possibile controllare il wiki di Debian, un sito web collaborativo dove chiunque, anche semplici visitatori, possono dare suggerimenti direttamente dai loro browser. È usato tanto dagli sviluppatori per delineare e specificare i loro progetti, quanto dagli utenti che condividono la loro conoscenza scrivendo documenti in modo collaborativo.
7.1.5. Esercitazioni (HOWTO)
Un howto è un documento che descrive, in termini concreti e passo passo, "come" raggiungere un obiettivo predefinito. Gli obiettivi coperti 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 data tecnologia.
Molte di queste esercitazioni sono gestite dal Linux Documentation Project (LDP), il cui sito web ospita tutti questi documenti:
Questi documenti dovrebbero essere presi con le molle. Sono spesso vecchi di diversi anni; le informazioni che contengono sono a volte obsolete. Questo fenomeno è ancora più frequente per le loro traduzioni, poiché gli aggiornamenti dopo la pubblicazione di una nuova versione dei documenti originali non sono né sistematici né istantanei. Questo fa parte delle gioie di lavorare in un ambiente di volontari e senza vincoli…
