|
MAN(7) manual page
Table of Contents
man - macro per formattare le pagine di manuale
groff -Tascii
-man file ...
groff -Tps -man file ...
man [sezione] titolo
Questa
pagina spiega il pacchetto di macro groff tmac.an. Questo pacchetto di macro
dovrebbe essere usato dagli sviluppatori quando scrivono o portano le
pagine di guida per Linux. È abbastanza compatibile con altre versioni
di questi pacchetti di macro, quindi portare le pagine di guida non dovrebbe
essere un grosso problema (ad eccezione della release BSD di NET-2, che
usa un pacchetto di macro completamente differente).
Si Osservi che le
pagine di guida NST-2 BSD possono essere usate con groff semplicemente
specificando l'opzione -mdoc invece dell'opzione -man. Usare l'opzione -mandoc
è, comunque, raccomandato, in quando automaticamente rileverà quale pacchetto
macro è in uso.
Il primo comando in una pagina di manuale dovrebbe
essere
.TH titolo sezione data sorgente manuale,
dove:
- titolo
- Il
titolo della pagina di manuale (per es. MAN).
- sezione
- Il numero di sezione
in cui la pagina di guida dovrebbe essere posta (per es. 7).
- data
- La data
dell'ultima revisione--ci si ricordi di cambiare questa ogni volta che viene
fatta una modifica alla pagina di manuale, essendo questo il metodo più
generale per eseguire il controllo della versione.
- sorgente
- La sorgente
del comando.
Per file binari, si usi qualcosa tipo: GNU, NET-2, SLS Distribution,
MCC Distribution.
Per chiamate di sistema, si usi la versione del kernel
viene documenta: Linux 0.99.11.
Per chiamate di libreria, si usi la fonte
della funzione: GNU, BSD 4.3, Linux DLL 4.4.1.
- manuale
- Il titolo del manuale
(es. Linux Programmer's Manual).
Le sezioni del manuale sono tradizionalmente
definite così:
- 1 Comandi utente
- Quei comandi che possono essere eseguiti
dall'utente all'interno di una shell.
- 2 Chiamate di sistema
- Quelle funzioni
che sono di competenza del kernel.
- 3 Chiamate di libreria
- Molte delle
funzioni libc, come sort(3)
).
- 4 File speciali
- File che si trovano in /dev).
- 5 Formati dei file e convenzioni
- Il formato di /etc/passwd e altri file
leggibili dall'utente.
- 6 Giochi
- 7 Pacchetti di macro e convenzioni
- Una
descrizione dell'aspetto standard del file system, questa pagina di manuale
e altre cose.
- 8 Comandi di amministrazione del sistema
- Comandi tipo mount(8)
,
che solo root può eseguire.
- 9 Routine del kernel
- Questa è una sezione
non standard del manuale ed è inclusa perché il codice sorgente del kernel
di Linux è liberamente distribuibile sotto la Licenza Pubblica GNU e molta
gente lavora sulle modifiche al kernel.
Sebbene ci siano molte
convenzioni arbitrarie per le pagine di guida nel mondo UNIX, l'esistenza
di diverse centinaia di pagine di guida specifiche per Linux definisce
i nostri standard:
- Per le funzioni, gli argomenti sono sempre specificati
usando il corsivo,
- anche nella sezione SINTASSI, dove il resto della
funzione è specificato in grassetto:
int myfunction(int argc, char **argv);
- I filename sono sempre in corsivo (per es.
- /usr/include/stdio.h), eccetto
nella sezione SINTASSI, dove i file include sono in grassetto (es. #include
<stdio.h>).
- Macro speciali, che sono generalmente in maiuscolo, sono in grassetto
(es.
- MAXINT).
- Nel enumerare una lista di codici di errore, i codici sono
in grassetto
- (questa lista generalmente usa la macro .TP).
- Ogni riferenza
ad altre pagine di manuale (o all'argomento dell'attuale
- pagina di manuale)
è in grassetto. Se il numero della sezione del manuale è dato, è dato in
tondo, senza nessuno spazio (per es. man(7)
).
I comandi per selezionare
il tipo di carattere sono i seguenti:
- .B
- Grassetto
- .BI
- Grassetto alternato
a corsivo
- .BR
- Grassetto alternato a tondo
- .I
- Corsivo
- .IB
- Corsivo alternato
a grassetto
- .IR
- Corsivo alternato a tondo
- .RB
- Tondo alternato a grassetto
- .RI
- Tondo alternato a corsivo
- .SB
- Piccolo alternato a grassetto
- .SM
- Piccolo
Tradizionalmente, ogni comando può avere fino a sei argomenti, ma la versione
GNU sembra aver rimosso questa limitazione. Gli argomenti sono delimitati
da spazi. Doppie virgolette possono essere usate per specificare un argomento
che contiene spazi. Tutti gli argomenti verranno stampati uno vicino all'altro
senza spazi, così il comando .BR può essere usato per specificare una parola
in grassetto seguita da un punto in tondo.
Le sezioni iniziano
con .SH seguito dal nome dell'intestazione. Se il nome contiene spazi e appaiono
nella stessa lina di .SH, allora si ponga l'intestazione in virgolette doppie.
Tradizionalmente le intestazioni comprendono: NOME, SINTASSI, DESCRIZIONE,
OPZIONI, FILE, VEDERE ANCHE, DIAGNOSTICA, BACHI e AUTORE. La sola intestazione
obbligatoria è NOME, che dovrebbe essere seguita sulla riga successiva
da una riga descrittiva del programma:
.SH NOME
chess \- il gioco degli
scacchi
È estremamente importante che questo formato sia rispettato,
e che ci sia una barra inversa prima del trattino singolo seguente il
nome del comando. Questa sintassi è usata dal programma makewhatis(8)
per
creare un database di brevi descrizioni di comandi per i programmi whatis(1)
e apropos(1)
.
Altre macro comprendono i seguenti:
- .DT
- Tabulazione
normale
- .HP
- Inizia il testo rientrato
- .IP
- Inizia un paragrafo con etichetta
evidenziata. Questo è lo stesso di .TP, eccetto che l'etichetta è messa nella
stessa riga, non nella seguente.
- .LP
- Lo stesso di .PP
- .PD
- Imposta la distaza
tra paragrafi all'argomento
- .PP
- Inizia un nuovo paragrafo
- .RE
- Termina un
rientro relativo (paragrafo rientrato)
- .RS
- Inizia un rientro relativo
(paragrafo rientrato)
- .SS
- Sottosezione (tipo .SH, ma usata per una sottosezione)
- .TP
- Inizia un paragrafo con etichetta evidenziata. L'etichetta è data nella
riga successiva. Questo comando è simile a .IP
/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis
groff(1)
, man(1)
, whatis(1)
, apropos(1)
,
makewhatis(8)
Table of Contents
|
