Scrivere la guida in linea, la cosiddette man page, é un'operazione
abbastanza elementare, che chiunque può fare. Per essere tutte standard,
le man page devono seguire dei semplici passi che vediamo sotto.
Si tratta semplicemente di scrivere un file con elementari regole
sintattiche, che viene poi rielaborato dal programma groff, che
restituisce la man page.
Si rende comunque necessario sapere il meccanismo preciso di come
il sistema accede alle man page allo scopo di dare alla vostra man
page il nome giusto e installarlo nel luogo adatto. Ciascuna man
page appartiene a una sezione specifica, denotata da un singolo
carattere.
Le sezioni più usate sotto Linux e i loro relativi nomi sono:
Tabella 2-11. Le diverse sezioni delle man page
|
Sezione |
Significato |
|
1 |
Comandi utente, che possono essere avviati da chiunque. |
|
2 |
Chiamate di sistema, cioè funzioni fornite dal kernel. |
|
3 |
Funzioni di libreria. |
|
4 |
Periferiche, cioè, nomi speciali nella directory /dev. |
|
5 |
Descrizione di formati di files, esempio /etc/lilo.conf. |
|
6 |
Giochi. |
|
7 |
Miscellanea. |
|
8 |
Utility di amministrazione del sistema che solo root può eseguire. |
|
9 |
Altro (specificatamente in Linux) documentazione relativa al kernel. |
|
n |
Nuova documentazione, che può essere spostata nella sezione appropriata. |
|
o |
Documentazione obsoleta. |
|
l |
Documentazione che fa riferimento a questo particolare sistema. |
Vediamo ora la struttura di una tipica man page:
.TH nome sezione
data
specifica l'intestazione della man page
che ha la seguente struttura:
+--------------------------------------------+
|nome(sezione) nome(sezione)|
| |
/ /
| |
| data numero_pagina|
+--------------------------------------------+
.SH "descrizione"
Intestazione della sezione descrizione
.SS "descrizione"
Intestazione della sotto-sessione di "descrizione"
.B scritta
scritta in grassetto
.I scritta
scritta in corsivo
.BI a b a b a b a...
.IB a b a b a b a...
.RI a b a b a b a...
.IR a b a b a b a...
.RB a b a b a b a...
.BR a b a b a b a...
BI pone le a in grassetto e le b in corsivo
RI pone le a in roman e la le b in corsivo
IR pone le a in corsivo e le b in roman
RB pone le a in roman e le b in grassetto
BR pone le a in grassetto e le b in roman
.P
.LP
.PP
Tre sinonimi per le interruzioni di paragrafo
.TP colonne
termine
paragrafo...
.IP inizio
Inizia un paragrafo indentato, l'argomento
inizio é presente viene posto alla
sinistra del paragrafo.
.RS
...
.RE
Definisce un regione indentata.
Comandi generici
.\" linea di commento
Queste macro appena descritte compongono un elenco completo di come
può essere fatta una man page, ma effettivamente alcune di esse
sono poco usate. Scriviamo ora una man page, rispettando le regole
fin ora dette, chiameremo tale man page mioprogramma.1, dove mio
programma sarà un comando utente che può essere avviato da chiunque.
Ecco un esempio di come deve essere tale file:
Esempio 2-5. La nostra prima manpage
.TH MIOPROGRAMMA
1 LOCAL
.SH NAME
mioprogramma - esegue qualcosa di utile
.SH SYNOPSIS
.B mioprogramma [opzioni]
.I option option
.B ["
.I f1 f2
.B ..."]
.SH DESCRIPTION
.I mioprogramma
Script bash che fa qualcosa di utile, e ha le seguenti opzioni:
.TP 5
f1
Descrivi la prima opzione
.TP
f2
Descrivi la seconda opzione
.P
Paragrafo con un esempio di utilizzo:
.br
.nf
mioprogramma "con opzioni"
.fi
.SH OPTIONS
.TP
.I -r
Fa qualcosa di utile.
.TP
.I -n
Opzione per non fare nulla
.SH AUTHOR
MioNome MioCognome
.SH SEE ALSO
utile(1), tools(2)
.SH DIAGNOSTICS
Programma utile.
.SH BUGS
Per vederne l'output, abbiamo bisogno di formattare il codice appena
creato con
$ groff -man -Tascii mioprogramma.1
E cosí abbiamo visto l'output della nostra man page. Tutti i programmi
installano la manpage nella directory di sistema, di solito /usr/man/manN,
dove N é il numero di man page nel nostro caso 1.
Torna all'indice Generale del corso di Corso di C con Linux di Software Planet