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