Man pages

Il comando man

Man è uno strumento assai potente ma è bene chiarirne l’uso: i Man non sono una raccolta di tutorial e non servono per imparare l’uso dei comandi, sono guide veloci e dettagliate che presuppongono la conoscenza dell’argomento e del tool in discussione. I manuali  non  sono  lo  strumento  indicato  per  imparare  da  zero,  per  questo  sono più

adatti i classici tutorial disponibili sul web. Anche la qualità, nelle pagine dei manuali, è molto variabile: alcune sono ottimamente scritte, altre inaccurate o incomplete.  I  manuali sono normalmente scritti dagli stessi autori del programma e spesso non ripongono nello scrivere documentazione la stessa attenzione profusa nella programmazione.

Veniamo al funzionamento vero e proprio del comando man.

Il modo più semplice di utilizzare questo potente strumento è digitare il comando man seguito dal comando su cui ci si vuole documentare, sul relativo file di configurazione o altra parola chiave significativa:

$ man cp NAME

cp – copy files and directories

SYNOPSIS

cp [OPTION]… [-T] SOURCE DEST

cp [OPTION]… SOURCE… DIRECTORY cp [OPTION]… -t DIRECTORY SOURCE…

Ognuna delle pagine di manuale ricade sotto una delle 9 categorie riepilogate  nella tabella 1.

Tabella 1 categorizzazione delle pagine di man

L’utilità di questa tabella si evidenzia in caso di argomenti omonimi. ad esempio per la parola chiave passwd:

NOME

passwd – cambia la password utente

SINOSSI

passwd [opzioni] [LOGIN]

DESCRIZIONE

Il comando passwd permette di cambiare le password per un account utente.

$ man                5 passwd

PASSWD(5)       Linux Programmer’s Manual              PASSWD(5)

NOME

passwd – file delle password DESCRIZIONE

Passwd è un file di testo che contiene un elenco degli account sul  sistema,  e  per  ciascuno di questi riporta alcune informazioni utili come user ID, group ID, home  directory, ecc.

Nell’esempio precedente, invocando la pagina di manuale con tanto di richiamo alla categoria 5 (il cinque fra “man” e “passwd” del secondo esempio), è stata richiamata la pagina della categoria “formati dei file” (relativa al file /etc/passwd), anzichè quella più comunemente richiesta della categoria 1, ossia “programmi eseguibili e comandi  di  shell” (relativa all’eseguibile /bin/passwd). Man stabilisce la priorità delle categorie secondo quanto impostato in /etc/man.conf: un utente alle prime armi non avrà probabilmente bisogno nè di modificare questo file, nè di specificare la categoria al momento dell’invocazione di man, poichè tipicamente avrà  bisogno  delle informazioni che il sistema man saprà restituire in automatico, ma un rapido accenno alla questione era almeno doveroso.

Struttura delle pagine di man

La struttura delle pagine di man segue un certo schema convenzionale che include  di  base diverse sezioni, ognuna delle quali ha una specifica funzione. Quelle più comuni sono:

• Nome: ogni pagina di manuale comincia con la dichiarazione del comando, chiamata o file in trattazione, il tutto seguito da una brevissima descrizione.

$ man ls

LS(1)           User Commands       LS(1)                 NAME ls – list directory contents

• Sinossi: La sinossi presenta brevemente come il comando va usato. Eventuali parametri opzionali saranno racchiusi fra parentesi quadre, mentre le parentesi tonde indicheranno la possibilità di inserire un set di elementi come argomento   al comando
  • Descrizione: Una breve descrizione su ciò che l’applicazione, file o file di configurazione fa o non fa. La lunghezza di questa sezione può variare da poche righe a diverse pagine, ma solitamente si attesta alle dimensioni di un tipico sommario.
  • Opzioni: Questa sezione estende e spiega le opzioni menzionate nella sinossi. Solitamente ogni opzione si presenta paragrafata singolarmente, ed include una spiegazione più o meno dettagliata delle funzionalità.
  • Files: Questa sezione elenca i file associati all’argomento in trattazione: ad esempio nel caso di un file eseguibile, verranno qui menzionati i relativi file di configurazione.
  • See also: Questa sezione fornisce eventuali informazioni correlate all’argomento  in trattazione disponibili altrove. Ad esempio, la pagina man di fdisk (uno strumento per partizionare i dischi), indica come ulteriori riferimenti le pagine   per cfdisk, sfdisk, parted ed altri strumenti utili allo stesso scopo.
  • Bugs: La sezione dedicata agli eventuali difetti e limitazioni relative all’argomento in trattazione o nel migliore dei casi dichiara che non sono noti difetti allo stato attuale.
  • Storico: Alcuni tool possono includere questa sezione per spiegare l’evoluzione storica dell’argomento in trattazione, come le date di inizio del progetto ed eventuale passaggi fondamentali degni di nota.
  • Autore: La sezione con i riferimenti ed i contatti dell’autore del programma o progetto in questione.

Oltre questo schema classico, possono essere presenti altre sezioni, a discrezione dell’autore del programma e/o della relativa pagina di manuale.

Navigare tra le pagine di man

Tipicamente il sistema man fa uso dello strumento less per scorrere le pagine di documentazione, ossia un impaginatore testuale funzionante via terminale. Le sue funzionalità includono lo spostamento avanti e indietro nel testo, la ricerca e lo spostamento a determinate righe del documento. La tabella 2 riepiloga i comandi principali

Tabella 2 – tasti di navigazione del comando less

Il comando less è invocato automaticamente dal comando man ma può essere utilizzato anche per leggere altri file di testo appendendo al comando less il file da aprire. Ovviamente i comandi di navigazione riepilogati in tabella 2.2B  saranno  altrettanto  validi.