Cominciamo con un esempio che verrà descritto nel dettaglio più avanti; se lo leggete come testo puro non mostrerà i caratteri in maniera differente a seconda della loro formattazione (grassetto e corsivo). Per avere ulteriori informazioni si faccia riferimento al paragrafo "Quali sono le convenzioni sui font?". Ma ora veniamo alla pagina di manuale relativa al programma (ipotetico) foo.
FOO(1) Manuale Utente FOO(1)
NOME
foo - sentarbinisce la libreria zac
SINTASSI
foo [-bar] [-c file-config ] file ...
DESCRIZIONE
foo sentarbinisce la libreria zac sminestrando nelle tabelle
interne dei simboli; per default parserizza tutti i segmenti
baz e li risistema in ordine inverso di tempo per mezzo del
linker xyzzy(1), per sottoporli a ricerca. Successivamente
viene compresso l'elemento symdef utilizzando l'algoritmo
WBG (Whiz-Bang-Gizmo). Tutti i file vengono elaborati nel-
l'ordine indicato.
OPZIONI
-b In fase di elaborazione non scrive `busy' sullo stdout.
-c file-config
Usa il file di configurazione alternativo file-config
invece di /etc/foo.conf. Ciò comporta l'annullamento
della variabile d'ambiente FOOCONF.
-a Oltre ai segmenti baz, vengono parserizzati anche gli
header blurfl.
-r Modalità ricorsiva. Opera alla velocità della luce, al
costo di un megabyte di memoria virtuale.
FILE
/etc/foo.conf
Il file di configurazione generale. Per altri dettagli
si veda foo(5).
~/.foorc
File di configurazione personale dell'utente. Per altri
dettagli si veda foo(5).
AMBIENTE
FOOCONF
Se impostata è il nome del percorso completo di un file
di configurazione alternativo a foo.conf. È annullata
dall'opzione -c.
DIAGNOSTICA
I seguenti messaggi diagnostici possono essere inviati su
stderr:
Magic number sconosciuto.
Il file di input non sembra essere un file d'archivio
valido.
Segmenti baz di vecchio formato.
foo può gestire solo i segmenti baz di nuovo formato.
Le librerie di oggetti COBOL non sono supportate in
questa versione.
BUG
Il nome del comando dovrebbe essere scelto facendo maggiore
attenzione al suo scopo.
AUTORE
Jens Schweikhardt <howto at schweikhardt dot net>
VEDERE ANCHE
bar(1), foo(5), xyzzy(1)
Linux MARZO 1995 2
|
Come promesso, ecco la spiegazione delle voci di sezione.
La sezione NOME
...è la sola sezione obbligatoria. Le pagine man senza una sezione del nome sono utili quanto un congelatore al polo nord. Questa sezione ha anche un formato standard che consiste di un elenco di nomi di programmi o funzioni separati da virgole, seguita da un trattino, seguito a sua volta da una breve descrizione (su una sola riga, di solito) della funzionalità che il programma (o la funzione, o il file) è in grado di fornire. Per mezzo di makewhatis(8), le sezioni del nome vengono inserite nel database dei file di whatis. L'uso di makewhatis è il motivo della necessità della sezione NOME; tale sezione, dunque deve esistere ed aderire al formato descritto. Il sorgente in formato groff deve apparire così:
.SH NOME foo \- sentarbinisce la libreria zac
La sequenza \- è importante: la barra rovesciata (o backslash) è necessaria a distinguere il trattino da quello della suddivisione in sillabe che può comparire sia nel nome del comando che nella descrizione disposta su una riga.
La sezione SINTASSI
...ha lo scopo di fornire una breve panoramica sulle opzioni messe a disposizione dal programma. Per quel che riguarda le funzioni, questa sezione elenca i corrispondenti file di include e il prototipo, così da informare il programmatore in merito al tipo degli argomenti di input, al loro numero e al tipo dei dati restituiti.
La sezione DESCRIZIONE
...descrive in maniera eloquente il motivo per cui la vostra sequenza di 0 e 1 valga la pena di essere usata. Questo è il posto in cui scrivere la vostra conoscenza. Questa è la Sala delle Celebrità: potrete guadagnarvi l'ammirazione degli altri programmatori ed utenti facendo di questa sezione la fonte di informazioni dettagliate e affidabili. Qui, tra le altre cose, potete descrivere l'utilizzo degli argomenti, il formato dei file e quali sono gli algoritmi delle operazioni critiche.
La sezione OPZIONI
...dà una descrizione di come ogni opzione influenza il comportamento del programma. Ma questo già si sapeva, no?
La sezione FILE
...elenca i file usati dal programma o dalla funzione; per esempio, può elencare i file di configurazione, quelli di avvio e quelli su cui il programma interviene direttamente in scrittura. È buona cosa fornire il percorso completo di questi file e permettere che il processo di installazione possa modificare parte della directory per soddisfare le preferenze dell'utente: i manuali di groff hanno un prefisso predefinito pari a /usr/local, cosicché faranno riferimento per default a /usr/local/lib/groff/*. Invece, se si installa usando 'make prefix=/opt/gnu', il riferimento nella pagina man diventa /opt/gnu/lib/groff/*
La sezione AMBIENTE
...elenca tutte le variabili d'ambiente che influenzano il programma o la funzione (descrivendo anche le modalità di quest'interazione, ovviamente). La maggior parte delle variabili contiene nomi di percorso, nomi di file o opzioni di default.
La sezione DIAGNOSTICA
...dovrebbe dare una panoramica dei messaggi d'errore emessi più comunemente dal vostro programma e come venirne a capo. Non c'è alcuna necessità di descrivere i messaggi d'errore di sistema (descritti in perror(3)) o i segnali d'errore fatale (descritti in psignal(3)) che dovessero comparire durante l'esecuzione, in quanto sono descritti a parte e riguardano l'esecuzione di qualsiasi programma.
La sezione BUG
...non dovrebbe esistere, in un mondo ideale. Qui, se siete intrepidi, potrete descrivere le limitazioni, i problemi noti e quelle che voi vedete come funzionalità ma che altri potrebbero interpretare come complicazioni inutili. Se invece non avete questo coraggio, cambiate il nome di questa sezione in TO DO ;-)
La sezione AUTORE
...è molto utile nel caso in cui ci siano errori grossolani nella documentazione o nel comportamento del programma (Bzzt!) e volete inviare una segnalazione del problema incontrato.
La sezione VEDERE ANCHE
...è un elenco di pagine man correlate alla presente, elencate in ordine alfabetico. Per convenzione, questa è l'ultima sezione. Se le sezioni disponibili fossero insufficienti a descrivere il contenuto che volete fornire siete liberi di inventarne altre. Per concludere: come si può generare questa pagina man? Mi aspettavo questa domanda: ecco il sorgente:
.\" Processa questo file con il comando .\" groff -man -Tascii foo.1 .\" .TH FOO 1 "MARZO 1995" Linux "Manuale Utente" .SH NOME foo \- sentarbinisce la libreria zac .SH SINTASSI .B foo [-bar] [-c .I file-config .B ] .I file .B ... .SH DESCRIZIONE .B foo sentarbinisce la libreria zac sminestrando nelle tabelle interne dei simboli; per default parserizza tutti i segmenti baz e li risistema in ordine inverso di tempo per mezzo del linker .BR xyzzy (1), per sottoporli a ricerca. Successivamente viene compresso l'elemento symdef utilizzando l'algoritmo WBG (Whiz-Bang-Gizmo). Tutti i file vengono elaborati nell'ordine indicato. .SH OPZIONI .IP -b In fase di elaborazione non scrive `busy' sullo stdout. .IP "-c file-config" Usa il file di configurazione alternativo .I file-config invece di .IR /etc/foo.conf . Ciò comporta l'annullamento della variabile d'ambiente .BR FOOCONF . .IP -a Oltre ai segmenti baz, vengono parserizzati anche gli header blurfl. .IP -r Modalità ricorsiva. Opera alla velocità della luce, al costo di un megabyte di memoria virtuale. .SH FILE .I /etc/foo.conf .RS Il file di configurazione generale. Per altri dettagli si veda .BR foo (5). .RE .I ~/.foorc .RS File di configurazione specifico dell'utente. Per altri dettagli si veda .BR foo (5). .SH AMBIENTE .IP FOOCONF Se impostata è il nome del percorso completo di un file di configurazione alternativo a .IR foo.conf . È annullata dall'opzione .BR -c . .SH DIAGNOSTICA I seguenti messaggi diagnostici possono essere inviati su stderr: Magic number sconosciuto. .RS Il file di input non sembra essere un file d'archivio valido. .RE Segmenti baz di vecchio formato. .RS .B foo può gestire solo i segmenti baz di nuovo formato. Le librerie di oggetti COBOL non sono supportate in questa versione. .SH BUG Il nome del comando dovrebbe essere scelto facendo maggiore attenzione al suo scopo. .SH AUTORE Jens Schweikhardt <howto at schweikhardt dot net> .SH "VEDERE ANCHE" .BR bar (1), .BR foo (5), .BR xyzzy (1) |