ManPage

Comment faire une page man ?

Introduction

Lors de la première étape de mon projet en entreprise, j'ai du faire un script qui récupère et trie des informations. Ce script contient quelques options (-s / -r / -h) qu'il a fallu expliquer et documenter. J'ai donc décidé de créer ma première page de manuel Linux.

Catégorie

La catégorie de votre ManPage, que vous devez préciser dans le .TH, est importante ! Pour savoir la catégorie de la page MAN que vous voulez rédiger : Fiez-vous à ce tableau :

Num. Catégorie Description
1 Commandes générales
2 Appels Systèmes
3 Librairies
4 Fichiers spéciaux et pilotes
5 Formats de fichiers
6 Jeux
7 Divers
8 Commandes d'administration système
o.o

Syntaxe

La syntaxe d'une page de manuel est très particulière : Il faut toujours préciser ce que va être la ligne avant de l'écrire. Par exemple : 

.SH NAME

Cette ligne va précise qu'il s'agit d'un grand titre, d'une nouvelle section (.SH) qui se nommera NAME. C'était un simple exemple, je vais mettre tout ce qu'il faut savoir dans un tableau :

Syntaxe Description
.\" Permet d'ajouter un commentaire 

.\" [Commentaire]
.TH Spécifie ce qui servira d'en-tête à la page de manuel. Voici le format :


.TH [nom du programme] [numéro de section] [centre du pied de page]
[section gauche du pied de page] [section centrale de l'en-tête]
.SH Annonce une nouvelle section, s'affiche comme un grand titre 

.SH [Nom de la section]
.TP Nouveau paragraphe avec titre ! Indente le texte qui vient deux lignes après :) 


.TP
[Titre]
[Texte indenté]
.PP Annonce un nouveau paragraphe.

.PP [Texte]
.B Caractères gras.

.B [Texte]
.I Italique.

.I [Texte]
.SM Taille réduite.

.SM [Texte]
.SB Gras, taille réduite.

.SB [Texte]
o.o

Exemple

En guise d'exemple, je vais insérer le code que j'ai écrit pour créer ma page man.


.TH ARTEMIS 1
.SH NAME
Artemis \- Détruit et reconstruit la base de données Artemis.
.SH SYNOPSIS
.B ./Artemis.sh
[\-r]
[\-\-rapport]
[\-s PATH]
[\-\-structure PATH]
[\-h]
[\-\-help]
.SH DESCRIPTION
.B Artemis
Script permettant de détruire et reconstruire la base de données répertoriant chaque volume ainsi que sa méthode et son lieu de sauvegarde.
.SH OPTIONS
.TP
.BR \-r ", " \-\-rapport
Active la fonction rapport. Un rapport SQL apparaîtra à la fin du script.
.TP
.BR \-s ", " \-\-structure
Permet à l'utilisateur de préciser où trouver le fichier SQL qui servira à créer la base de données après son drop.
.TP
.BR \-h ", " \-\-help
Petite aide syntaxique pour l'utilisateur.

Exemple 2


.TH BLACK_MESA 1
.SH NAME
BLACK_MESA \- Projet en plusieurs étapes qui permettra la migration des anciennes données NetWorker vers NetBackup
.SH SYNOPSIS
.B ./Neverland.sh
[\-N]
[\-\-Neverland]
[\-h]
[\-\-help]
.SH DESCRIPTION ETAPE 1
.B Neverland
Correspond à la première étape de BLACK_MESA : Retire les bandes considérées comme 'inutiles' du robot.
.SH OPTIONS NEVERLAND
.TP
.BR \-N ", " \-\-Neverland
Interroge la base de données BLACK_MESA et trouve les bandes devant être retirées du robot. Une fois trouvées, les bandes sont retirées et placées dans la localisation Neverland.
.TP
.BR \-h ", " \-\-help
Affiche l'aide permettant d'apprendre à utiliser le script Neverland.