MAN(7) | Linux Programmer's Manual | MAN(7) |
man - macro per formattare le pagine di manuale
groff -Tascii -man file ...
groff -Tps -man file ...
man [sezione] titolo
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).
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
Si noti che le pagine formattate con l'mdoc di BSD iniziano col comando Dd invece che col comando TH.
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
Per un elenco di altre sezioni che potrebbero apparire in una pagina di manuale si veda man-pages(7).
I comandi per selezionare il tipo di carattere sono:
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.
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:
(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.
È disponibile un certo numero di altri collegamenti macro. Si veda groff_www(7) per maggiori dettagli.
Il pacchetto man ha le seguenti stringhe predefinite:
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.
/usr/share/groff/[*/]tmac/an.tmac
/usr/man/whatis
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:
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.
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)
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
2012-08-05 | Linux |