Provided by: manpages-it_4.21.0-2_all 
NOME
man - macro per formattare le pagine di manuale
SINTASSI
groff -Tascii -man file ...
groff -Tps -man file ...
man [sezione] titolo
DESCRIZIONE
Questa pagina illustra il pacchetto di macro groff an.tmac (spesso chiamato pacchetto
macro man). Questo pacchetto di macro dovrebbe essere usato dagli sviluppatori quando
scrivono o fanno il port delle pagine di manuale per Linux. È abbastanza compatibile con
altre versioni di questi pacchetti di macro, quindi fare il port delle 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 noti 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 quanto rileverà automaticamente quale pacchetto
macro è in uso.
Per le convenzioni da usare nella scrittura di pagine di manuale per il pacchetto
man-pages di Linux, si veda man-pages(7).
Riga del titolo
Il primo comando in una pagina di manuale (dopo le righe di commento, cioè le righe che
iniziano con .\") dovrebbe essere
.TH titolo sezione data sorgente manuale
Per i dettagli degli argomenti da fornire al comando TH si veda man-pages(7).
Si noti che le pagine formattate con l'mdoc di BSD iniziano col comando Dd invece che col
comando TH.
Sezioni
Le sezioni iniziano con un .SH seguito dall'intestazione.
L'unica intestazione obbligatoria è NOME, che dovrebbe essere la prima sezione e dovrebbe
essere seguita, sulla riga successiva, da una descrizione del programma della lunghezza di
una riga:
.SH NOME
nome \- descrizione
È molto importante che venga seguito questo formato e che ci sia una barra inversa prima
del trattino singolo che segue il nome. Questa sintassi viene usata dal programma
makewhatis(8) per creare un database di brevi descrizioni per i comandi whatis(1) e
apropos(1) (Si veda lexgrog(1) per ulteriori dettagli sulla sintassi della sezione NOME).
Per un elenco di altre sezioni che potrebbero apparire in una pagina di manuale si veda
man-pages(7).
Tipi di carattere
I comandi per selezionare il tipo di carattere sono:
.B Grassetto
.BI Grassetto alternato a corsivo (molto utile per le specifiche delle funzioni)
.BR Grassetto alternato a tondo (molto utile per fare riferimento ad altre pagine di
manuale)
.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 l'implementazione GNU
rimuove questa limitazione (ci si può comunque limitare a sei argomenti per
compatibilità). Gli argomenti sono delimitati da spazi. Le virgolette doppie possono
essere usate per specificare un argomento che contiene spazi. Per le macro che producono
tipi di carattere alternati, 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 non ci sono argomenti, il comando si applica alla
successiva riga di testo.
Altre macro e stringhe
Seguono altre macro importanti e stringhe predefinite. A meno che non sia specificato
diversamente, ogni macro causa un'interruzione (la fine dell'attuale riga di testo). Molte
di queste macro impostano o usano il «rientro dominante». Il suo valore viene impostato da
ognuna delle seguenti macro grazie al parametro i; le macro possono omettere la i, nel
qual caso viene usato il rientro dominante attuale. Come risultato, paragrafi rientrati
che si susseguano possono usare lo stesso rientro senza rispecificarne il valore. Un
paragrafo normale (cioè non rientrato) reimposta il rientro dominante al suo valore
predefinito (mezzo pollice). A priori, il rientro si misura in quadratini; è meglio
utilizzare quadratini (en) e quadratoni (em) come unità, perché si adattano
automaticamente al cambiamento di dimensione dei caratteri. Ulteriori definizioni di macro
sono:
Paragrafi normali
.LP Lo stesso di .PP (inzia un nuovo paragrafo).
.P Lo stesso di .PP (inzia un nuovo paragrafo).
.PP Incomincia un nuovo paragrafo e reimposta il rientro dominante.
Rientro relativo del margine
.RS i Inizia un rientro relativo del margine; sposta di i il margine sinistro verso
destra (se i è omessa, viene usato il valore del 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 dominante.
Macro per paragrafi rientrati
.HP i Inizia 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 è indentato).
.IP x i Paragrafo rientrato con un'etichetta opzionale a bandiera. Se l'etichetta x è
omessa, l'intero paragrafo seguente è rientrato di i. 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 trovarsi sulla riga successiva). Se l'etichetta è troppo
lunga, il testo che la segue viene spostato alla riga seguente (e non verrà né
perso né impiastricciato). Per gli elenchi puntati, si usi questa macro con \(bu
(pallino) o \(em (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 i Incomincia il paragrafo con un'etichetta a bandiera: l'etichetta è sulla riga
seguente, ma il risultato è lo stesso del comando .IP.
Macro per collegamenti ipertestuali
.UR url
Inserisce un collegamento ipertestuale all'URI (URL) url, con tutto il testo fino
alla successiva macro .UE come testo del collegamento.
.UE .RI [ trailer ]
Termina il testo del collegamento della precedente macro .UR, con il trailer
opzionale (se è presente, normalmente una parentesi chiusa e/o una punteggiatura di
fine frase) immediatamente dopo. Per i dispositivi di output non HTML (p.es. man
-Tutf8), il testo del collegamento è seguito dall'URL in parentesi angolate; se
manca il testo del collegamento, l'URL viene stampata così com'è, delimitata da
parentesi angolate. (Le parentesi angolate possono non essere disponibili su tutti
i dispositivi di output.) Per i dispositivi di output HTML, il testo del
collegamento è collegato come ipertesto all'URL; se manca il testo del
collegamento, l'URL viene stampata così com'è.
Queste macro sono state supportate a partire da GNU Troff 1.20 (2009-01-05) e da Heirloom
Doctools Troff 160217 (2016-02-17).
Macro varie
.DT Riporta le tabulazioni al valore di tabulazione predefinito (ogni mezzo pollice);
non causa un'interruzione.
.PD d Imposta la distanza verticale tra paragrafi a d (se omesso, d=0.4v); non causa
un'interruzione.
.SS t Sottotitolo t (come .SH, ma usato per una sottosezione in una sezione).
Stringhe predefinite
Il pacchetto man ha le seguenti stringhe predefinite:
\*R Simbolo di registrazione: ®
\*S Torna alla dimensione predefinita del carattere
\*(Tm Simbolo del marchio registrato: ™
\*(lq Doppie virgolette verso sinistra: “
\*(rq Doppie virgolette verso destra: ”
Sottoinsieme sicuro
Sebbene tecnicamente man sia un pacchetto macro troff, in realtà un grande numero di altri
strumenti che non implementano tutte le capacità di troff processano file di pagine di
manuale. Pertanto è bene evitare alcune delle capacità più esotiche di troff quando
possibile, per permettere a questi strumenti di funzionare correttamente. Evitare di usare
i vari preprocessori di troff (se si deve, proseguire e usare tbl(1), ma provare ad usare
i comandi IP e TP invece delle tabelle a due colonne). Evitare di usare computazioni;
molti altri tool non possono processarle. Si usino comandi semplici, che siano facili da
tradurre in altri formati. Le seguenti macro troff sono ritenute sicure (anche se in molti
casi verranno ignorate dai traduttori): \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft,
hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.
You may also use many troff escape sequences (those sequences beginning with \). When you
need to include the backslash character as normal text, use \e. Other sequences you may
use, where x or xx are any characters and N is any digit, include: \', \`, \-, \., \", \%,
\*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx. Avoid using the escape sequences for
drawing graphics.
Do not use the optional parameter for bp (break page). Use only positive values for sp
(vertical space). Don't define a macro (de) with the same name as a macro in this or the
mdoc macro package with a different meaning; it's likely that such redefinitions will be
ignored. Every positive indent (in) should be paired with a matching negative indent
(although you should be using the RS and RE macros instead). The condition test (if,ie)
should only have 't' or 'n' as the condition. Only translations (tr) that can be ignored
should be used. Font changes (ft and the \f escape sequence) should only have the values
1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no parameters).
Se si usano potenzialità oltre a queste, si verifichino attentamente i risultati con
diversi strumenti. Una volta confermato che la capacità aggiuntiva è sicura mettete a
conoscenza il curatore di questo documento del comando o sequenza sicura che deve essere
aggiunta a questo elenco.
FILE
/usr/share/groff/[*/]tmac/an.tmac
/usr/man/whatis
NOTE
Certamente includere URL (o URI) completi nello stesso testo; alcuni tool come man2html(1)
possono trasformarli automaticamente in collegamenti ipertestuali. Si può anche usare la
nuova macro URL per identificare collegamenti a informazioni correlate. Se si includono
URL usare l'URL completo (es., ⟨http://www.kernel.org⟩) per assicurarsi che gli strumenti
possano trovare automaticamente gli URL.
Tools processing these files should open the file and examine the first nonwhitespace
character. A period (.) or single quote (') at the beginning of a line indicates a
troff-based file (such as man or mdoc). A left angle bracket (<) indicates an
SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text
(e.g., a "catman" result).
Many man pages begin with '\" followed by a space and a list of characters, indicating how
the page is to be preprocessed. For portability's sake to non-troff translators we
recommend that you avoid using anything other than tbl(1), and Linux can detect that
automatically. However, you might want to include this information so your man page can
be handled by other (less capable) systems. Here are the definitions of the preprocessors
invoked by these characters:
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
BUG
La maggior parte delle macro descrivono la formattazione (per esempio, tipo di carattere e
spaziatura) invece di marcare il contenuto semantico (per esempio, questo testo è un
riferimento ad un'altra pagina), rispetto a formati come mdoc e DocBook (anche HTML ha più
marcatori semantici). Questa situazione rende difficile variare il formato di man per
media differenti, per rendere la formattazione coerente per un dato media, e inserire
automaticamente riferimenti incrociati. Bloccandosi sul sottoinsieme sicure descritto
prima, dovrebbe essere più facile automatizzare la transazione ad un diverso formato di
riferimento delle pagine in futuro.
La macro di Sun TX non è implementata.
VEDERE ANCHE
apropos(1), groff(1), lexgrog(1), man(1), man2html(1), groff_mdoc(7), whatis(1),
groff_man(7), groff_www(7), man-pages(7), mdoc(7)
TRADUZIONE
La traduzione italiana di questa pagina di manuale è stata creata da Michele Dalla
Silvestra <dalla@maya.dei.unipd.it>, Ottavio G. Rizzo <rizzo@pluto.linux.it>, Daniele
Giacomini <daniele@evo.it>, Giulio Daprelà <giulio@pluto.it>, Elisabetta Galli
<lab@kkk.it> e Marco Curreli <marcocurreli@tiscali.it>
Questa traduzione è documentazione libera; leggere la GNU General Public License Versione
3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ o successiva per le condizioni di copyright.
Non ci assumiamo alcuna responsabilità.
Per segnalare errori nella traduzione di questa pagina di manuale inviare un messaggio a
⟨pluto-ildp@lists.pluto.it⟩.