È importante conoscere il meccanismo preciso per accedere alle pagine man, per poter dar loro il nome in modo corretto e installarle nel posto giusto. Ogni pagina man andrebbe classificata in una sezione specifica, identificata da un singolo carattere. Le sezioni più comuni utilizzate sotto Linux, insieme ai loro nomi di umana comprensione, sono:
Sezione Nome 1 Comandi dell'utente avviabili da chiunque. 2 Chiamate di sistema, cioè le funzioni fornite dal kernel. 3 Subroutine, ovvero le librerie di funzioni. 4 Dispositivi, ossia i nomi dei file speciali nella directory /dev. 5 Descrizioni di formati dei file, ad esempio /etc/passwd. 6 Giochi (si descrive da sé). 7 Miscellanea, ad esempio i pacchetti di macro e le convenzioni. 8 Strumenti per l'amministrazione di sistema che soltanto il root può eseguire. 9 Un'altra sezione (specifica di Linux) per documentare le routine del kernel. n (Deprecato) Nuova documentazione, da spostare in una sezione più adatta. o (Deprecato) Documentazione obsoleta, da tenere qui solo per un breve periodo. l (Deprecato) Documentazione locale, riguardante questo sistema in particolare. |
Il nome del file sorgente della pagina man (quello di input per il sistema di formattazione) è quello del comando, della funzione o del file, seguito da un punto, seguito dal carattere identificativo della sezione. Se state scrivendo la documentazione riguardante il formato del file `passwd', il file sorgente dovrà chiamarsi `passwd.5'. Questo è anche un caso esemplare in cui il un nome di un file risulta identico al nome di un comando. Potrebbe esistere anche una libreria di subroutine chiamata passwd. La classificazione in sezioni è il modo consueto di risolvere queste ambiguità: la descrizione del comando è trattata nel file `passwd.1', mentre l'ipotetica libreria è descritta in `passwd.3'.
A volte capita di incontrare nomi di file con caratteri terminali aggiuntivi, come in `xterm.1x' o `wish.1tk'; in questo modo si vuol indicare che si tratta di documentazione per un programma di X Window o di un'applicazione Tk, rispettivamente. Qualche visualizzatore delle pagine man può far uso di quest'informazione aggiuntiva. Per esempio, nella lista della documentazione messa a disposizione da xman compariranno le voci `xterm(x)' e `wish(tk)'.
Si prega di non usare le sezioni n, o e l; queste sezioni, conformemente al File System Standard, sono deprecate. Limitatevi alle sezioni numeriche. Si faccia attenzione a non usare nomi di programmi, funzioni o file già esistenti. Se doveste sviluppare un nuovo editor, sarebbe di sicuro una pessima idea quella di chiamarlo ed, sed (volendo intendere "super ed") o red (intendendo "il ritorno di ed"). Assicurandovi l'unicità del nome, eviterete all'utente di eseguire il vostro programma facendogli leggere la pagina man di un altro programma, e viceversa.
Ora che sappiamo il nome da dare al nostro file, la prossima decisione da prendere riguarda la directory in cui installarlo (ad esempio facendo eseguire all'utente il `make install' del vostro pacchetto). Su Linux, tutte le pagine di manuale si trovano all'interno delle directory elencate nella variabile d'ambiente MANPATH. Gli strumenti adibiti al trattamento della documentazione utilizzano MANPATH nello stesso modo in cui una shell utilizza PATH per localizzare gli eseguibili. In effetti, MANPATH ha lo stesso formato di PATH; ognuna di essa contiene un elenco di directory separate da punti e virgole (se si eccettua il fatto che MANPATH non ammette campi vuoti e nomi di percorso relativi, utilizzando solo nomi assoluti). Se MANPATH non è stato impostato o esportato, verrà utilizzato un valore predefinito che conterrà almeno la directory /usr/man. Per velocizzare la ricerca e mantenere snello l'elenco delle directory, le directory indicate in MANPATH (chiamate "directory base") contengono una manciata di sottodirectory chiamate `man<s>' dove <s> sta per il carattere che descrive la sezione introdotta nella tabella precedente. Non tutte le sezioni saranno rappresentate da una sottodirectory semplicemente perché non c'è alcuna ragione di tenere delle sottodirectory vuote. Tuttavia, possono essere presenti alcune sottodirectory di nome `cat<s>', `dvi<s>' e `ps<s>' che contengono documentazione pronta da visualizzare o stampare; di questo parleremo più tardi. L'unico altro file che deve essere presente in qualsiasi directory base è quello chiamato `whatis', di cui tratteremo scopi e preparazione all'uso nel paragrafo 12. Affinché una pagina man della sezione <s> sia collocata con certezza nel posto giusto, basterà copiarla nella directory /usr/man/man<s>. Un buon Makefile, però, permetterà all'utente di scegliersi la propria directory base, per mezzo di una variabile di make, ad esempio MANDIR. La maggior parte dei pacchetti GNU possono essere configurati con l'opzione --prefix=/qualsiasi/dir. I manuali verranno perciò installati all'interno della directory base /qualsiasi/dir. Il mio suggerimento è che venga fornito anche un modo per fare qualcosa di simile.
Con l'avvento del Linux File System Standard (FS-Stnd) le cose sono diventate più complicate. [Nota: Il FS-Stnd sembra esser stato sostituito dal Filesystem Hierarchy Standard, FHS.] Il FS-Stnd 1.2 dichiara che
"La struttura di /usr/man va predisposta per ospitare le pagine di manuale scritte nei vari linguaggi (o con più linguaggi). "
Questo obiettivo può essere raggiunto introducendo un altro livello di directory che distingua tra i diversi linguaggi. Citando ancora dal FS-Stnd 1.2:
"Questa denominazione delle sottodirectory dei linguaggi sotto /usr/man è basata sull'Appendice E dello standard POSIX 1003.1, che descrive la stringa identificativa della localizzazione (si tratta del metodo più accettato per descrivere un ambiente multiculturale o poliglotta). La stringa di localizzazione o <locale> è: <linguaggio>[_<territorio>][.<set-di-caratteri>][,<versione>]"
(Si veda il FS-Stnd per trovare un elenco di stringhe <locale> d'uso frequente). Seguendo queste direttive, le nostre pagine man si troveranno in /usr/man/<locale>/man[1-9lno]. Ovviamente, le versioni formattate dovrebbero di conseguenza trovarsi in /usr/man/<locale>/cat[1-9lno], altrimenti potremmo fornirle soltanto per un'unica localizzazione. TUTTAVIA, per ora mi sento di sconsigliare il passaggio a questa struttura. Il FS-Stnd 1.2, inoltre, permette quanto segue:
"I sistemi che utilizzano un solo linguaggio ed un solo set di codici per tutte le pagine di manuale possono ottere la sottostringa <locale> e conservare tutte le pagine di manuale in <mandir>. Per esempio, i sistemi che hanno solo pagine di manuale in inglese codificate in ASCII possono conservarle direttamente in /usr/man, nelle sottodirectory man[1-9] (di fatto, questo è quel che avviene di solito)" ).
Io non farei il passaggio alla nuova struttura finché tutti gli strumenti (come xman, tkman, info e molte altre che leggono le pagine di manuale) non saranno in grado di farvi fronte.