Comment créer une page de manuel sous Linux

Souhaitez-vous donner une allure professionnelle à votre nouveau programme Linux ? Offrez-lui une page de manuel. Nous allons vous montrer la méthode la plus simple et rapide pour y parvenir.

Les pages de manuel

Il y a une part de vérité dans la vieille blague Unix qui dit que « la seule commande que vous avez besoin de connaître est `man` ». Les pages de manuel sont une mine d'informations, et elles devraient être le premier endroit où vous vous tournez pour en apprendre davantage sur une commande.

Fournir une page de manuel pour un utilitaire ou une commande que vous avez développée transforme votre code en un véritable package Linux. Les utilisateurs s'attendent à ce qu'une page de manuel soit disponible pour un programme conçu pour Linux. Si votre logiciel est compatible avec Linux, une page de manuel est indispensable pour que votre programme soit pris au sérieux.

Traditionnellement, les pages de manuel étaient rédigées en utilisant un ensemble de macros de formatage. Lorsque vous utilisez `man` pour ouvrir une page, il appelle Groff afin de lire le fichier et générer une sortie formatée, en fonction des macros présentes dans le fichier. Cette sortie est ensuite redirigée vers `less`, puis affichée à l'écran.

À moins de créer régulièrement des pages de manuel, en écrire une en insérant manuellement les macros est un processus fastidieux. Le simple fait de créer une page de manuel qui s'analyse correctement et qui a une apparence soignée peut devenir un obstacle à votre objectif initial : fournir une description concise, mais complète, de votre commande.

Vous devriez vous concentrer sur le contenu, et non sur une lutte acharnée avec un ensemble obscur de macros.

pandoc à la rescousse

Le programme pandoc permet de lire des fichiers Markdown et d'en générer de nouveaux dans environ 40 langages de balisage et formats de documents différents, y compris le format de page de manuel. Cela transforme complètement le processus de rédaction d'une page de manuel, en vous évitant de vous battre avec des hiéroglyphes.

Pour commencer, vous pouvez installer pandoc sur Ubuntu avec cette commande :

sudo apt-get install pandoc

Sur Fedora, la commande à utiliser est la suivante :

sudo dnf install pandoc

Sur Manjaro, saisissez :

sudo pacman -Syu pandoc

Sections d'une page de manuel

Les pages de manuel contiennent des sections qui suivent une convention de nommage standard. Les sections dont votre page de manuel a besoin sont déterminées par la complexité de la commande que vous décrivez.

Au minimum, la plupart des pages de manuel comprennent ces sections :

Nom : Le nom de la commande et une courte description de sa fonction.
Synopsis : Une brève description des différentes façons de lancer le programme. Cela inclut les types de paramètres de ligne de commande acceptés.
Description : Une description détaillée de la commande ou de la fonction.
Options : Une liste des options de ligne de commande et de leur effet.
Exemples : Quelques exemples d'utilisation courante.
Valeurs de sortie : Les codes de retour possibles et leur signification.
Bugs : Une liste des bugs et des comportements inattendus connus. Parfois, elle est complétée (ou remplacée) par un lien vers le système de suivi des problèmes du projet.
Auteur : Le ou les personnes qui ont écrit la commande.
Copyright : Votre message de copyright, qui inclut généralement le type de licence sous laquelle le programme est publié.

Si vous consultez certaines pages de manuel plus complexes, vous remarquerez de nombreuses autres sections. Par exemple, essayez `man man`. Vous n'êtes pas obligé de toutes les inclure, seulement celles qui vous sont vraiment utiles. Les pages de manuel ne sont pas un endroit pour faire du remplissage.

Voici quelques autres sections que vous rencontrerez fréquemment :

Voir aussi : D'autres commandes liées au sujet qui pourraient être utiles ou pertinentes.
Fichiers : Une liste des fichiers inclus dans le package.
Mises en garde : D'autres points à connaître ou à surveiller.
Historique : L'historique des modifications de la commande.

Sections du manuel

Le manuel Linux est composé de toutes les pages de manuel, qui sont ensuite divisées en sections numérotées :

1. Programmes exécutables : Ou commandes shell.
2. Appels système : Fonctions fournies par le noyau.
3. Appels de bibliothèque : Fonctions contenues dans les bibliothèques de programmes.
4. Fichiers spéciaux.
5. Formats de fichiers et conventions : Par exemple, « /etc/passwd ».
6. Jeux.
7. Divers : Packages de macros et conventions, comme Groff.
8. Commandes d'administration système : Généralement réservées à l'utilisateur root.
9. Routines du noyau : Généralement non installées par défaut.

Chaque page de manuel doit indiquer à quelle section elle appartient, et elle doit également être stockée à l'emplacement approprié pour cette section, comme nous le verrons plus loin. Les pages de manuel des commandes et des utilitaires appartiennent à la première section.

Le format d'une page de manuel

Le format de macro Groff n'est pas facile à interpréter visuellement. En revanche, le Markdown est un jeu d'enfant.

Vous trouverez ci-dessous un aperçu d'une page de manuel au format Groff.

La même page est affichée ci-dessous, cette fois au format Markdown.

Préambule

Les trois premières lignes forment ce que l'on appelle le préambule. Elles doivent toutes commencer par un signe pourcentage (%), sans espace au début, mais avec un espace après, suivi de :

Première ligne : Le nom de la commande, suivi de la section du manuel entre parenthèses, sans espaces. Le nom devient les sections gauche et droite de l'en-tête de la page de manuel. Par convention, le nom de la commande est en majuscules, même si vous en trouverez beaucoup qui ne le sont pas. Tout ce qui suit le nom de la commande et le numéro de section manuelle devient la section gauche du pied de page. Il est pratique de l'utiliser pour le numéro de version du logiciel.
Deuxième ligne : Le ou les noms des auteurs. Ils sont affichés dans une section "Auteurs" générée automatiquement dans la page de manuel. Vous n'êtes pas obligé d'ajouter une section "Auteurs", incluez simplement au moins un nom ici.
Troisième ligne : La date, qui devient également la partie centrale du pied de page.

Nom

Les sections sont indiquées par des lignes commençant par un signe dièse (#), qui est le balisage indiquant un en-tête en Markdown. Le signe dièse (#) doit être le premier caractère de la ligne, suivi d'un espace.

La section "Nom" contient une seule ligne comprenant le nom de la commande, un espace, un tiret (-), un espace, puis une très courte description de la fonction de la commande.

Synopsis

Le synopsis contient les différentes manières d'utiliser la ligne de commande. La commande peut accepter un motif de recherche ou une option de ligne de commande. Les deux astérisques (**) de chaque côté du nom de la commande indiquent que le nom sera affiché en gras sur la page de manuel. Un seul astérisque de chaque côté du texte indique que le texte sera souligné.

Par défaut, un saut de ligne est suivi d'une ligne vide. Pour forcer un retour à la ligne sans ligne vide, vous pouvez utiliser une barre oblique inverse de fin (\).

Section Description d'une page de manuel en Markdown.

La description explique ce que fait la commande ou le programme. Elle doit couvrir les détails importants de manière concise. N'oubliez pas que vous n'écrivez pas un guide de l'utilisateur.

L'utilisation de deux signes numériques (##) au début d'une ligne crée un en-tête de niveau deux. Vous pouvez les utiliser pour diviser votre description en sections plus petites.

Section Options d'une page de manuel en Markdown.

La section "Options" contient une description de toutes les options de ligne de commande pouvant être utilisées avec la commande. Par convention, elles sont affichées en gras, donc incluez deux astérisques (**) avant et après chacune d'elles. Incluez la description textuelle des options sur la ligne suivante et commencez-la par deux points (:), suivis d'un espace.

Si la description est suffisamment courte, `man` l'affichera sur la même ligne que l'option de ligne de commande. Si elle est trop longue, elle s'affichera sous forme de paragraphe en retrait, qui commence sur la ligne sous l'option de ligne de commande.

Section Exemples d'une page de manuel en Markdown.

La section "Exemples" contient une sélection de différents formats de ligne de commande. Notez que nous commençons les lignes de description par un deux-points (:), tout comme dans la section "Options".

Section Valeurs de sortie d'une page de manuel en Markdown.

Cette section répertorie les valeurs de retour que votre commande renvoie au processus appelant. Il peut s'agir du shell si vous l'avez appelée depuis la ligne de commande, ou d'un script si vous l'avez lancée depuis un script shell. Nous commençons également les lignes de description par deux points (:) dans cette section.

Section Bugs d'une page de manuel en Markdown.

La section "Bugs" répertorie les bogues connus, les pièges ou les comportements inattendus que les utilisateurs doivent connaître. Pour les projets open source, il est courant d'inclure ici un lien vers le système de suivi des problèmes du projet pour vérifier l'état de tout bug ou en signaler de nouveaux.

Section Copyright d'une page de manuel en Markdown.

La section "Copyright" contient votre déclaration de copyright et, généralement, une description du type de licence sous laquelle le logiciel est publié.

Un flux de travail efficace

Vous pouvez modifier votre page de manuel dans votre éditeur de texte préféré. La plupart des éditeurs qui prennent en charge la coloration syntaxique identifieront le Markdown et colorieront le texte pour mettre en évidence les en-têtes, le texte en gras et le texte souligné. C'est une bonne chose, mais vous ne visualisez pas une page de manuel rendue, ce qui est le test ultime.

pandoc ms.1.md -s -t man | /usr/bin/man -l -

pandoc ms.1.md -s -t man | /usr/bin/man -l - dans une fenêtre de terminal.

Une fois que vous avez utilisé cette commande, vous pouvez appuyer sur la flèche vers le haut pour la répéter, puis appuyer sur Entrée.

Cette commande appelle pandoc sur le fichier Markdown (ici, il s'appelle "ms.1.md") :
L'option `-s` (standalone) génère une page de manuel complète de haut en bas, plutôt que juste du texte au format man.
L'option `-t` (type de sortie) avec l'opérateur `man` indique à pandoc de générer sa sortie au format man. Nous n'avons pas demandé à pandoc d'envoyer sa sortie dans un fichier, elle sera donc envoyée sur la sortie standard (stdout).
Nous envoyons également cette sortie vers `man` avec l'option `-l` (fichier local). Elle indique à man de ne pas chercher dans la base de données man la page de manuel. Au lieu de cela, il doit ouvrir le fichier spécifié. Si le nom du fichier est `-`, `man` prendra ses entrées depuis l'entrée standard (stdin).

En résumé, vous pouvez enregistrer votre fichier depuis votre éditeur et appuyer sur `Q` pour fermer `man` s'il est exécuté dans la fenêtre du terminal. Ensuite, vous pouvez appuyer sur la flèche vers le haut, puis sur Entrée pour voir une version rendue de votre page de manuel, directement à l'intérieur de `man`.

Créer votre page de manuel

pandoc ms.1.md -s -t man -o ms.1

pandoc ms.1.md -s -t man -o ms.1 dans une fenêtre de terminal.

Cela suit la convention qui consiste à nommer la page de manuel d'après la commande qu'elle décrit et à ajouter le numéro de section du manuel comme s'il s'agissait d'une extension de fichier.

manpath

`manpath` dans une fenêtre de terminal.

Les résultats nous donnent les informations suivantes :
`/usr/share/man` : l'emplacement de la bibliothèque standard des pages de manuel. Nous n'ajoutons pas de pages à cette bibliothèque.
`/usr/local/share/man` : Ce lien symbolique pointe vers `/usr/local/man`.
`/usr/local/man` : C'est ici que nous devons placer notre nouvelle page de manuel.

Notez que les différentes sections du manuel sont stockées dans leurs propres répertoires : `man1`, `man2`, `man3`, etc. Si le répertoire de la section n'existe pas, nous devons le créer.

sudo mkdir /usr/local/man/man1

Pour ce faire, nous tapons ce qui suit :

sudo cp ms.1 /usr/local/man/man1

Nous copions ensuite le fichier `ms.1` dans le bon répertoire : `man` s'attend à ce que les pages de manuel soient compressées, nous utiliserons donc `gzip` pour le compresser.

sudo gzip /usr/local/man/man1/ms.1

Enfin, nous mettons à jour la base de données de `man` :

sudo mandb

`sudo mkdir /usr/local/man/man1` dans une fenêtre de terminal.

man ms

`man ms` dans une fenêtre de terminal.

Partie supérieure d'une nouvelle page de manuel.

Partie centrale de la nouvelle page de manuel.

Partie inférieure d'une nouvelle page de manuel.

Nous avons également généré automatiquement une section "Auteurs". Le pied de page inclut le numéro de version du logiciel, la date et le nom de la commande, tels que définis dans le préambule.

Si vous voulez aller plus loin...

Une fois que pandoc a créé votre page de manuel, vous pouvez également modifier directement le fichier au format de macro groff avant de le déplacer vers le répertoire de la page de manuel, puis le compresser avec gzip.