Linux Certif

Toute la documentation sur la certification Linux LPI

man

NOME

man - macro per formattare le pagine di manuale

SINTASSI

groff -Tascii -man file ...

groff -Tlatin1 -man file ...

groff -Tps -man file ...

man [sezione] titolo

DESCRIZIONE

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 rileverà automaticamente quale pacchetto macro è in uso.

PREAMBOLO

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 della sezione in cui la pagina di guida dovrebbe essere posta (per es. 7).

data

La data dell'ultima revisione --- si ricordi di aggiornarla ogni volta che viene fatta una modifica alla pagina di manuale, essendo questo il metodo più semplice 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 a cui si fa riferimento: 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.

CARATTERI

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 nomi dei file 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 riferimento ad altre pagine di manuale (o all'argomento dell'attuale pagina di manuale) è in grassetto. Se il numero della sezione del manuale è dato, è indicato 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. Le virgolette doppie 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.

SEZIONI

Le sezioni iniziano con .SH seguito dal nome dell'intestazione. Se il nome contiene spazi e appaiono nella stessa riga di .SH, allora si ponga l'intestazione tra 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 immediatamente 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 che segue 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

Altre macro comprendono quanto segue:

.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

FILE

/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

VEDERE ANCHE

groff(1), man(1), whatis(1), apropos(1), makewhatis(8)