Creazione di una man page sotto Linux

Sommario

Una pagina di manuale detta « man » è l'elemento indispensabile di un programma. In effetti, essa fornisce le informazioni essenziali riguardo l'uso di un programma e necessita poco spazio sul disco. questo articolo vi permetterà di realizzare la votra pagina di manuale molto velocemente.

Avvertenza

Questo articolo non è destinato a spiegarvi l'uso di ogni macro macro, per maggiori informazioni,consultare la pagina di manuale denomminata groff_man(7)

Introduzione

Un buon programma è sempre munito di una documentazione. in effetti il manuale è l'elemento essenziale e indispensabile per l'utente finale. Imaginate la prima reazione di un utente se quello si trova nell'incapacita di capirne il funczionnamento !!! Scrivere un manuale d'uso, è semplice, occupa pochissimo spazio, possibilità di converzione nei formati correnti. Iniziamo questo How-To con la presentazione di una pagina di manuale " man page".

Presentazione

Le rubriche

queste sone le rubriche principali di un pagina di manuale :

• Nome

Nome del programma usato.

• Synopsis

qui si trovano la sintassi del comando del programma, le opzioni e i i parametri.

• Description

Utilizzazione del programma.

• Options

Tutte le opzioni usate dal programma e la loro descrizione.

• Exemples

Esempio d'utilizzazione dell'applicazione.

• Autore

La persona che ha realizzazato l'applicazione.

• Bugs

Permette di segnalare in caso di errore.

• Copyright

I diritti di autore.

• Disponibilità

Generalmente il sito in cui è ossibile scaricare l'applicazione.

• Files

Lista dei file utilizzati dall'applicazione.

• See also

Elenca i programma che hanno un link diretto con l'applicazione.

• History

Storia delle modifiche del programma.

Le macro

Il linguaggio utilzzato per realizzare un manuale è relativamente semplice:i termini usati innizianno tutti con un punto e sonno noti come macro. Qui sotto è riportata una lista esaustiva delle macro con le relative funzioni. Macro (struttura del documento)

• .DT - (Tabulazione predefinita)
• .HP - (Inizio d'indentation)
• .IP - (Inizio paragrafo con parola chiave alla riga seguente)
• .TP - (Inizio paragrafo con parola chiave sulla stessa riga)
• .LP - (Inizio di un nuovo paragrafo)
• .PD - (Imposta la distanza al valore passato in parametro)

• .PP - (Iniziare un nuovo paragrafo)
• .RE - (Fine d'indentation relativa (in un nuovo paragrafo))
• .RS - (Inizio d'indentation relativa (in un paragrafo))
• .SS - (Sotto-titolo ma per una sotto sezione)
• .SH - (Sotto-titolo)
• .TH - (Tittolo sezione data sorgente manuale)
• ." - (Commento su una riga)

Macro (font per i caratteri)

• .B - (Grassetto)
• .BI - (Gras alternato con Corsivo)
• .BR - (Grassetto alternato con Roman)
• .I - (Corsivo)
• .IB - (Corsivo alternato con Grassetto)
• .IR - (Corsivo alternato con Roman)
• .RB - (Roman alternato con Grassetto)
• .RI - (Roman alternato con Corsivo)
• .SB - (Small alternato con Grassetto)
• .SM - (Small)

Tutte quelle macro di formattazione sono riperibili nella pagine di manuale intittolata groff_man(7)

Il comando groff

Il pacchetto groff include molti programmin per l'elaborazione e la formattazione del testo. Groff traduce testo e comandi specifici in output formatatto, esttamente come visualizzate su una man page.

Lo script nroff

Lo script nroff emula il comando nroff utilizzando groff.