Corso di C con Linux

Scrivere la guida in linea (man page)

 

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