[inizio] [indice generale] [precedente] [successivo] [indice analitico] [contributi]


18. Documentazione

Esistono diverse fonti di documentazione su GNU/Linux. La maggior parte di questa è normalmente disponibile all'interno delle distribuzioni, ma la consultazione può risultare un problema per chi non ha esperienza.

18.1 Testo puro

Il modo più semplice con cui può essere stato scritto qualcosa è quello del testo puro. Questo è il caso dei file «leggimi» (readme) e simili, oppure di tutta quella documentazione che, per semplicità, è stata convertita anche in questo formato.

La lettura di questi file può essere fatta attraverso due programmi ben conosciuti: `more' oppure `less'. `more' è quello tradizionalmente più diffuso negli ambienti Unix; `less' è il più pratico ed è decisamente più ricco di piccoli accorgimenti. Le funzionalità essenziali di questi due programmi sono simili, anche se il secondo offrirebbe un gran numero di funzioni aggiuntive che qui non vengono considerate.

La sintassi di questi due programmi è la seguente:

more [<opzioni>] [<file>]...

less [<opzioni>] [<file>]...

Nell'utilizzo normale non vengono fornite opzioni e se non viene indicato alcun file negli argomenti, viene fatto lo scorrimento di quanto ottenuto dallo standard input.

Una volta avviato uno di questi due programmi, lo scorrimento del testo dei file da visualizzare avviene per mezzo di comandi impartiti attraverso la pressione di tasti. Il meccanismo è simile a quello utilizzato da VI: alcuni comandi richiedono semplicemente la pressione di uno o più tasti in sequenza; altri richiedono un argomento e in questo caso, la digitazione appare nell'ultima riga dello schermo o della finestra a disposizione. La tabella 18.1 mostra l'elenco dei comandi comuni ed essenziali di questi due programmi.

Comando Descrizione
h Richiama una breve guida dei comandi disponibili.
H Come `h'.
Spazio Scorre il testo in avanti di una schermata.
Invio Scorre il testo in avanti di una riga alla volta.
b Quando possibile, scorre il testo all'indietro di una schermata.
/<modello> Esegue una ricerca in avanti, in base all'espressione regolare indicata.
n Ripete l'ultimo comando di ricerca.
Ctrl+l Ripete la visualizzazione della schermata attuale.
q Termina l'esecuzione del programma.
Q Come `q'.

Tabella 18.1: Elenco dei comandi comuni ed essenziali di `more' e `less'.

La differenza fondamentale tra questi due programmi sta nella possibilità da parte di `less' di scorrere il testo all'indietro anche quando questo proviene dallo standard input, mentre per `more' non è possibile. `less' permette inoltre di utilizzare i tasti freccia e i tasti pagina per lo scorrimento del testo, e di effettuare ricerche all'indietro. La tabella 18.2 mostra l'elenco di alcuni comandi aggiuntivi disponibili con `less'.

Comando Descrizione
y Scorre il testo all'indietro di una riga alla volta.
?<modello> Esegue una ricerca all'indietro, in base all'espressione regolare indicata.
N Ripete l'ultimo comando di ricerca nella direzione inversa.

Tabella 18.2: Elenco di alcuni comandi particolari di `less'.

Esempi

ls -l | more

ls -l | less

Scorre sullo schermo l'elenco del contenuto della directory corrente che probabilmente è troppo lungo per essere visualizzato senza l'aiuto di uno tra questi due programmi.

more README

less README

Scorre sullo schermo il contenuto del file `README'.

`less' è un programma che permette un utilizzo molto più complesso di quanto descritto qui, ma questo va oltre l'uso che se ne fa normalmente.

18.1.1 Variabile LESSCHARSET

Il programma `less' è sensibile al contenuto della variabile di ambiente `LESSCHARSET': se questa contiene la stringa `latin1', consente la visualizzazione corretta di caratteri e simboli speciali che vanno oltre la codifica ASCII pura e semplice.

18.2 Pagine di guida

Quasi tutti i programmi sono accompagnati da una pagina di manuale, ovvero man page. Si tratta di un documento stringato sull'uso di quel programma particolare, scritto in uno stile abbastanza uniforme.

Si distinguono diverse sezioni di queste pagine di manuale, a seconda del genere di informazioni in esse contenute. Può infatti accadere che esistano più pagine con lo stesso nome, appartenenti però a sezioni diverse. La tabella 18.3 riporta l'elenco di queste sezioni.

Sezione Contenuto
1 comandi utente
2 chiamate di sistema
3 chiamate di libreria
4 dispositivi
5 formati dei file
6 giochi
7 varie
8 comandi di sistema
9 routine del kernel

Tabella 18.3: Sezioni delle pagine di manuale.

Quando si vuole fare riferimento a una pagina di manuale, se ne indica il nome seguito da un numero tra parentesi, che ne esprime la sezione. Per cui, man(1) indica la pagina di manuale di nome `man' nella prima sezione. Spesso, nella documentazione, si fa riferimento ai programmi in questo modo, per dare istantaneamente l'informazione di dove raggiungere le notizie che riguardano quel programma particolare.

Questa documentazione viene consultata normalmente attraverso il programma `man' che a sua volta, solitamente, si avvale di `less', oppure `more', per scorrere il documento. La tabella 18.1 mostra l'elenco dei comandi comuni essenziali di questi due programmi.

18.2.1 Collocazione fisica e nazionalizzazioni

Le pagine di manuale possono trovarsi in diverse posizioni all'interno del filesystem.

Queste directory sono tutte suddivise o suddivisibili nello stesso modo. Si indicherà una qualsiasi di queste directory di partenza come <mandir>.

La collocazione effettiva dei file che costituiscono le pagine di manuale è nelle directory esprimibili nella forma seguente:

<mandir>[/<locale>]/man<sezione>[/<architettura>]

Ciò significa che, oltre alle directory <mandir> già viste, esiste un'altra directory, <locale>, eventuale, che poi si scompone in diverse sottodirectory in funzione delle sezioni delle pagine di manuale esistenti (di solito da `man1/' a `man9/'), e ognuna di queste può articolarsi ulteriormente in funzione delle differenze tra un'architettura e l'altra.

La directory <locale> è facoltativa, nel senso che spesso manca. Può essere utilizzata per distinguere tra le pagine di manuale di diverse lingue o di diversi formati. Il nome di questa directory è stabilito dallo standard POSIX 1003.1 secondo la sintassi seguente:

<linguaggio>[_<territorio>][.<insieme-di-caratteri>][,<versione>]

Nel caso delle pagine di manuale in italiano, queste, ammesso che siano disponibili, dovrebbero trovarsi nelle directory `<mandir>/it_IT/man<sezione>'. In pratica, non si usa l'indicazione dell'insieme di caratteri perché si sottintende `ISO-8859-1'. Per fare in modo però che queste directory vengano utilizzate effettivamente, è necessario che la variabile di ambiente `LANG' contenga il valore `it_IT'.

Anche la directory che definisce l'architettura è facoltativa ed è necessaria solo quando in una determinata sezione esistono pagine di manuale riferite a programmi o altre informazioni dipendenti da particolari caratteristiche architetturali.

18.2.2 /etc/man.config

Il comportamento di `man' può essere configurato attraverso il file `/etc/man.manconfig'. Tra le tante cose, questo file contiene gli argomenti da fornire ai programmi utilizzati per la formattazione del testo da visualizzare o da stampare. Si osservi l'estratto seguente:

TROFF		/usr/bin/groff -Tps -mandoc
NROFF		/usr/bin/groff -Tlatin1 -mandoc
EQN		/usr/bin/geqn -Tps
NEQN		/usr/bin/geqn -Tlatin1
TBL		/usr/bin/gtbl
# COL		/usr/bin/col
REFER		/usr/bin/grefer
PIC		/usr/bin/gpic
VGRIND		
GRAP		
PAGER		/usr/bin/less -is
CAT		/bin/cat

Una cosa che conviene modificare, se non fosse già impostata correttamente, è l'opzione `-T' di `groff' e di `geqn'. Utilizzandola nel modo che si vede nell'esempio (`-Tlatin1'), serve a consentire la visualizzazione dei caratteri accentati delle pagine di manuale tradotte in italiano.

18.2.3 $ man

man [<opzioni>] <nome>...

L'eseguibile `man' formatta ed emette attraverso lo standard output la pagina di manuale indicata dal nome. Lo scorrimento del testo che compone le pagine di manuale indicate negli argomenti viene fatto attraverso un programma esterno, richiamato automaticamente da `man'. Solitamente si tratta di `more' o di `less'. Di conseguenza, i comandi per lo scorrimento del testo dipendono dal tipo di programma utilizzato. Se si tratta di uno di questi due appena citati, sono sempre validi almeno quelli riportati nella tabella 18.1.

Alcune opzioni

<numero-di-sezione>

Se prima del nome del comando o dell'argomento appare un numero, si intende che si vuole ottenere la pagina di manuale da una sezione determinata, come riportato nella tabella 18.3.

-f

Si comporta come `whatis'.

-h

Visualizza una breve guida di se stesso.

-k

Equivalente a `apropos'.

Esempi

man ls

Visualizza la pagina di manuale del programma `ls'.

man 8 lilo

Visualizza la pagina di manuale dell'ottava sezione, del programma `lilo'.

18.2.4 $ whatis

whatis <parola>...

Cerca all'interno degli elenchi whatis una o più parole intere. Questi elenchi sono dei file con lo stesso nome (`whatis') contenenti una breve descrizione dei comandi di sistema e collocati nelle varie directory <mandir>. Il risultato della ricerca viene emesso attraverso lo standard output. Sono visualizzate solo le corrispondenze con parole intere. I file `whatis' vengono rigenerati utilizzando il programma `makewhatis' (di solito viene fatto fare al sistema Cron).

Esempi

whatis ls

Visualizza le righe degli elenchi whatis contenenti la parola `ls'.

18.2.5 $ apropos

apropos <stringa>...

Cerca all'interno degli elenchi whatis una o più stringhe. `apropos' esegue la ricerca negli stessi file utilizzati da `whatis'. Il risultato della ricerca viene emesso attraverso lo standard output. A differenza di `whatis', sono visualizzate tutte le corrispondenze.

Esempi

apropos keyboard

Visualizza le righe degli elenchi whatis contenenti la stringa `keyboard'.

18.2.6 # makewhatis

makewhatis [<opzioni>]

Crea o aggiorna gli elenchi whatis del sistema di pagine di manuale. In pratica, crea un file con il nome `whatis' all'interno di ogni directory <mandir> contenente la prima riga di ogni pagina di manuale. Viene utilizzato dai programmi `whatis' e `apropos' per effettuare delle ricerche sommarie all'interno di questo elenco.

18.3 Info

La documentazione Info è un ipertesto realizzato dai file Info e leggibile attraverso il programma `info' oppure all'interno di Emacs. I file di questo ipertesto si trovano nella directory `/usr/share/info/'.

La documentazione Info è organizzata in file contenenti dei nodi. Ogni nodo ha un nome e rappresenta un'unità di informazioni. Trattandosi di un sistema ipertestuale, ogni nodo può avere riferimenti ad altri nodi contenenti informazioni aggiuntive o collegate. Quasi tutti i nodi contengono almeno dei riferimenti standard definiti dalle voci seguenti:

Gli altri riferimenti possono essere organizzati in forma di menu o di riferimenti incrociati (cross-reference). Ogni file Info contiene almeno un nodo principale: `Top'. I nodi vengono identificati formalmente secondo la notazione seguente:

[(<file-info>)][<nome-del-nodo>]

Se si indica solo il nome del nodo, si fa implicitamente riferimento al file utilizzato in quel momento determinato; se si indica solo il nome del file, si fa implicitamente riferimento al nodo `Top'.

18.3.1 $ info

info [<opzioni>] [<voce>...]

L'eseguibile `info' consente di consultare i file Info senza l'ausilio di Emacs. Se non viene indicato alcun argomento, in particolare, se non viene indicato il file Info da consultare, viene aperto il file `/usr/share/info/dir'.

Alcune opzioni

--directory <percorso>

Specifica un percorso aggiuntivo all'interno del quale possono essere cercati i file Info.

-f <file> | --file=<file>

Specifica un file particolare da visitare.

-n <nodo> | --node=<nodo>

Specifica un nodo particolare da visitare.

Esempi

info -f pippo

Inizia la visualizzazione del file `pippo' a partire dal suo nodo principale.

info -f pippo pappa

Seleziona la voce di menu `pappa' che dovrebbe essere contenuta nel nodo principale del file `pippo'.

info -f info

Inizia la visualizzazione del file `info' a partire dal suo nodo principale.

info info

Seleziona la voce di menu `info' dal nodo principale del file `dir' (`/usr/share/info/dir') che è quello predefinito.

18.3.2 Utilizzo del sistema attraverso l'eseguibile info

Per poter leggere le informazioni contenute in questi file attraverso l'eseguibile `info', occorre conoscere alcuni comandi che non sono necessariamente intuitivi. Questi comandi si impartiscono semplicemente premendo il tasto della lettera o del simbolo corrispondente. Alcuni di questi comandi richiedono degli argomenti, in tal caso si è costretti a inserirli e a farli seguire da [Invio]. I comandi più importanti sono riportati nella tabella 18.4.

Comando Descrizione
h Visualizza la guida del programma `info'.
? Visualizza l'elenco dei comandi disponibili.
d Visualizza il file `dir'.
q Termina l'esecuzione del programma.
Ctrl+g Interrompe il comando in corso di digitazione.
Ctrl+l Ripristina l'immagine sullo schermo.
l Ritorna al nodo selezionato precedentemente.

Tabella 18.4: Elenco dei comandi principali di `info'.

Quando si usa un ipertesto è molto importante conoscere il modo con cui si può ritornare sui propri passi. In questo caso, il comando `l' permette di tornare indietro, ed è particolarmente utile dopo la selezione di un comando di aiuto come `h' o `?'.

La figura 18.1 mostra il nodo principale del file `info', cioè del documento che spiega il funzionamento di questo tipo di ipertesto.

File: info,  Node: Top,  Next: Getting Started,  Prev: (dir),  Up: (dir)

Info: An Introduction
*********************

   Info is a program for reading documentation, which you are using now.

   To learn how to use Info, type the command `h'.  It brings you to a
programmed instruction sequence.  If at any time you are ready to stop
using Info, type `q'.

   To learn advanced Info commands, type `n' twice.  This brings you to
`Info for Experts', skipping over the `Getting Started' chapter.

* Menu:

* Getting Started::             Getting started using an Info reader.
* Advanced Info::               Advanced commands within Info.
* Create an Info File::         How to make your own Info file.

--zz-Info: (info.gz)Top, 20 lines --All----------------------------------------
Welcome to Info version 2.18. "C-h" for help, "m" for menu item.

Figura 18.1: La guida all'uso della documentazione Info.

La prima riga, quella che appare in alto, contiene in particolare il nome del file e del nodo.

File: info, Node: Top,  Next: Getting Started,  Prev: (dir), Up: (dir)

La penultima riga, la seconda dal basso, riporta ancora il nome del file e del nodo, oltre alla dimensione del nodo in righe e alla parola `All'.

--zz-Info: (info.gz)Top, 20 lines --All-------------------------------

La parola `All' indica in questo caso che il nodo appare completamente nello spazio a disposizione sullo schermo o nella finestra. L'ultima riga dello schermo viene usata per dare informazioni all'utilizzatore e come spazio per l'inserimento di argomenti quando i comandi ne richiedono.

Sulla parte iniziale di ogni nodo, insieme al nome del file e del nodo stesso, sono riportati alcuni riferimenti standard (ad altri nodi). Sono rappresentati simbolicamente dai termini `Next' (successivo), `Prev' (precedente) e `Up' (superiore). Chi ha redatto il file Info ha definito quali debbano essere effettivamente i nodi a cui queste voci si riferiscono e a questi si accede utilizzando i comandi `n', `p' e `u', rispettivamente.

Comando Descrizione
n Visualizza il nodo successivo.
p Visualizza il nodo precedente.
u Visualizza il nodo superiore.

Tabella 18.5: Elenco dei comandi per la navigazione attraverso i riferimenti standard.

Il riferimento `Up' non corrisponde necessariamente al nodo principale (`Top') del file che si sta consultando, ma a quello che in quel momento, per qualche motivo, rappresenta un riferimento principale. Lo stesso tipo di ragionamento vale per i riferimenti `Next' e `Prev' che sono solo una sequenza di massima.

Il testo di un nodo può essere più lungo delle righe a disposizione sullo schermo o nella finestra. Per scorrere il testo si utilizza la barra spaziatrice per avanzare e il tasto [Canc] per indietreggiare. È però necessario fare attenzione: se si eccede si prosegue su altri nodi, attraverso un percorso predefinito che solitamente non coincide con i riferimenti `Next' e `Prev' già visti.

Comando Descrizione
Spazio Scorre in avanti.
Canc Scorre all'indietro.
b Visualizza l'inizio del nodo.

Tabella 18.6: Elenco dei comandi per lo scorrimento naturale del documento.

L'utilità di un ipertesto sta nella possibilità di raggiungere le informazioni desiderate seguendo un percorso non sequenziale. I documenti Info utilizzano due tipi di riferimenti (oltre a quelli standard): i menu e i riferimenti incrociati. I primi si distinguono perché sono evidenziati dalla sigla `* Menu:' seguita da un elenco di riferimenti; sono cioè staccati dal testo normale. I riferimenti incrociati appaiono invece all'interno del testo normale e sono evidenziati dalla sigla `* Note Cross:'.

Le voci di menu possono essere selezionate attraverso il comando `m' seguito dal nome del nodo; le voci dei riferimenti incrociati possono essere selezionate attraverso il comando `f' seguito dal nome del nodo.

L'utilità di avere due comandi diversi sta nel fatto che questi nomi possono essere indicati in forma abbreviata (per troncamento), indicando solo quello che serve per distinguerli dagli altri. Distinguendo i riferimenti raggruppati in menu, rispetto a quelli che appaiono nel testo, si riducono le possibilità di equivoci.

Comando Descrizione
m <nodo> Richiama un nodo tra quelli indicati nel menu.
f <nodo> Richiama un nodo tra quelli indicati nei riferimenti incrociati.
g <nodo> Richiama un nodo qualunque.
Tab Sposta il cursore sul prossimo riferimento disponibile.
Invio Seleziona il nodo corrispondente al riferimento su cui si trova il cursore.

Tabella 18.7: Elenco dei comandi per la selezione dei riferimenti.

Per facilitare la selezione dei riferimenti che appaiono nel testo di un nodo (menu inclusi), si può utilizzare il tasto [Tab] per posizionare il cursore all'inizio della prossima voce, e il tasto [Invio] per selezionare il nodo a cui fa riferimento la voce su cui si trova il cursore.

Se si conosce esattamente il nome di un nodo che si vuole raggiungere, si può utilizzare il comando `g' seguito dal nome del nodo stesso.

Quando si naviga all'interno della documentazione Info è sempre bene tenere a mente il comando `l' che permette di ritornare al nodo attraversato precedentemente.

Comando Descrizione
s <stringa> Cercare all'interno del file Info la stringa indicata.
Alt+x print-node Invia alla stampa il nodo visualizzato sullo schermo.

Tabella 18.8: Altri comandi utili.

18.4 Documentazione allegata ai pacchetti

I pacchetti di programmi più importanti sono accompagnati da documentazione scritta in vario modo (testo, LaTeX, TeX, SGML, PostScript, ecc.). Questa si trova collocata normalmente in sottodirectory discendenti da `/usr/doc/'.

18.5 HOWTO

I documenti HOWTO non accompagnano i pacchetti di programmi come loro parte integrante, essendo delle guide aggiuntive con scopi che vanno oltre la semplice documentazione del funzionamento di un solo pacchetto particolare. La maggior parte delle distribuzioni GNU/Linux include anche i file di documentazione HOWTO. Solitamente, questi vengono installati al di sotto della directory `/usr/doc/HOWTO/'.

18.6 FAQ

Un'altra fonte di documentazione su GNU/Linux sono le cosiddette FAQ o Frequently Asked Questions. Si tratta di informazioni disordinate in forma di botta e risposta. Solitamente si trovano al di sotto della directory `/usr/doc/FAQ/'. *1*

18.7 LDP

A fianco della documentazione standard fornita più o meno con tutte le distribuzioni GNU/Linux, ci sono dei libri veri e propri disponibili liberamente. Questi sono raccolti all'interno del progetto LDP, o Linux Documentation Project.

Questi documenti, normalmente disponibili sia in PostScript che in HTML, sono raggiungibili a partire da http://metalab.unc.edu/pub/Linux/docs/LDP/ e dai siti speculari relativi.

18.8 Altra documentazione

Oltre alla documentazione citata nelle sezioni precedenti, esistono altri documenti che possono essere ritrovati a partire da http://metalab.unc.edu/pub/Linux/docs/ e dai siti speculari relativi.

Inoltre, la documentazione in italiano è consistente e può essere ottenuta dagli FTP dei vari gruppi italiani che si occupano di GNU/Linux. In particolare ftp://ftp.pluto.linux.it/pub/pluto/ildp/ e i suoi siti speculari.

Meritano particolare attenzione i riferimenti seguenti.

---------------------------

Appunti Linux 2000.04.12 --- Copyright © 1997-2000 Daniele Giacomini --  daniele @ pluto.linux.it


1.) In italiano qualcuno usa la definizione «filza di assilli quotidiani».


[inizio] [indice generale] [precedente] [successivo] [indice analitico] [contributi]