<- Utilità e traduzione di documenti in SGML e XML - Indice Generale - Copertina - Intervista a Paolo Didonè (Associazione Software libero) ->

L'angolo del PLUTO

Come funziona e come si traduce una man page

di Giulio Daprelà

Cos'è una man page

Una man page è una pagina di manuale in linea, ossia una pagina che chiarisce nei dettagli come funziona un comando o un programma che può essere indicata e visualizzata digitando il comando man <nome programma> nell'interfaccia a linea di comando.
Il sorgente di una man page deve essere scritto nel linguaggio troff e viene poi letto e formattato in modo tale da essere visualizzato sul monitor da un programma che si chiama Groff.
Sarà possibile visualizzare una sezione, se fornita, che indirizzerà man page solo in quella sezione della pagina.

Nella tabella seguente sono elencate le sezioni delle pagine man:

1. Programmi eseguibili e comandi della shell.

2. Chiamate di sistema.

3. Chiamate libc.

4. Periferiche (es. hd, sd).

5. Formati dei file e protocolli (es. wtmp, /etc/passwd, nfs).

6. Giochi (solo intro).

7. Pacchetti di macro e convenzioni, come man(7), groff(7).

8. Comandi di amministrazione e privilegiati (solo intro)

9. Routine del kernel [Non standard]

Le pagine di manuale, di solito, sono incluse nei pacchetti software, pertanto durante l'installazione di uno o più programmi viene automaticamente installata anche la sua man page. Esistono molti pacchetti software che non includono la man page nel pacchetto principale, e questo significa che l'utente che installa quel determinato programma che non possiede la man page è ovviamente privo di ogni possibilità di aiuto in linea. Il pacchetto man page è stato pensato e quindi indirizzato a supportare alcune mancanze di elementi di utilizzo di base e per fornire documentazione riguardo a chiamate di sistema, routine di librerie, dispositivi speciali e formati di file. Il pacchetto man page ufficiale si trova all'indirizzo web http://www.win.tue.nl/~aeb/linux/man/ ed è redatto da Michael Kerrisk.

Nel pacchetto man page sono sempre incluse le pagine di manuale dei comandi di Linux.
Essi non sono altro che programmi che svolgono un compito standard in GNU/Linux, come ad esempio copiare dei file (cp) o elencare il contenuto di una directory (ls).
Linux è un linguaggio Unix, il più famoso, e tutti i suoi comandi dovrebbero seguire lo standard Unix, ma poiché i programmi che eseguono i comandi vengono creati da programmatori indipendenti non esiste nessuna garanzia che si comportino secondo gli standard riconosciuti.
In Unix esiste "famiglia" di standard di riferimento chiamata POSIX , acronimo di Portable Operating System Interface for uniX, che non è mai stata utilizzata perché IEEE , l'organismo che pubblica questi standard, richiedeva per fornire la documentazione costi elevati. Solo nel 2003 l' IEEE ha concesso la pubblicazione dei suoi standard all'interno delle pagine di manuale. Sono state così create tre nuove sezioni, in cui sono state spostate, da quelle in cui si trovavano in precedenza,  molte pagine di manuale. È stata aggiunta inoltre, una "P" all'estensione della pagine di manuale, per rendere chiaro che sono standard POSIX (es. cp.1p).
La differenza fondamentale tra una pagina di manuale normale e una POSIX è che nel primo caso si vuole documentare un programma esistente, mentre la man page POSIX è una specifica tecnica, utile a tutti coloro che desiderino creare un programma che si chiami con quel determinato nome. Il concetto è che se ad esempio il comando "cp" è uno standard POSIX, tutti coloro che vogliono creare un programma che copi i file e vogliono chiamarlo "cp" devono far sì che questo si comporti e segua la procedura richiesta appositamente da POSIX.

Nel pacchetto ufficiale si aggiungono quindi tre nuove sezioni:

1. 0P Header POSIX

2. 1P Utilità POSIX

3. 3P Funzioni di libreria POSIX

Cos'è Groff

Il nome Groff significa GNU roff ed è l'implementazione libera del sistema di scrittura roff. Storicamente il linguaggio roff veniva chiamato troff. Groff è compatibile con questo sistema e aggiunge alcune estensioni, perciò nei sistemi GNU, roff, troff e groff possono essere usati come sinonimi. Troff è nato nel 1973 (ma ha antenati che risalgono agli anni 60) ed è un linguaggio ottimamente strutturato che viene usato ancora oggi.

Il linguaggio delle man page

Per poter scrivere una man page con una corretta formattazione è necessario seguire la sintassi roff, che non è molto difficile.
Il linguaggio groff è "line-oriented", ovvero orientato alla linea. Ci sono due tipi di linee: le linee di controllo e le linee di testo. Le linee di controllo iniziano con un carattere di controllo, solitamente un punto ".", oppure un apice singolo "'". Tutte le altre sono linee di testo.

Le linee di controllo rappresentano comandi con eventuali argomenti. Essi hanno la seguente sintassi: il carattere di controllo in testa può essere seguito da un nome di comando, eventuali argomenti sono separati dal comando e tra di loro da spazi.

Per esempio:

.nome_comando arg1 arg2

È importante capire che il carattere di controllo deve essere sempre nella prima posizione sulla linea.

Le linee di testo rappresentano la parte che verrà stampata.

Il linguaggio roff fornisce strumenti flessibili per scrivere estensioni del linguaggio, come le macro.
Man non è altro che un pacchetto di macro di Groff.

A seguire un elenco delle macro principali che man utilizza per la formattazione del testo delle man page.

• .TH = titolo di una sezione

• .SH = intestazione non indentata

• .SS = intestazione indentata

• .TP = paragrafo indentato

• .LP = interruzione di linea alla posizione corrente

• .PP = idem come .LP

• .P = idem come .LP

• .B = il testo che segue viene evidenziato in grassetto (bold face)

• .I = il testo che segue viene rappresentato in italic

• .R = il testo che segue viene rappresentato in roman

• .BI = il testo viene rappresentato alternativamente in grassetto e italic

Per quest'ultima macro ecco un esempio che potrebbe chiarirne il funzionamento. Se nel sorgente ci fosse la seguente linea:

.BI Questa "parola e" quella

"questa" e "quella" verrebbero impostate in grassetto, e "parola e" in italic (racchiudendole tra apici doppi vengono considerate una parola sola). Per cui il testo stampato sarebbe:

questa parola e quella

È possibile realizzare le combinazioni che si desiderano tra i tre stili di font. Ad esempio .IB avrebbe invertito le parole in grassetto e quelle in italic.

Esempi

Il seguente esempio prende la man page di Wait(2) e mostra il sorgente della pagina e la visualizzazione sul monitor.

Alla linea numero 53 la macro .SH indica una sezione. La parola che segue (NOME) viene scritta in grassetto, come mostrato nell'immagine. (1)

Le prime due linee nella sezione SINTASSI (cerchiate nel numero 2) sono scritte in grassetto (.B). Il comando .br serve per andare a capo al termine della prima linea, altrimenti Groff mostrerebbe le linee una di seguito all'altra sulla stessa riga.

Il comando .sp (3) è un salto di riga.

4 (grassetto) e 5 (Italic) nell'immagine, mostrano l'effetto della combinazione delle macro .BI (4 sull'immagine del sorgente).

Figura 1: Sorgente della pagina di manuale Wait(2)

Figura 2: Man page di Wait(2) come compare sul monitor.

Ogni macro o comando, ha effetto su tutto ciò che segue solo sulla stessa riga. Il testo sulla riga successiva viene formattato normalmente
Se la riga è vuota, la macro o il comando avranno invece effetto sulla riga successiva.
È importante tenere ben presente questa caratteristica quando si traduce o si scrive una man page. Se si desidera scrivere in grassetto una precisa parola all'interno di un testo, essa dovrà trovarsi DA SOLA in una linea (di esempio) come la seguente:

testo che precede
.B parola
testo che segue

Come tradurre

Il lavoro di traduzione di una man page, a condizione che si conosca la lingua inglese, è piuttosto semplice dal punto di vista tecnico. Bisogna tuttavia porre attenzione ad alcuni aspetti importanti.

Terminologia

I titoli delle sezioni in una man page sono standardizzati, quindi è importante che tutti i traduttori mantengano una certa uniformità e usino gli stessi titoli. Di seguito vengono elencati i titoli delle sezioni e la loro traduzione in italiano.

Tabella 1: Traduzione standard dei titoli di sezione.

Il copyright

Nelle pagine di manuale il copyright si trova o all'inizio o in fondo alla pagina, inserito come commento. Esso quindi non appare a video quando utilizziamo la pagina di manuale.
Il copyright non va mai tradotto, perché ovviamente è un lavoro inutile in caso di necessità bisogna sempre ricordarsi e tener presente che fa fede il testo in lingua originale, poiché la traduzione potrebbe non rispecchiarne fedelmente il significato.

Nome del traduttore

È sempre bene aggiungere il nome del traduttore, inserito tra i commenti,  per dare credito a chi ha fatto il lavoro. Il nome del traduttore può essere aggiunto all'inizio del documento, in fondo al copyright, come nell'esempio a seguire in figura 3.

Figura 3: Come aggiungere il nome del traduttore al documento

Come si può notare c'è una prima traduzione e due successive revisioni. La ragione per cui la pagina di manuale non è stata aggiornata ad ogni nuova versione del pacchetto man page è che non è detto che venga sempre modificata. Potrebbe rimanere invariata per mesi o addirittura anni, nel qual caso non subirebbe mai aggiornamenti, nemmeno nella sua versione tradotta.

I formati delle pagine di manuale

Il formato originario delle pagine di manuale non è obbligatoriamente quello utilizzato per visualizzarle.
Esiste la possibilità, con appositi comandi, di ottenere una versione HTML di tutte le pagine. Sul sito di ILDP, all'indirizzo web http://www.pluto.it/ildp/man/ è possibile accedere alla versione on line delle pagine tradotte in italiano. È possibile inoltre ottenere una versione in formato testo delle pagine attraverso il comando:

man nome_prg > col -bfx > nome_prg.txt

Il programma con le relative opzioni funziona da filtro, per togliere tutti i codici o macro di groff e rendere quindi il testo "pulito".

Per chi desidera stampare una man page di qualità in postcript basta usare il comando:

man -t nome_prg > nome_prg.ps

Infine per visualizzare a video la pagina di manuale che si sta traducendo basta richiamarla con il comando:

man ./percorso/del/file/file_man.1

Riferimenti bibliografici

[1] Appunti di informatica libera - di Daniele Giacomini.
Introduzione a *roff

[2] la pagina info di groff, ottenibile attraverso il comando
info groff

[3] La pagina di manuale di man, ottenibile attraverso il comando:
man man

[4] La pagina di troff di Wikipedia:
troff

<- Utilità e traduzione di documenti in SGML e XML - Indice Generale - Copertina - Intervista a Paolo Didonè (Associazione Software libero) ->