Provided by:
manpages-it_2.80-3_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. E
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 e 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 e, comunque, raccomandato, in quanto rilevera
automaticamente quale pacchetto macro e 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,
cioe 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 e NOME, che dovrebbe essere la prima
sezione e dovrebbe essere seguita, sulla riga successiva, da una
descrizione lunga una riga del programma:
.SH NOME
E molto importante che venga seguito questo formato e che ci sia una
barra inversa prima del trattino singolo che segue il nome del comando.
Questa sintassi viene usata dal programma makewhatis(8) per creare un
database di brevi descrizioni dei comandi per i comandi whatis(1) e
apropos(1)
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 puo avere fino a sei argomenti, ma
l'implementazione GNU rimuove questa limitazione (ci si puo comunque
limitare a sei argomenti per compatibilita). 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, cosi il comando .BR
puo 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 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
(cioe non rientrato) reimposta il rientro dominante al suo valore
predefinito (mezzo pollice). A priori, il rientro si misura in
quadratini; e meglio utilizzare quadratini (en) e quadratoni (em) come
unita, perche 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 e 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 e indentato).
.IP x i Paragrafo rientrato con un'etichetta opzionale a bandiera. Se
l'etichetta x e omessa, l'intero paragrafo seguente e
rientrato di i. Se l'etichetta x e presente, viene allineata
al margine sinistro prima del paragrafo rientrato seguente (e
la stessa cosa di .TP tranne per il fatto che l'etichetta e
inclusa nel comando invece di trovarsi sulla riga successiva).
Se l'etichetta e troppo lunga, il testo che la segue viene
spostato alla riga seguente (e non verra ne perso ne
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: cio semplifica la
conversione verso altri formati.
.TP i Incomincia il paragrafo con un'etichetta a bandiera:
l'etichetta e sulla riga seguente, ma il risultato e lo stesso
del comando .IP .
Macro per collegamenti ipertestuali
(Caratteristica suportata solo da groff .) Per usare le macro per
collegamenti ipertestuali e necessario caricare il pacchetto macro
www.tmac . Usare il .mso www.tmac richiesto per farlo.
.URL url link trailer
Inserisce un collegamento ipertestuale all'URI (URL) url, con
link come testo del collegamento. Il trailer verra stampato
immediatamente dopo. Quando si genera l'HTML, questo dovrebbe
essere tradotto nel comando HTML <A
HREF="url">link</A>trailer.
Questo <<macro>>, e altre ad essa relative, 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), si
possono inserire senza problemi.
Puo essere utile definire la propria macro URL nelle pagine di
manuale per facilitare coloro che la vedono con un
visualizzatore roff piuttosto che con groff. In questo modo
URL, testo del collegamento, e testo collegato (se c'e)
saranno ancora visibili.
Ecco un esempio:
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(di seguito nella pagina)
Questo software viene dal
.URL "http://www.gnu.org/" "Progetto GNU" " della"
.URL "http://www.fsf.org/" "Free Software Foundation" .
Nell'esempio qui sopra, se e stato usato groff la definizione
della macro URL del pacchetto macro www.tmac sostituira quella
definita localmente.
E disponibile un certo numero di altri collegamenti macro. Si veda
groff_www(7) per maggiori dettagli.
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: (R)
\*S Torna alla dimensione predefinita del carattere
\*(Tm Simbolo del marchio registrato: tm
\*(lq Doppie virgolette verso sinistra: "
\*(rq Doppie virgolette verso destra: "
Sottoinsieme sicuro
Sebbene tecnicamente man sia un pacchetto macro troff, in realta un
grande numero di altri strumenti che non implementano tutte le capacita
di troff processano file di pagine di manuale. Pertanto e bene evitare
alcune delle capacita piu 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.
Si possono anche usare molte sequenze di escape di troff (queste
sequenze iniziano con \). Quando si ha la necessita di includere il
carattere backslash come testo normale usare \e. Altre sequenze che si
possono usare, dove x o xx sono caratteri qualsiasi e N e un numero
qualunque, includono: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N,
\nx, \n(xx, \fx, e \f(xx. Evitare di usare sequenze di escape per
disegni grafici.
Non usare il parametro opzionale per bp (interruzione pagina). Usare
solo valori positivi per sp (spazio verticale). Non definire una macro
(de) con lo stesso nome di una macro in questo o nel pacchetto macro
mdoc con un diverso significato; e facile che queste ridefinizioni
vengano ignorate. Ogni rientro positivo (in) deve essere accompagnato
da un corrispondente rientro negativo (anche se si dovrebbero usare le
macro RS e RE al loro posto). Il test condizionale (if,ie) deve avere
solo 't' o 'n' come condizione. Solo le traduzioni (tr) che possono
essere ignorate devono essere usate. I cambiamenti del tipo di
carattere (ft e la sequenza di escape \f ) devono avere solo i valori
1, 2, 3, 4, R, I, B, P, o CW (il comando ft puo anche non avere
parametri).
Se si usano potenzialita oltre a queste, si verifichino attentamente i
risultati con diversi strumenti. Una volta confermato che la capacita
aggiuntiva e 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 puo anche usare la nuova macro URL per
identificare collegamenti a informazioni correlate. Se si includono
URL usare l'URL completo (es., <http://www.kernelnotes.org>) per
assicurarsi che gli strumenti possano trovare automaticamente gli URL.
Gli strumenti che processano questi file devono aprire il file ed
esaminare il primo carattere che non sia uno spazio. Un punto (.) o
virgoletta singola (') all'inizio di una riga indicano un file basato
su troff (come man o mdoc). Una parentesi angolare sinistra (<) indica
un file basato su SGML/XML (come HTML o Docbook). Qualsiasi altra cosa
suggerisce semplice testo ASCII (per esempio un risultato "catman").
Molte pagine di manuale cominciano con '\" seguito da uno spazio e un
elenco di caratteri, che indicano come la pagina deve essere
preprocessata. Per ragioni di portabilita verso traduttori non troff
si raccomanda di evitare cose diverse da tbl(1), e Linux lo puo
rilevare automaticamente. Tuttavia si possono includere queste
informazioni in modo che le proprie pagine di manuale possano essere
gestite da altri (meno capaci) sistemi. Queste sono le definizioni dei
preprocessori invocate da questi caratteri:
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
BACHI
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 e un riferimento ad un'altra
pagina), rispetto a formati come mdoc e DocBook (anche HTML ha piu
marcatori semantici). Questa situazione rende difficile variare il
formato di man per media differenti, per rendere la formattazione
consistente per un dato media, e inserire automaticamente riferimenti
incrociati. Bloccandosi sul sottoinsieme sicure descritto prima,
dovrebbe essere piu facile automatizzare la transazione ad un diverso
formato di riferimento delle pagine in futuro.
La macro di Sun TX non e implementata.
VEDERE ANCHE
apropos(1), groff(1), man(1), man2html(1), whatis(1), groff_man(7),
groff_www(7), man-pages(7), mdoc(7), mdoc.samples(7)