Documentazione in Linux

Articolo

man

È il primo dei sistemi di documentazione in linea adottati in ambiente Unix, e di conseguenza ce lo ritroviamo pari pari anche in Linux.

Si chiama man come abbreviazione di "manual" ed è costituito da numerosi documenti (files), uno per ogni comando o programma da documentare. Naturalmente il comando man stesso possiede la sua documentazione:


laptop-lfini-128: man man

man(1)                                                     man(1)

NAME
       man - format and display the on-line manual pages

SYNOPSIS
       man [-acdfhkKtwW] [-m system] [-p string] [-C config_file]
       [-M path] [-P pager] [-S section_list] [section] name  ...

DESCRIPTION
       man  formats  and displays the on-line manual pages.  This
       version knows about the MANPATH and (MAN)PAGER environment
       variables, so you can have your own set(s) of personal man
       pages and choose whatever program you like to display  the
       formatted  pages.  If section is specified, man only looks
       in that section of the manual.

Le pagine di documentazione ottenute con man hanno un formato prefissato in modo da facilitarne la consultazione. Esse sono divise in paragrafi come nell'esempio precedente.

Alcuni paragrafi sono presenti in tutte le pagine, altri possono essere presenti o meno a seconda dell'argomento.

Ecco un elenco dei paragrafi più comuni:

NAME
Il nome del comando o del programma documentato ed una breve descrizione della funzione.

SYNOPSYS (talvolta: SYNTAX)
Il modo di uso del comando con la posizione degli argomenti e delle opzioni.

DESCRIPTION
Una descrizione estesa del comando o programma.

OPTIONS
L'elenco completo di tutte le opzioni con il loro significato e modo di impiego.

ENVIRONMENT
L'elenco delle variabili di "environment" utilizzate dal comando o programma.

SEE ALSO
Eventuale lista di comandi "collegati".

BUGS
L'elenco di "bug" conosciute e non corrette.

FILES
L'elenco dei files di configurazione, temporanei, etc. necessari per il funzionamento del comando.

Per facilitare la ricerca dell'informazione i files di documentazione di man sono suddivisi in sezioni a seconda dell'argomento:

Contiene la documentazione dei comandi di Unix di uso per l'utente comune.
Contiene la documentazione delle routines della libreria standard Unix.
Contiene la documentazione delle routines delle librerie dei linguaggi di programmazione ed altri packages.
Contiene la documentazione sui files "speciali" (cioè quelli contenuti nella directory /dev).
Contiene la documentazione sui vari formati di files utilizzati dai programmi e dalle procedure di sistema.
Contiene la documentazione sui giochi.
Miscellanea. Contiene la documentazione su vari aspetti del sistema che non rientrano in nessun'altra categoria.
Contiene la documentazione dei comandi di Unix di uso dell'amministratore di sistema.

A queste sezioni se ne aggiungono di solito altre destinate alle informazioni "locali" ovvero quelli che non appartengono al sistema operativo ma sono state aggiunte dall'amministratore di sistema per uso esclusivamente locale.

È possibile indicare, nel comando man, di limitare la ricerca ad un'unica sezione:

laptop-lfini-134:man 4 full

Ricerca per argomento

Il sistema man implementa una semplice forma di ricerca di argomenti collegati.

Il comando può essere utilizzato come nel seguente esempio:


laptop-lfini-113:man -k formatting 

amslatex (1)         - structured text formatting and typesetting
amstex (1)           - structured text formatting and typesetting
f2c (1)              - Convert Fortran 77 to C or C++ .
ftl_format (8)       - Flash Translation Layer formatting utility
groff (1)            - front end for the groff document formatting system
groff_me (7)         - troff macros for formatting papers
lamstex (1)          - structured text formatting and typesetting
latex (1)            - structured text formatting and typesetting
localeconv (3)       - get numeric formatting information
tex, virtex (1)      - text formatting and typesetting

Il risultato è l'elenco di tutti i files di documentazione del sistema man che contengono la stringa "formatting" nel paragrafo NAME.

Anche in questo caso si tratta di un meccanismo assai semplice, ma che risolve gran parte dei problemi di reperimento della documentazione.

Implementazione e dettagli

Struttura dei files

Il sistema man è costituito da files (uno per ogni voce) contenuti solitamente in una struttura di directories del tipo:

/usr/man -+- man1 -+- ac.1
          |        +- acm.1
          |        .
          |        .
          |
          +- man2 -+- accept.2
          |        .
          .
          .
          +- man8

Oltre alla directory citata le pagine di manuale vengono cercate in un elenco di directory contenuto nella variabile MANPATH.

Sulla mia installazione RedHat 5.1 sono definite anche: /usr/X11R6/man, /usr/local/man

I files di man sono scritti in groff il linguaggio di "typesetting" classico di Unix.

L'uso di groff consente di utilizzare elementi di evidenziazione del testo (grassetto, sottolineature) per aumentare la leggibilità dei documenti.

Il comando man provoca quindi l'attivazione del programma groff per "formattare" il testo del file di documentazione e successivamente lancia un programma di paginazione (solitamente more) per visualizzarlo sul video.

Lo stesso comando consente di ottenere copie stampabili delle pagine di manuale. I manuali operativi di gran parte dei sistemi Unix consistono essenzialmente nella raccolta delle stampe dei files di documentazione.

Ad esempio prendiamo il file di documentazione del comando arch. Questo viene visualizzato sullo schermo come segue:


ARCH(1)             Linux Programmer's Manual             ARCH(1)

NAME
       arch - print machine architecture

SYNOPSIS
       arch

DESCRIPTION
       arch is equivalent to uname -m

       On  current  Linux  systems,  arch  prints  things such as
       "i386" or "i486".

SEE ALSO
       uname(1), uname(2)

Il file corrispondente è il seguente:


.\" arch.1 -- 
.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
.\" Public domain: may be freely distributed.
.TH ARCH 1 "4 July 1997" "Linux 2.0" "Linux Programmer's Manual"
.SH NAME
arch \- print machine architecture
.SH SYNOPSIS
.B arch
.SH DESCRIPTION
.B arch
is equivalent to
.B uname -m

On current Linux systems,
.B arch
prints things such as "i386" or "i486".
.SH SEE ALSO
.BR uname (1) ", " uname (2)

Pagine preformattate

Per motivi "storici" dovuti al fatto che in passato era importante minimizzare il carico di CPU nell'esecuzione dei comandi, il sistema man è corredato di un metodo automatico per "preformattare" i files di documentazione.

Ciò aveva lo scopo di evitare di lanciare il programma di formattazione groff ogni volta che veniva impartito un comando man.

Il meccanismo funziona come segue:

La prima volta che viene usato il comando man per un particolare comando viene generato il testo "formattato" mediante groff per la visualizzazione.
Tale testo viene visualizzato ed anche memorizzato su un file, con lo stesso nome del file "sorgente", sulla directory: /usr/man/cat1/ (qui si suppone che il comando faccia parte della sezione 1).
Ogni volta successiva che viene impartito lo stesso comando man non è più necessario il passo per la formattazione perché il risultato è già disponibile nel file memorizzato.

Si tratta di un tipico caso in cui si "spende" spazio disco per "risparmiare" tempo di CPU.

È evidente che il metodo è tanto più conveniente quante più sono numerose le richieste di visualizzazione di un particolare file di documentazione, ed è quindi più indicato per sistemi con molti utenti.

Quando un sistema ha pochi utenti o comunque poche richieste di tipo man oppure è "abbastanza" veloce (cioè può formattare un file man in tempi non avvertibili come ritardo), allora è inutile "sprecare" lo spazio disco per i files preformattati. In tal caso è sufficiente cancellare le directories cat1 cat2, etc. da /usr/man per disabilitare il meccanismo descritto.

database whatis

Il meccanismo che consente il funzionamento del comando apropos o dell'equivalente man -k è anch'esso molto semplice: tutte le linee di descrizione dei comandi vengono raccolte in un file di testo sul quale viene effettuata una ricerca con modalità del tutto analoga a quelle del comando grep.

Perché i comandi possano funzionare occorre dunque aver preventivamente generato il relativo "database" mediante il comando makewhatis.

Questa operazione deve essere ripetuta ogni volta che viene aggiunto o tolto un file di documentazione.

Alcuni dati

Per completezza nella seguente tabella sono riportati il numero di files e l'occupazione di disco per ciascuna delle sottodirectory che fanno parte del sistema man in una installazione standard di RedHat 5.1 con un po' di software aggiuntivo installato (octave):



      Sezione   Num.Files    Kbytes
===================================
/usr/man/man1         887      7429  
/usr/man/man2         230       736  
/usr/man/man3        1243      3343  
/usr/man/man4          47       284  
/usr/man/man5          77       696     
/usr/man/man6          54       346     
/usr/man/man7          22       209     
/usr/man/man8         274      1328    
/usr/man/mann         205      2481    

/usr/X11R6/man/man1   266      2689    
/usr/X11R6/man/man3   974      2933    
/usr/X11R6/man/man4     2        12      
/usr/X11R6/man/man5     3        56      
/usr/X11R6/man/man6    11        46      

/usr/local/man/man1     3         5

/usr/man/whatis                 138
-----------------------------------
Totali               4295     22731

- Documentazione in Linux - Texinfo

Clueless - Copertina - RPM