Man (Unix)

Da Wikipedia, l'enciclopedia libera.

The man page on man

La maggior parte dei sistemi operativi UNIX e Unix-like hanno un'ampia documentazione nota come man pages (abbreviazione di "manual pages" ovvero pagine di manuale). Il comando Unix utilizzato per mostrarle è man. Ogni pagina è un documento esplicativo di un comando, che può contenere riferimenti ad altre pagine.

Indice

1 Uso
2 Le sezioni del manuale
3 Layout
4 Voci correlate
5 Collegamenti esterni
- 5.1 Repositories delle pagine di manuale

[modifica] Uso

Per leggere una pagina dal manuale, si può utilizzare il comando

man <page_name>

sul prompt della shell, per esempio "man ftp". Le pagine sono tradizionalmente riferite utilizzando la notazione "nome(sezione)", per esempio, ftp(1).

Lo stesso nome di pagina può apparire in più di una sezione di un manuale. Questo può succedere quando il nome di una system call, un comando utente o un macro package sono in conflitto. Due esempi sono man(1) e man(7), oppureexit(1) and exit(3). La sintassi per accedere ad una sezione del manuale che non sia di default varia tra le differenti implementazioni di man. Su Linux e *BSD, ad esempio, la sintassi per leggere printf(3) è:

man 3 printf

Lo UNIX Programmer's Manual ("Manuale Unix per Programmatori") fu pubblicato per la prima volta il 3 novembre 1971. Comunque, le pagine di manuale non furono disponibili online fino alla release della settima edizione nel 1979. A quel tempo, la disponibilità della documentazione online attraverso il sistema delle man page fu considerato come un grande passo avanti. Oggi giorno, virtualmente ogni applicazione Unix da linea di comando è corredata della sua pagina di manuale, e molti utenti Unix percepiscono l'assenza di tali pagine come indice di bassa qualità del software. Infatti, alcuni progetti, come Debian, si preoccupano di scrivere man page per quei programmi che ne sono carenti. Poche alternative a man hanno riscosso la stessa popolarità, una possibile eccezione si fa per "info" del progetto GNU, un primo sistema di ipertesto molto semplice ma efficace.

Tuttavia, il fatto di prevedere una singola pagina per ogni applicazione, l'assenza di una classificiazione in sezioni e altre pecche, dovute allo sforzo di mantenere il sistema di gestione delle pagine estremamente semplice, hanno motivato lo sviluppo di sistemi di documentazione alternativi, come il suddetto sistema info-

La maggior parte di applicazioni Unix dotate di GUI (in particolare quelle realizzate utilizzando gli ambienti di sviluppo di GNOME o KDE) ora prevedono una documentazione per l'utente finale in HTML e includono visualizzatori di HTML embedded per leggere l'help direttamente senza uscire dall'applicazione.

Tipicamente le pagine di man sono scritte in inglese. Traduzioni in altri linguaggi sono a volte disponibili nei sistemi.

Il formato di default di una pagina è il troff, con una struttura di tipo macro package (orientata all'apparenza) oppure alternativamente mdoc (orientata alla semantica). Questo rende possibile realizzare una pagina di manuale in PostScript, PDF e vari altri formati per la visualizzazione o la stampa (sebbene la maggior parte degli utenti preferisca ancora l'interfaccia di default del terminale).

[modifica] Le sezioni del manuale

Il manuale è in genere diviso in otto sezioni numerate, organizzate come segue (su Unix BSD e Linux):

Section	Description
1	Comandi generali
2	System call
3	Funzioni della libreria C
4	File speciali (tipicamente i device, quelli trovati in /dev) e driver
5	Formato di file e convenzioni
6	Giochi e screensaver
7	Miscellanea
8	Amministrazione del sistema comandi e demoni

Lo UNIX System V utilizza uno schema di numerazione simile, eccetto la sezione 4, che è per i formati di file, la sezione 5, che contiene i miscellanea, e la sezione 7, che è per i file speciali.

In alcuni sistemi sono disponibili alcune delle seguenti sezioni:

Section	Description
0	Header file della libreria C
9	Routine del Kernel
n	Parole chiave di Tcl/Tk
x	Il sistema X Window

Le sezioni sono ulteriormente suddivise per mezzo di una lettera di suffisso, come la sezione 3C per le chiamate di libreria C, 3M per la libreria di matematica, e così via. Una conseguenza di cià è che la sezione 8 (per i comandi di amministrazione del sistema) sono talvolta rimandati alla sottosezione 1M della sezione dei comandi generali. Altri suffissi delle sottosezioni hanno un significato generale tra le sezioni:

Subsection	Description
p	specifiche POSIX
x	documentazione per il sistema X Window

Per vedere le varie opzioni che si possono dare al comando man, digitare il comando man man.

[modifica] Layout

Tutte le pagine di manuale seguono un layout comune, che è ottimizzato per la presentazione su semplice testo in ASCII - possibilmente senza alcuna forma di evidenziazione o controllo dei font. Le seguenti intestazioni delle sezioni sono quasi sempre presenti e sono sempre in questo ordine:

NAME - Il nome del comando o della funzione, seguito da una descrizione su una linea di che cosa fa il comando.
SYNOPSIS - Nel caso di un comando, dà una formale descrizione di come fare a eseguirlo e di quali opzioni poter specificare. Per le funzioni di programmazione, c'è una lista dei parametri che la funzione accetta e in quale header file essa viene definita. Per gli utenti esperti, ciò può costituire tutta la documentazione di cui essi hanno bisogno.
DESCRIPTION - Una descrizione testuale del funzionamento del comando o della funzione.
EXAMPLES - Qualche esempio di uso più comune
SEE ALSO - Una lista di comandi o funzioni simili o correlati ad essi.

Possono essere presenti anche altre sezioni, ma non sono ben standardizzate. Esempi comuni sono: OPTIONS, EXIT STATUS, ENVIRONMENT, KNOWN BUGS, FILES, AUTHOR, REPORTING BUGS and COPYRIGHT.