Follow

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. 🙂