Provided by:
manpages-it_0.3.4-5_all 
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 illustra il pacchetto di macro groff tmac.an (spesso
chiamato man) e relative convenzioni usate nella creazione di pagine di
manuale. Questo pacchetto di macro dovrebbe essere usato dagli
sviluppatori quando scrivono o portano le pagine di manuale per Linux.
È abbastanza compatibile con altre versioni di questi pacchetti di
macro, quindi portare le pagine di manuale non dovrebbe essere un
grosso problema (un’eccezione è NET-2 BSD, che usa un pacchetto di
macro completamente differente chiamato mdoc; si veda mdoc(7)).
Si osservi che le pagine di manuale NET-2 BSD, in formato mdoc, 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 (dopo le righe di commento)
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 manuale
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 Programmers
Manual).
Si noti che le pagine formattate con l’mdoc di BSD iniziano col comando
Dd invece che col comando TH.
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 qsort(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,
protocolli di rete, codici ASCII e altri, questa
pagina di manuale e altre cose.
8 Comandi di amministrazione del sistema
Comandi tipo mount(8), molti dei quali eseguibili solo
da root.
9 Routine del kernel
Questa sezione è obsoleta: una volta si credeva che
sarebbe stata una buona idea includere qui la
documentazione del kernel di Linux, ma in realtà
pochissimo è stato documentato, e quel poco è già
obsoleto. Gli sviluppatori del kernel hanno a
disposizioni fonti migliori d’informazione.
SEZIONI
Le sezioni incominciano con un .SH seguito dall’intestazione; se questa
contiene spazi e compare sulla stessa riga del .SH, allora la si
inserisca fra virgolette doppie. Le intestazioni tradizionali o
consigliate sono, tra le altre: NOME, SINTASSI, DESCRIZIONE, VALORE DI
RITORNO (o VALORI DI RITORNO), STATO D’USCITA, GESTIONE DEGLI ERRORI,
ERRORI, OPZIONI, USO, FILE, AMBIENTE, DIAGNOSTICA, SICUREZZA, CONFORME
A, NOTE, BACHI, AUTORE e VEDERE ANCHE [NdT si consulti la pagina
originale per i corrispondenti termini inglesi]. Nei casi in cui
un’intestazione tradizionale è adatta, per favore, la si usi: questo
tipo di coerenza facilita la comprensione delle informazioni. In ogni
caso, si è liberi di creare le proprie se questo facilita la
comprensione delle cose. L’unica intestazione obbligatoria è NOME, che
dovrebbe segnare la prima sezione ed essere seguita, sulla riga
successiva, da una descrizione monoriga del programma:
.SH NOME
chess \- il gioco degli scacchi
È molto importante che questo formato venga seguito e che ci sia una
barra inversa prima del trattino singolo che segue il nome del comando:
questa sintassi viene usata da makewhatis(8) per creare un database di
brevi descrizioni dei comandi per whatis(1) e apropos(1) [NdT Il
makewhatis incluso in man a partire dalla versione 1.5g sa riconoscere
l’intestazione italiana NOME oltre a quella inglese].
Altre sezioni classiche hanno i seguenti contenuti:
SINTASSI descrive brevemente l’interfaccia del comando o della
funzione. Nel primo caso, mostra la sintassi e gli
argomenti del comando (opzioni incluse); il grassetto è
usato per il testo verbatim e il corsivo per gli
argomenti sostituibili. Parentesi quadre «[]» circondano
gli argomenti opzionali, sbarre verticali «|» separano le
scelte e i puntini di sospensione «...» possono essere
ripetuti. Nel caso delle funzioni, mostra ogni
dichiarazione obbligatoria dei dati o direttive di
#include, seguiti dalla dichiarazione della funzione.
DESCRIZIONE dà una spiegazione di quello che il comando, funzione o
formato fa. Si discuta delle interazioni coi file e con
lo standard input, e i risultati prodotti su standard
output o standard error. Si trascurino i dettagli
interni e d’implementazione, a meno che siano necessari
alla comprensione dell’interfaccia. Si descrivano i casi
comuni; le informazioni sulle opzioni vanno nella sezione
OPZIONI. Se c’è un qualche tipo di grammatica d’ingresso
o un insieme complesso di sottocomandi, potrebbe essere
meglio descriverli in una sezione USO separata, e
lasciare solo una panoramica nella sezione DESCRIZIONE.
VALORI DI RITORNO
dà un elenco di valori restituiti dal programma o dalla
routine di libreria al chiamante, e le condizioni che
causano queste restituzioni.
STATO D’USCITA
elenca i possibili valori dello stato di uscita di un
programma e le condizioni che causano questi valori
(alcune pagine di manuale usano VALORI DI RITORNO al
posto di STATO D’USCITA: va ugualmente bene).
OPZIONI descrive le opzioni accettate dal programma e le
modifiche che inducono al suo comportamento.
USO descrive la grammatica di ogni sottolinguaggio
implementato.
FILE elenca i file, come file di configurazione, file di avvio
o file su cui il programma opera direttamente, utilizzati
dal programma o funzione. Si dia l’intero percorso di
questi file e si utilizzino le procedure d’installazione
per modificare il nome delle directory secondo la
preferenza dell’utente [NdT Essendo ciò chiaramente
impossibile nel caso di una traduzione distribuita
separatamente, si usi il percorso specificato dagli
standard, o quello usato nelle distribuzioni più comuni].
Per molti programmi, il sito predefinito d’installazione
è /usr/local, per cui la pagina di manuale di base
dovrebbe usare /usr/local come base.
AMBIENTE elenca tutte le variabili ambientali che influenzano il
programma o la funzione e il modo in cui l’influenza si
attua.
DIAGNOSTICA dà una panoramica dei messaggi d’errore più comuni [NdT
Ovviamente, se questi sono stati già tradotti in
italiano, si usino le traduzioni preesistenti. Se non c’è
una traduzione è probabilmente meglio lasciare il testo
in inglese; oppure offrirsi volontari per tradurre tutti
i messaggi del programma] e come affrontarli. Non c’è
bisogno di spiegare messaggi d’errore di sistema o
segnali fatali che possano apparire durante l’esecuzione
del programma, a meno che ricoprano un ruolo speciale
rispetto al programma in questione.
SICUREZZA discute i problemi di sicurezza e le loro implicazioni.
Avvisa quali sono le configurazioni o gli ambienti che
dovrebbero essere evitati, i comandi che potrebbero avere
effetti sulla sicurezza e altro, soprattutto se non
ovvio. Non è necessario discutere della sicurezza in una
sezione a parte: se facilita la comprensione, le
informazioni in merito possono apparire in altre sezioni
(come DESCRIZIONE o USO). In ogni caso, le informazioni
sulla sicurezza devono apparire da qualche parte!
CONFORME A descrive tutti gli standard o convenzioni implementate.
NOTE fornisce annotazioni varie.
BACHI elenca i limiti, i difetti o gl’inconvenienti noti e
altre attività dubbie.
AUTORE elenca l’autore (o gli autori) della documentazione o del
programma, onde potergli segnalare eventuali bachi [NdT
Il nome del traduttore, di norma, appare nei commenti
della pagina; i problemi di traduzione vanno chiaramente
segnalati a lui e a nessun altro].
VEDERE ANCHE elenca, in ordine alfabetico, pagine di manuale
correlate, possibilmente seguite da altre pagine o
documentazioni in merito. Per convenzione, questa è
l’ultima sezione.
CARATTERI
Sebbene ci siano molte convenzioni arbitrarie per le pagine di manuale
nel mondo UNIX, l’esistenza di diverse centinaia di pagine specifiche
per Linux definisce i nostri standard per i caratteri:
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 d’include sono in grassetto (es. #include <stdio.h>).
Macro speciali, che sono generalmente in maiuscole, sono in
grassetto (es. MAXINT).
Nell’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:
.B Grassetto
.BI Grassetto alternato a corsivo (molto utile nelle specifiche di una
funzione)
.BR Grassetto alternato a tondo (molto utile nelle referenze verso
altre pagine)
.I Corsivo
.IB Corsivo alternato a grassetto
.IR Corsivo alternato a tondo
.RB Tondo alternato a grassetto
.RI Tondo alternato a corsivo
.SB Maiuscoletto alternato a grassetto
.SM Maiuscoletto (utile per gli acronimi)
Tradizionalmente, ogni comando può avere fino a sei argomenti, ma la
versione GNU rimuove questa limitazione (in ogni caso, ha senso
limitarsi a sei argomenti per compatibilità). 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. Se nessun argomento è presente, il comando si applica
alla riga di testo seguente.
ALTRE MACRO E STRINGHE
Seguono altre macro importanti e stringhe predefinite; a meno che sia
specificato diversamente, ogni macro causa un’andata a capo. Molte di
queste macro impostano o usano il «rientro principale»: il suo valore
viene impostato da ognuna delle seguenti macro grazie al parametro r;
le macro possono omettere la r, nel qual caso viene usato il rientro
principale corrente. Come risultato, dei paragrafi rientrati che si
susseguano possono usare lo stesso rientro senza rispecificare il
valore di rientro. Un paragrafo normale (cioè non rientrato) reimposta
il rientro principale al suo valore predefinito (mezzo pollice). A
priori, il rientro si misura in quadratini; è meglio utilizzare
quadratini (en) e quadratoni (em) come unità perché queste si adattano
automaticamente al cambiamento di dimensione dei caratteri. Ulteriori
definizioni di macro importanti sono:
Paragrafi normali
.LP Lo stesso di .PP (incomincia un nuovo paragrafo).
.P Lo stesso di .PP (incomincia un nuovo paragrafo).
.PP Incomincia un nuovo paragrafo e reimposta il rientro
principale.
Rientro relativo del margine
.RS r Incomincia un rientro relativo del margine; sposta di r il
margine sinistro verso destra (se r è omessa, viene usato il
rientro principale). Un nuovo rientro principale viene
impostato a mezzo pollice; di conseguenza, tutti i paragrafi
seguenti vengono rientrati fino al corrispondente .RE.
.RE Termina il rientro relativo del margine e ripristina il valore
precedente del rientro principale.
Macro per paragrafi rientrati
.HP r Incomincia il paragrafo con un rientro a bandiera (la prima
riga del paragrafo inizia al margine sinistro dei paragrafi
normali mentre il resto delle righe del paragrafo è
rientrato).
.IP x r Incomincia il paragrafo con un’etichetta opzionale a bandiera.
Se l’etichetta x è omessa, l’intero paragrafo seguente è
rientrato di r; se l’etichetta x è presente, viene allineata
al margine sinistro prima del paragrafo, rientrato, seguente
(è la stessa cosa di .TP tranne per il fatto che l’etichetta è
inclusa nel comando invece di starsene per conto suo sulla
riga successiva). Se l’etichetta è troppo lunga, il testo che
la segue viene spostato alla riga seguente (e non viene né
perso né impiastricciato). Per gli elenchi puntati, si usi
questa macro con \(bu (bullet, cioè pallino) o \(em (em dash,
cioè trattino lungo) come etichetta; per gli elenchi numerati,
si usi il numero o la lettera seguiti da un punto come
etichetta: ciò semplifica la conversione verso altri formati.
.TP r Incomincia il paragrafo con un’etichetta a bandiera:
l’etichetta è nella riga seguente, ma il risultato è lo stesso
del comando .IP.
Macro per referenze ipertestuali
.UR u Incomincia una referenza ipertestuale verso l’URI (URL) u, che
termina col corrispondente comando UE. Generando HTML, questo
dovrebbe essere reso nel comando HTML <A HREF="u">. C’è
un’eccezione: se u è il valore speciale «:», allora nessun
tipo di referenza ipertestuale viene generata fino al
corrispondente UE (questo permette di disabilitare le
referenze ipertestuali in frasi come LALR(1) dove dare una
referenza non sarebbe appropriato). Queste «macro» per
referenze ipertestuali sono nuove e molti strumenti non
sapranno cosa farsene, ma considerando che molti strumenti
(troff incluso) ignorano tranquillamente le macro indefinite
(o, al peggio, inseriscono il loro testo), le si possono
inserire senza problemi.
.UE Termina il comando UR corrispondente; generando HTML, questo
dovrebbe essere reso come </A>.
.UN u Crea un’etichetta ipertestuale col nome u; non include il
comando UE corrispondente. Generando HTML, questo dovrebbe
essere reso nel comando HTML <A NAME="u" id="u"> </A> (il
è opzionale se non si richiede la compatibilità con
Mosaic).
Macro varie
.DT Reimposta la tabulazione al valore predefinito (ogni mezzo
pollice); non manda a capo.
.IX ... Inserisce informazioni d’indicizzazione (per un sistema di
ricerca o per un indice vero e proprio); l’informazione
d’indicizzazione non è di norma mostrata nella pagina in sé.
Se è seguita da un parametro solo, questo viene aggiunto come
voce d’indicizzazione autonoma che punti alla posizione nella
pagina di manuale. Se ci sono due parametri, probabilmente si
tratta del formato di Perl per le manpagine: il primo
parametro identifica il tipo di nome (uno fra nome titolo
intestazione sottosezione o voce) ed il secondo parametro il
nome da indicizzare. Altrimenti, abbiamo il formato lungo
d’indice: ciascun parametro dà un termine d’indicizzazione, un
termine subordinato, un termine subsubordinato e così via fino
ad un parametro vuoto finale, poi c’è un parametro col nome
del programma, \em e una breve descrizione; eventualmente
seguita da un altro parametro vuoto e magari anche da un
messaggio per controllare l’impaginazione (tipo PAGE START).
Un esempio di tutto ciò potrebbe essere "strumenti di
programmazione" "make" "" "\fLmake\fP \(em costruisce
programmi".
.PD d Imposta la distanza verticale fra paragrafi a d (se manca,
d=0.4v); non va a capo.
.SS t Sottosezione t (come .SH, ma usato per una sottosezione
all’interno di una sezione).
Stringhe predefinite
Il pacchetto man include le seguenti stringhe predefinite
\*R Registrato: ®
\*S Ritorna alla dimensione predefinita dei caratteri
\*(Tm Marchio di fabbrica: ™
\*(lq Virgolette inglesi di sinistra: “
\*(rq Virgolette inglesi di destra: ”
SOTTOINSIEME DI SICUREZZA
Per quanto man sia tecnicamente un pacchetto di macro di troff, in
realtà ci sono moltissimi altri strumenti che elaborano pagine di
manuale e che non implementano tutte le capacità di troff. Perciò, se
possibile, è meglio evitare alcune delle abilità più esotiche di troff
onde permettere agli altri strumenti di operare correttamente. Si
evitino i vari preprocessori per troff (se proprio si deve, va bene
usare tbl(1), anche se sarebbe meglio usare IP e TP per tabelle a due
colonne). Si evitino i calcoli, poiché la maggior parte degli altri
strumenti non può elaborarli. Si adoperino comandi semplici che possano
essere resi facilmente in altri formati. Si può supporre che le
seguenti macro di troff siano sicure (anche se in molti casi vengono
ignorate nella conversione): \", ., ad, bp, br, ce, de, ds, el, ie, if,
fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.
Si possono usare anche molte delle sequenze di escape di troff (quelle
incomincianti per \): se c’è bisogno di includere la barra inversa come
testo ordinario, si usi \e; altre sequenze che si possono usare sono
\’, \‘, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, \f(xx,
dove x o xx sono un carattere qualsiasi e N una cifra qualsiasi. Si
evitino le sequenze di escape per disegnare grafici.
Non si usi il parametro opzionale a bp (break-page, cioè nuova pagina).
Si usino solo valori positivi per sp (spazio verticale). Non si
ridefinisca una macro (de) con lo stesso nome di una macro in questo
pacchetto o in mdoc e con un significato diverso: quasi sicuramente la
ridefinizione verrà ignorata. Ogni rientro positivo (in) deve essere
accoppiato con un rientro negativo corrispondente (anche se, invece,
bisognerebbe usare le macro RS e RE). I test condizionali (if,ie)
dovrebbero avere come uniche condizioni «t» e «n». Solo le
translitterazioni (tr) che possono essere ignorate dovrebbero essere
usate. I cambi di carattere (ft e le sequenze \f di escape) dovrebbero
assumere unicamente i valori 1, 2, 3, 4, R, I, B, P e CW (il comando ft
potrebbe anche essere privo di parametri).
Se vengono usate ulteriori abilità di troff, bisognerebbe controllarne
attentamente i risultati con diversi strumenti: dopo essersi assicurati
che queste ulteriori abilità sono sicure, lo si faccia sapere al
responsabile di questo documento, perché vengano aggiunte all’elenco.
NOTE
In ogni modo, si cerchi di includere URL (o URI) intere nel testo
stesso: alcuni strumenti come man2html(1) possono convertirle
automaticamente in referenze ipertestuali. È anche possibile usare la
nuova macro UR per identificare referenze a informazioni correlate. Se
vengono incluse URL, si adoperi l’URL intera
(<http://www.pluto.linux.it>, ad esempio) per assicurarsi che questi
strumenti possano trovarla automaticamente.
Gli strumenti che elaborano questi file dovrebbero aprirle ed esaminare
il primo carattere non di spazio: un punto «.» o un apostrofo «’»
all’inizio di una riga indicano un file di troff (tipo man o mdoc), un
segno di minore «<» un file in SGML/XML (come HTML o DocBook),
qualsiasi altra cosa dovrebbe indicare un semplice testo ASCII (come il
prodotto di «catman», ad esempio).
Molte pagine di guida incominciano con ’\" seguito da uno spazio ed un
elenco di caratteri che indicano i preprocessori per la pagina. Per
mantenere la compatibilità verso i convertitore non troff, consigliamo
di evitare qualsiasi cosa tranne tbl(1), e comunque Linux può
accorgersi da solo di ciò. Comunque, uno potrebbe voler includere
queste informazioni per permettere ad altri sistemi (meno capaci) di
gestire la propria pagina di manuale; per cui, questi sono i
preprocessori invocati da questi caratteri:
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
FILE
/usr/lib/groff/tmac/tmac.an
/usr/man/whatis
BACHI
In confronto ad altri formati come mdoc o DocBook, la maggior parte
delle macro descrivono la formattazione (il tipo di carattere e la
spaziatura, ad esempio) piuttosto che marcare il contenuto semantico
(questo testo è una referenza ad un’altra pagina, ad esempio): persino
l’HTML ha più marcatori semantici! Ciò complica adattare il formato man
a supporti differenti, rendere coerente la formattazione per un dato
supporto e inserire automaticamente le referenze incrociate.
Limitandosi al sottoinsieme di sicurezza descritto prima, dovrebbe
essere più facile automatizzare nel futuro la transizione verso un
formato differente per le pagine di referenza.
La macro Sun TX non è implementata.
AUTORI
— James Clark (jjc@jclark.com) ha scritto l’implementazione del
pacchetto di macro.
— Jens Schweikhardt (schweikh@noc.fdn.de) ha scritto il mini-HOWTO
«The Linux man-page», che ha influenzato questa pagina.
— David A. Wheeler (dwheeler@ida.org) ha apportato pesanti modifiche a
questa pagina, come l’aggiunta di informazioni dettagliate sulle
sezioni e sulle macro.
VEDERE ANCHE
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7),
whatis(1).