Ubuntu Manpage: man - macro per formattare le pagine di manuale

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. 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 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 (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
(Caratteristica suportata solo da groff). Per usare le macro per collegamenti ipertestuali è 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 verrà 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.

Può 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'è) 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 è stato usato groff la definizione della macro URL del pacchetto
macro www.tmac sostituirà quella definita localmente.

È 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: ®

\*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.

Si possono anche usare molte sequenze di escape di troff (queste sequenze iniziano con \). Quando si ha
la necessità 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 è 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; è 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 può anche non avere parametri).

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.kernelnotes.org) per assicurarsi che gli strumenti possano trovare automaticamente gli URL.

       Gli strumenti che elaborano 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 portabilità verso traduttori non troff si
       raccomanda di evitare cose diverse da tbl(1), e  Linux  lo  può  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)

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),  whatis(1),  groff_man(7),  groff_www(7), man-
       pages(7), mdoc(7), mdoc.samples(7)

COLOPHON

       Questa pagina fa parte del rilascio 3.73 del progetto Linux man-pages. Una descrizione del  progetto,  le
       istruzioni  per  la  segnalazione  degli  errori,  e  l'ultima  versione  di  questa  pagina  si trova su
       http://www.kernel.org/doc/man-pages/.

       La versione italiana fa parte del pacchetto  man-pages-it  v.  3.73,  a  cura  di:  ILDP  "Italian  Linux
       Documentation Project" http://www.pluto.it/ildp
       Per la traduzione in italiano si può fare riferimento a http://www.pluto.it/ildp/collaborare/
       Segnalare eventuali errori di traduzione a ildp@pluto.it

Linux                                              2012-08-05                                             MAN(7)