Creazione di una man page sotto Linux
Indice
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.