man

formatta e mostra le pagine di guida in linea

man.1.man
man.7.man

1. man.1.man

Manpage of man

man

Section: User Commands (1)
Updated: 2 settembre 1995
Index Return to Main Contents

NOME

man - formatta e mostra le pagine di guida in linea
manpath - determina i percorsi di ricerca dell'utente per le pagine di guida

SINTASSI

man [-acdfFhkKtwW] [-m sistema] [-p stringa] [-C file_configurazione] [-M percorso] [-P impaginatore] [-S lista_sezioni] [sezione] nome ...

DESCRIZIONE

man formatta e mostra le pagine di guida in linea. Questa versione riconosce le variabili d'ambiente MANPATH e (MAN)PAGER, in modo da avere il proprio insieme di pagine di guida e scegliere il programma preferito per leggere le pagine formattate. Se sezione è specificata, man cerca solamente in quella sezione del manuale. Si può anche specificare l'ordine di ricerca delle sezioni e quale preprocessore utilizzare tramite un'opzione della riga di comando o variabile d'ambiente. Se nome contiene un carattere /, allora questo viene prima provato come se fosse il nome di un file, in modo da poter fare man ./foo.5 o anche man /cd/foo/bar.1.gz.

OPZIONI

-C file_configurazione: Specifica il file man.conf da usare; il valore di default è /etc/man.conf (vedere man.conf(5)).
-M percorso: Specifica la lista di directory in cui cercare le pagine di guida. Se questa opzione manca, viene usata la variabile d'ambiente MANPATH. Se tale variabile d'ambiente non ci fosse, l'elenco di default è trovato consultando /etc/man.conf. Una sottostringa vuota di MANPATH denota la lista di default.
-P impaginatore: Specifica il programma di impaginazione da usare. Per default man usa /usr/bin/less-is. Questa opzione sovrascrive la variabile d'ambiente MANPAGER, che sovrascrive a sua volta la variabile PAGER.
-S lista_sezioni: La lista è un elenco separato dal carattere due punti di sezioni di guide da cercare. Questa opzione sovrascrive la variabile d'ambiente MANSECT.
-a: Di natura, man esce dopo aver mostrato la prima pagina di guida trovata. Usando questa opzione si forza man a mostrare tutte le pagine di guida corrispondenti a nome, non solo la prima.
-c: Riformatta la pagina di guida sorgente, anche quando esiste una pagina formattata aggiornata. Questa opzione è utile se la pagina è stata formattata per uno schermo con un numero diverso di colonne.
-d: Non mostra la pagina di guida, ma stampa alcune informazioni diagnostiche.
-D: Mostra sia la pagina che le informazioni diagnostiche.
-f: Equivalente a whatis.
-F o --preformat: Formatta solamente: non mostra niente.
-h: Stampa una riga di aiuto ed esce.
-k: Equivalente a apropos.
-K: Ricerca una stringa specifica in *tutte* le pagine di guida. Attenzione: questo è probabilmente molto lento! Può essere di aiuto specificare una sezione (solo per dare un'idea, nella mia macchina questo porta via circa un minuto per 500 pagine di guida).
-m sistema: Specifica un insieme alternativo di pagine di guida da cercare basato sul nome di sistema dato.
-p stringa: Specifica la sequenza di preprocessori da eseguire prima di nroff o troff. Non tutte le installazioni hanno l'insieme completo di preprocessori. Alcuni preprocessori e le lettere usate per designarli sono: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). Questa opzione sovrascrive la variabile d'ambiente MANROFFSEQ.
-t: Usa /usr/bin/groff -Tps -mandoc per formattare la pagina di guida, mandando l'output allo stdout. L'output di /usr/bin/groff -Tps -mandoc potrebbe aver bisogno di passare attraverso filtri o altro prima di essere stampato.
-w o --path: Non mostra subito la pagina di guida, ma stampa la posizione dei file che dovrebbero essere formattati o visualizzati. Se non è dato nessun argomento mostra (sullo stdout) la lista di directory in cui man esegue la ricerca per le pagine di guida. Se manpath è un link a man, allora "manpath" è equivalente a "man --path".
-W: Come -w, ma stampa i nomi dei file uno per riga, senza ulteriori informazioni. Questo è utile in comandi di shell tipo man -aW man | xargs ls -l.

PAGINE FORMATTATE

Man tenterà di salvare le pagine di guida formattare, in modo da risparmiare il tempo di formattazione la volta successiva che quelle pagine saranno necessarie. Tradizionalmente, le versioni formattate delle pagine in DIR/manX sono salvate in DIR/catX, ma altri tipi di mappatura possono essere specificati in /usr/lib/man.conf. Le pagine formattate non sono salvate quando la directory cat corrispondente non esiste.

È possibile rendere man suid all'utente man. Quindi, se una directory cat ha proprietario man e permessi 0755 (scrivibile solo da man), e i file formattati hanno proprietario man e permessi 0644 o 0444 (scrivibili solo da man, o non scrivibili affatto), nessun utente ordinario può cambiare le pagine formattate o mettere altri file nella directory cat. Se man non è suid, allora la directory cat deve avere i permessi 0777 se tutti gli utenti devono essere abilitati a lasciare lì le pagine formattate.

L'opzione -c forza la formattazione di una pagina, anche se esiste una pagina formattata di recente.

AMBIENTE

MANPATH: Se MANPATH è impostata, il suo valore è usato come percorso di ricerca per le pagine di guida.
MANROFFSEQ: Se MANROFFSEQ è impostata, il suo valore è usato per determinare l'insieme di preprocessori da eseguire prima di nroff o troff. Per default, le pagine sono passate attraverso il preprocessore di tabelle prima di nroff.
MANSECT: Se MANSECT è impostata, il suo valore è usato per determinare quale sezione del manuale usare per la ricerca.
MANWIDTH: Se MANWIDTH è impostata, il suo valore è usato per la larghezza con cui le pagine di guida dovrebbero essere visualizzate. Altrimenti le pagine saranno mostrate utilizzando la dimensione intera dello schermo.
MANPAGER: Se MANPAGER è impostata, il suo valore è usato come nome del programma da usare per mostrare le pagine di guida. Altrimenti viene usato il valore di PAGER. Se neanche questa è impostata, viene usato /usr/bin/less-is.
LANG: Se LANG è impostata, il suo valore definisce il nome della sottodirectory dove man cerca prima per le pagine di guida. Così il comando `LANG=it man 1 foo' fa in modo che man cerchi la pagina di guida di foo in directory nel percorso di ricerca.
NLSPATH, LC_MESSAGES, LANG: Le variabili d'ambiente NLSPATH e LC_MESSAGES (o LANG quando l'ultima non esiste) giocano un ruolo nella localizzazione del catalogo messaggi (ma i messaggi inglesi sono compilati, e per l'inglese non è richiesto il catalogo). Notare che programmi tipo col(1) chiamati da man usano anche LC_CTYPE.
PATH: PATH è usata nella costruzione del percorso di ricerca di default per le pagine di guida.
SYSTEM: SYSTEM è usata per ottenere il nome di sistema alternativo (per l'uso con l'opzione -m).

VEDERE ANCHE

apropos(1), whatis(1), less(1), groff(1).

BACHI

L'opzione -t funziona solo se è installato un programma simile a troff.
Se compaiono dei \255 lampeggianti o <AD> al posto dei trattini, si ponga la variabile ambientale `LESSCHARSET=latin1'.

CONSIGLI

Se si aggiunge la riga

(global-set-key [(f1)] (lambda () (interactive) (manual-entry (current-word))))

nel proprio file .emacs, allora il tasto F1 produrrà la pagina di manuale corrispondente alla chiamata di libreria su cui è posizionato il cursore.

This document was created by man2html using the manual pages.
Time: 00:23:51 GMT, November 20, 2008

2. man.7.man

Manpage of MAN

MAN

Section: Linux Programmer's Manual (7)
Updated: 30 maggio 2007
Index Return to Main Contents

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

Index

NOME

SINTASSI

DESCRIZIONE

Riga del titolo
Sezioni
Tipi di carattere
Altre macro e stringhe
Paragrafi normali
Rientro relativo del margine
Macro per paragrafi rientrati
Macro per collegamenti ipertestuali
Macro varie
Stringhe predefinite
Sottoinsieme sicuro

This document was created by man2html using the manual pages.
Time: 00:23:51 GMT, November 20, 2008