I comandi per la documentazione

()

Benchè talvolta possa risultare difficile trovare informazioni aggiornate sulle funzionalità piu esoteriche, una delle caratteristiche di un sistema GNU/Linux e quella di essere fornito di una quantità impressionante di documentazione

Ciascun comando di norma supporta di suo una opzione –help (spesso abbreviata in -h) che permette di visualizzarne brevemente la sintassi. Dato che questa informazione e in genere solo uno stringato riassunto delle opzioni disponibili, la fonte primaria delle informazioni relative ai comandi e nelle pagine di manuale, n qui abbondantemente citate, gestite con il comando man. Tutti i comandi di sistema prevedono infatti una pagina di manuale cui si accede sempli-cemente con la sintassi man comando. In particolare poi gli sviluppatori di Debian hanno come impegno preciso quello di fornire per ogni pacchetto la relativa documentazione. Ma le pagine di manuale non fanno riferimento solo ai comandi, il sistema infatti ha origine fin dai primi Unix e prevede la documentazione di tutto il sistema.

Per questo le pagine di manuale sono divise in sezioni, il cui numero e quello che compare fra parentesi nella prima riga di ciascuna pagina dopo il nome del comando in maiuscolo. Con man si richiama la pagina di manuale, dove in genere si trova una documentazione esaustiva e dettagliata della sintassi e delle opzioni di un comando o del formato e del signi cato delle direttive di un le di con gurazione. Il comando supporta una serie di opzioni che ne modi cano il comportamento ed altre che consentono di controllare la formattazione per inviare l’output su stampante, al solito tutti i dettagli si trovano nella sua pagina di manuale, alla quale, come per gli altri comandi, si accede con man man

OpzioneSigni cato
  
-amostra tutte le pagine di manuale che corrispondono.
-k strcerca le pagine di manuale che hanno la stringa str nella
 descrizione (equivalente ad apropos).
-f cmdelenca le pagine corrispondenti a cmd (equivalente a whatis).
-wmostra dove e la pagina di manuale, non il suo contenuto.

Si tenga presente che il comando man richiama la pagina relativa al nome che si e passato come argomento, cercando in sequenza nelle varie sezioni e restituendo la prima che trova.

Per questo se esistono piu versioni della stessa pagina in sezioni diverse (come ad esempio per il comando passwd e per il le /etc/passwd) verra mostrata solo la prima, a meno di non aver speci cato l’opzione -a. Se si vuole accedere alla seconda si dovra richiamarla esplicitamente indicando la sezione come primo argomento, con un qualcosa del tipo man 5 passwd.

Il sistema delle pagine di manuale permette comunque di veri care se esistono piu pagine associate ad uno stesso nome con il comando whatis, che stampa l’elenco delle pagine ad esso corrispondenti, cos ad esempio avremo:

piccardi@anarres:~$ whatis passwd

passwd (1)                    – change user password

passwd (5)                    – The password file

Un’altra funzionalit utile del sistema delle pagine di manuale e fornita dal comando apropos che permette di e ettuare la ricerca della parola passata come argomento fra le descrizioni brevi dei comandi che compaiono nella intestazione delle pagine di manuale (quelle appena mostrate anche nell’output di whatis) per cui potremo eseguire la ricerca:

piccardi@anarres:~$ apropos “user password”

chage (1)                      – change user password expiry information

passwd (1)                    – change user password

e si noti come si siano usati i doppi apici per e ettuare una ricerca su una stringa contenente uno spazio, dato che altrimenti si sarebbero passate due stringhe al comando. Come accennato il comando man supporta la possibilita di generare documentazione stam-pabile. Questo avviene perch in realt le pagine di manuale non sono scritte direttamente nel formato in cui le vediamo su video, ma in uno speciale linguaggio di formattazione, chiamato tro , che permette la creazione di sezioni, indici, ecc. Per questo il testo mostrato sul terminale, e solo uno fra i vari formati di uscita disponibili.

Tutte le volte che si richiama il comando man per visualizzare una nuova pagina di manuale il comando dovra recuperare uno di questi le generando un testo in formato opportuno per la visualizzazione. Per evitare di ripetere il procedimento della generazione ad una successiva invocazione tutti questi le vengono salvati, usualmente sotto /var/cache/man/, in una direc-tory catN, dove N corrisponde alla sezione cui appartiene la pagina, cos da poterli recuperare velocemente.

Un secondo aspetto del sistema delle pagine di manuale e quello dell’indicizzazione dei con-tenuti usata dai comandi whatis e apropos; questa infatti non e diretta (come si puo veri care tutte le volte che si installa un nuovo pacchetto e non lo si trova nei risultati di detti comandi), ma viene e ettuata normalmente tramite il programma mandb, che costruisce gli opportuni le con gli indici usati dai precedenti.

In genere il programma viene invocato periodicamente nelle operazioni giornaliere eseguite da cron (vedi sez. 3.2.1), ma lo si puo anche invocare direttamente; le opzioni principali sono -c che gli fa ricreare tutti gli indici da zero (il default e aggiornare quelli esistenti) e -p che non fa eseguire la ripulitura degli indici dei dati della pagine non piu presenti; per la descrizione completa delle altre opzioni ed i dettagli sul comando al solito si faccia riferimento alla sua pagina di manuale.

Per stabilire in quale directory si trovano gli originali delle pagine, in che ordine cercarle, dove devono essere memorizzate le pagine riformattate per la visualizzazione, dove mantenere gli indici delle pagine presenti e delle parole su cui e ettuare le ricerche, il sistema di gestione delle man pages usa il le di con gurazione /etc/manpath.config.

Il primo aspetto della con gurazione e quello della de nizione delle directory in cui si trovano le pagine di manuale; come per gli eseguibili infatti anch’esse possono essere installate in diverse sezioni dell’albero. Si pensi infatti al caso in cui si siano installate diverse versioni di uno stesso pacchetto, ad esempio una versione piu recente a mano sotto /usr/local, in tal caso le pagine di manuale saranno sotto /usr/local/man ed il sistema deve essere in grado di vederle, ed in un certo ordine rispetto alle altre. Una lista di tutte queste directory si puo stampare con il comando manpath, ed in genere si otterra qualcosa del tipo:

piccardi@anarres:~$ manpath

/usr/local/man:/usr/local/share/man:/usr/share/man

a meno di non aver de nito in maniera diretta la variabile di ambiente MANPATH (nel qual caso sar semplicemente stampato il suo valore) che permette di soprassedere il valore preimpostato dal sistema.

La con gurazione delle directory in cui cercare le pagine di manuale e una di quelle impo-stazioni mantenute in manpath.config. La direttiva MANDATORY_MANPATH serve per indicare tutte le directory che si vuole siano sempre aggiunte (se esistono) alla lista di quelle in cui si cercano le pagine di manuale; la direttiva prende come argomento il pathname alla directory contenente gli originali, e deve essere ripetuta per tutte le directory che si vuole siano aggiunte alla lista.

La direttiva MANPATH_MAP indica invece la corrispondenza fra le directory dei comandi e le relative pagine di manuale; serve per aggiornare dinamicamente la lista delle directory in cui cercare le pagine di manuale sulla base delle directory presenti nel PATH (vedi sez. 2.1.3) dell’u-tente. La direttiva richiede due argomenti; il primo indica una directory contenente i comandi, il secondo la directory delle corrispondenti pagine di manuale. Se la prima compare nel PATH dell’utente la seconda e aggiunta al MANPATH in maniera implicita. Infine la direttiva MANDB_MAP serve ad indicare a mandb dove devono essere messi i le degli indici, e dove devono essere create le pagine temporanee. Un estratto del le manpath.config, cos come installato su una Debian Sid, e il seguente:

   manpath.config 
MANDATORY_MANPATH  
/usr/man
MANDATORY_MANPATH/usr/share/man
MANDATORY_MANPATH/usr/local/man
    
MANPATH_MAP/bin/usr/share/man
MANPATH_MAP/usr/bin/usr/share/man
MANPATH_MAP/sbin/usr/share/man
MANPATH_MAP/usr/sbin/usr/share/man
MANPATH_MAP/usr/local/bin/usr/local/man
    
MANDB_MAP/usr/man/var/cache/man/fsstnd
MANDB_MAP/usr/share/man/var/cache/man
MANDB_MAP/usr/local/man/var/cache/man/oldlocal
MANDB_MAP/usr/local/share/man/var/cache/man/local
MANDB_MAP/usr/X11R6/man/var/cache/man/X11R6
MANDB_MAP/opt/man/var/cache/man/opt
    
SECTION1 n l 8 3 2 3posix 3pm 3perl 5 4 9 6 7
     

L’ultima direttiva, SECTION, indica l’ordine di ricerca delle pagine di manuale nelle varie sezioni, si noti come nell’esempio appena citato ci siano altre sezioni oltre a quelle classiche illustrate in tab. 2.38.

Oltre alla consultazione delle pagine di manuale, una seconda fonte di informazioni e docu-mentazione e costituita dal sistema di help on line fornito dal comando info e dalle cosiddette info pages. In questo caso si tratta di una forma alternativa di strutturazione delle informazioni che usa un formato diverso e che aggiunge, rispetto alle pagine di manuale, delle caratteristiche piu avanzate e molto comode come la possibilita di navigare usando link ad altre pagine, una organizzazione gerarchica strutturata ad albero con nodi e sezioni, la possibilita di consulta-re indici, ecc.32 Grazie a questa struttura info permette anche di accedere a documenti piu complessi di una semplice pagina di manuale, e vi si trovano una grande quantit di manuali di grandissima importanza, come documentazione sui sistemi di sviluppo, sui linguaggi, sulle librerie, ecc.

Date le sue caratteristiche evolute info e il formato raccomandato dal progetto GNU, che lo considera alternativo rispetto alle pagine di manuale. Molti pero continuano ad utilizzare quest’ultime per cui alla ne i due sistemi si trovano a convivere. In genere il contenuto delle pagine di manuale e direttamente accessibile anche con il comando info comando, ma usualmente e disponibile anche un’informazione di livello piu alto; ad esempio la documentazione dettagliata dei comandi piu complessi della Unix toolbox, che comprende anche le spiegazioni generali sulla architettura scelta, viene mantenuta nelle pagine info del relativo pacchetto, accessibili con info coreutils.

Se ci si limita a richiamare il comando info ci verra mostrata la radice del sistema dove sono elencati tutti i documenti installati, e sar possibile iniziare la navigazione spostandosi con le frecce, seguire i link premendo invio, tornare al livello precedente premendo \u“, passare al nodo successivo con \n“, tornare al nodo precedente con \p“, andare all’indice con \i“, e ettuare una ricerca con \/“, ed in ne visualizzare i vari comandi disponibili con \?“. La potenza del sistema e che, come per le pagine di manuale, i testi vengono generalmente scritti in un apposito linguaggio di formattazione, per cui la versione testuale e solo una delle possibili forme di visualizzazione, e si puo facilmente accedere alla stessa documentazione anche dall’interfaccia gra ca con gli opportuni programmi di consultazione.

Si tenga presente poi che spesso i pacchetti dei singoli programmi vengono distribuiti con la documentazione prodotta direttamente dagli autori, che di norma, seguendo le indicazioni del Filesystem Hierarchy Standard, viene installata in una directory /usr/share/doc/nomeprogramma. A questa documentazione speci ca poi si aggiunge il patrimonio degli HOWTO, una serie di documenti sul come fare a riguardo di un certo argomento, disponibili in diversi formati (dal testo puro, all’HTML, al PDF).

Questi sono stati raccolti dal Linux Documentation Project (http://www.tldp.org), e di norma vengono installati dalle varie distribuzioni nella directory /usr/share/doc/HOWTO/.

In ne l’utilizzo dei motori di ricerca e un ottimo sistema per recuperare le informazioni pub-blicate su Internet, ed alcuni di essi forniscono anche un accesso speci co per ricerche su questo argomento. Fra queste troverete le versioni pubblicate degli HOWTO (anche se queste vengono spesso distribuite come documentazione nel sistema, non e detto che siano complete o aggior-nate) ma anche altre risorse come le annotazioni ed i log, le istruzioni lasciati in innumerevoli pagine web e gli archivi delle liste di discussione dei vari progetti in cui qualcuno puo aver gia avuto il vostro problema e trovato una risposta.

/ 5
Grazie per aver votato!

How useful was this post?

Click on a star to rate it!

Average rating / 5. Vote count:

No votes so far! Be the first to rate this post.

As you found this post useful...

Follow us on social media!

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?