Provided by: manpages-it_2.80-3_all bug

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 lunga una riga del programma:

              .SH NOME

       È 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  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 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 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)

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