Linux Lexicon — Anatomia di una pagina man

M an pagine sono tipicamente suddivise in una serie di sezioni che descrivono in dettaglio il nome e una descrizione, l'uso e le avvertenze. Le pagine man possono essere difficili da leggere, ma sono risorse preziose che possono essere sfruttate in caso di necessità e non richiedono nemmeno Internet.

NOME
Il primo è l'intestazione del nome, e questo lo riassume. Questa sezione include il nome dell'utilità e una breve descrizione.

SINOSSI
Ci sono vari gradi di leggibilità da una pagina man all'altra, ma una cosa è certa, la parte più difficile è in genere decifrare una sinossi pelosa. Esistono diverse convenzioni per indicare le informazioni richieste per un determinato comando. Queste convenzioni sono costituite da parentesi e parentesi diverse, nonché da altre forme di notazione. Tutte queste diverse convenzioni possono essere estremamente confuse per un principiante e ancora scoraggiante per qualcuno che è esperto ma non esperto nell'arte dei manuali. Di seguito analizzeremo le parole senza senso in regole digeribili.

Queste regole sono abbastanza semplici, ma diventano più difficili e persino intimidatorie quando vengono utilizzate in definizioni di funzioni lunghe, specialmente quando sono annidate. Quindi, daremo un'occhiata ad alcuni annidamenti di seguito per costruire ciò che abbiamo scomposto.

tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ ARG …]

Il comando tar ha molte opzioni. Vediamo il nome del comando tar in grassetto perché dovrebbe essere digitato come mostrato. Quindi vediamo le parentesi aperte con opzioni separate da tubi che indicano che siamo limitati a quelli e dobbiamo sceglierne solo uno. Poi ci sono i flag opzionali, possiamo usare qualsiasi numero, anche se potrebbero non funzionare tutti insieme, leggere più avanti nella pagina man farà luce su qualsiasi potenziale conflitto di opzioni. E, infine, abbiamo l'argomento ripetibile, nel caso di tar questo per i file su cui stai operando.

su [opzioni] [-] [ utente [ argomento …]]

Di nuovo, vediamo su bold perché è il nome del comando. In secondo luogo, vediamo che nessun flag è effettivamente specificato, solo che sono opzionali. In terzo luogo, è specificato un unico flag, ma anch'esso è facoltativo. Infine, vediamo un argomento facoltativo che è ripetibile all'interno di un argomento facoltativo. Ora, ciò che prima sembrava molto misterioso ha più senso.

whois [{-h|–host } HOST ] [{-p|–port} PORT ] [-abBcdGHKlLmMrRx] [-g SOURCE:FIRST-LAST ] [-i ATTR [, ATTR ]…] [-s SOURCE [, FONTE ]…] [-T TIPO [, TIPO ]…] [–dettagliato] OGGETTO

Questo è particolarmente denso. Copialo nel tuo editor di testo preferito e aggiungi degli spazi extra se ti aiuta a leggerlo. Dopo aver scansionato questo, dovresti iniziare a vedere un paio di schemi. Le porzioni host e port utilizzano la stessa formattazione per la forma breve e lunga dell'opzione seguita dall'argomento per tale opzione, pur essendo entrambe facoltative. Quindi vediamo la stringa di flag opzionali. Il prossimo passo sui sorgenti dal primo all'ultimo è la sintassi che ci si aspetta da whois che viene spiegata più avanti nella pagina man. Ora vediamo questa tripletta di flag opzionali che accettano un singolo argomento o argomenti facoltativi ripetuti, questo è il tipo di combinazione delle convenzioni che all'inizio può essere molto difficile da afferrare completamente. Infine ci sono opzioni dettagliate e l'oggetto (l'host/dominio).

Ed ecco come leggere la sinossi di una pagina man. Ci sono alcune altre convenzioni, ma sono troppo oscure per essere trattate in questo articolo.

DESCRIZIONE
Questo è generalmente il punto in cui viene delineato l'uso previsto del programma o dell'utilità. Alcuni manuali saranno molto più dettagliati sotto questo titolo rispetto ad altri.

OPZIONI
Ricordi tutti quei flag e diversi argomenti che potrebbero essere facoltativi o obbligatori? Qui è dove vengono spiegati tutti. Di solito ci sono buone informazioni qui ed è spesso dove troverai la convenzione <argomento>, che indica che un dato flag richiede un argomento corrispondente. A volte scoprirai che le opzioni saranno nella parte della descrizione perché non ci sono regole rigide che definiscono le pagine man, solo convenzioni e la volontà di conformarsi agli standard.

ESEMPI
Questa è una delle parti più pratiche che purtroppo non è inclusa in tutti i manuali. Scoprirai anche che la quantità di informazioni e il numero di esempi varia in modo significativo e non tutti gli esempi aiutano effettivamente con l'uso del comando.

Inoltre, troverai regolarmente sezioni per l'autore, informazioni sul copyright, segnalazione di bug e vedi anche (a proposito).

Oltre a questo, ci sono le sezioni formalmente definite delle pagine man come definite di seguito.

Molti comandi non hanno manuali in più di una sezione, ma per quelli che lo fanno, o per alcuni che potrebbero avere un nome ambiguo, puoi specificare la sezione come nell'esempio seguente.

I comandi non sono le uniche cose che hanno manuali come puoi vedere dalle sezioni disponibili. Le chiamate di sistema, i file di configurazione e i dispositivi speciali potrebbero anche avere una pagina man corrispondente. La quantità di informazioni su una tipica installazione Linux solo nelle pagine man è sorprendente, e lo stesso vale per altri sistemi operativi open source simili a UNIX.

Se trovi che la pagina man non è sufficiente e non capisci ancora un comando, controlla sempre online perché molte persone offrono spiegazioni più complete di determinati strumenti, ma anche molte distribuzioni hanno le proprie pagine man per diversi pacchetti software. Una volta che hai scoperto che ti senti a tuo agio con un software, ma ritieni ancora che manchi il manuale, puoi sempre contribuire scrivendo il tuo e inviandoti al rispettivo progetto. La documentazione è spesso la parte più trascurata dei progetti software, quindi anche se non sai scrivere codice, puoi scrivere manuali, articoli Wiki e tutorial per aiutare gli altri.

Ora che conosci l'anatomia di una pagina man, non hai scuse se non RTFM (e questo è il manuale gratuito per quelli di voi sotto i 18 anni) ;)

Leggi anche: Linux Lexicon: usa il comando Watch per eseguire un comando ogni X secondi