Penso abbiate tutti presente l”utilissima funzione “man”. Man sta per manual anche se io spesso penso derivi da manna in quanto il 90% dei problemi li risolvo grazie a lei. In GNU/Linux la totalità dei programmi ha la sua manpage associata e, grazie ad essa, possiamo sapere vita morte e miracoli di ogni eseguibile o comando sia presente sulla nostra macchina. Ma non solo! Man racchiude anche la sintassi e la semantica completa di praticamente tutte le funzioni e le system call unix. Indispensabile per chi programma in C/C++.

Così noi stiamo preparando il nostro programmino. E perché il nostro dovrebbe essere da meno? Perché il nostro applicativo non deve avere la sua manpage? Perché gettare nella disperazione i nostri utenti?

Infatti non dobbiamo. Impariamo quindi a fare la manpage per il nostro programma!

Creare una manpage è decisamente semplice. Innanzitutto impariamo quelle 7 istruzioni di markup che ci servono:

• .TH – Indica il titolo della manpage
• .SH – Indica il titolo della sezione
• .SS – Indica il titolo della sotto-sezione
• .pp – Indica l’inizio di un nuovo paragrafo
• .B – Mostra il testo in grassetto
• .I – Mostra il testo in corsivo
• .” – Indica che la riga corrente è un commento (non viene visualizzata nel manuale)

Ora siamo praticamente pronti. Sappiamo tutto quello che ci serve. Apriamo il nostro editor di testo e iniziamo a scrivere la nostra manpage come in questo esempio:

.TH MioSoftware
.SH NAME
MioSoftware Super Calculator
.SH DESCRIPTION
.I MioSoftware
è un programma troppo bello!
.SH URL

http://www.linuxqualityhelp.it

E così via. Fate attenzione che ogni tag deve capitare come primo comando della riga.

A questo punto salviamo il nostro file come, ad esempio, mioprogramma.txt

Adesso dobbiamo copiarlo nella cartella di sistema affinché venga rilevato dal sistema. In debian questa cartella è /usr/share/man

All’interno di questa cartella sono presenti diverse sotto cartelle per indicare le varie “categorie” di manuali. Queste cartelle sono segnate da man1, man2, man3 e così via. Le categorie associate ad ogni numero variano da sistema a sistema ma generalmente sono:

• 0 – File Header
• 1 – Comandi Standard (quindi i normali eseguibili)
• 2 – Kernel System Call
• 3 – Funzioni Standard della libreria C
• 4 – Device speciali
• 5 – Formati di file e convenzioni
• 6 – Giochi
• 7 – Varie, ad esempio informazioni sugli standard (ISO)
• 8 – Comandi root
• 9 – Dettagli  del Kernel

Noi per esempio inseriremo la nostra man page nella categoria 1. Per farlo basta dare da root:

# cp mioprogramma.txt /usr/share/man/man1/mioprogramma.1

A questo punto abbiamo finito. Per vedere il risultato basta dare:

$ man mioprogramma

E crogiolarsi nella senzazione di “professionalità” che la manpage da al vostro software.

Penso abbiate tutti presente l”utilissima funzione “man”. Man sta per manual anche se io spesso penso derivi da manna in quanto il 90% dei problemi li risolvo grazie a lei....