Créer une page de manuel Unix en Markdown avec Pandoc

hello1

Dans le monde UNIX, les pages de manuel sont l'une des ressources incontournables. Bien que ces pages de manuel aient relativement peu changé depuis leur première publication en 19711, elles restent une référence inestimable pour toute application en ligne de commande sérieuse ou fonction de bibliothèque standard de C (libc pour les intimes).

Les pages de manuel sont consultables avec la commande man. Le format natif des pages de manuel est roff, un langage d'assemblage de document. Voici un cours extrait de l'entête d'un fichier de manuel :

.TH "HELLO" "1" "December 17, 2021" "Version 1.0" "Hello World User Manuals"
.hy
.SH NAME
.PP
\f[B]hello\f[] \[em] prints Hello, World!
.SH SYNOPSIS
.PP
\f[B]hello\f[] [\f[B]\-o\f[]|\f[B]\-\-out\f[] \f[I]file\f[]]
[\f[I]dedication\f[]]
.PD 0

Pas très sexy.

Par chance, il existe des outils pour convertir un format plus lisible et facile à écrire, comme le Markdown2, en page de manuel.

Pandoc est un logiciel libre de conversion de documents numériques. Il se présente lui-même comme le « couteau Suisse » de la conversion tant il peut passer d'un format à un autre avec facilité. Les formats sont notamment : Markdown, HTML, DocBook, LaTeX, reStructuredText, Textile, syntaxe MediaWiki, syntaxe TWiki, OPML, Org-mode, Txt2tags, Microsoft Word docx, LibreOffice ODT [ ... ].

L'anatomie d'une page de manuel

Les numéros de section

Toutes les pages de manuel résident dans une section numérotée. Une page de manuel est souvent référencée par son nom et son numéro de section comme dans hello(1). La liste des numéros de section peut être trouvée dans la page de manuel de man (man man). Sous Linux, les sections les plus courantes sont :

  • la section 1 : les commandes utilisateur générales ;
  • la section 3 : les fonctions de la libc ;
  • la section 5 pour les formats de fichiers, qui s'applique notamment aux fichiers de configuration.

Chaque section possède une page d'introduction qui présente la section, disponible en tapant :

man <section> intro.

Nom et emplacement des fichiers de manuel

Le nom du fichier d'une page de manuel correspond au nom de la commande et au numéro de section commande.<section>

Par exemple, pour la commande hello, le fichier s'appellerait hello.1. Ne confondez pas .1 avec une extension de fichier ! C'est juste par convention que « l'extension de fichier » d'une page de manuel correspond au numéro de section du manuel auquel elle appartient.

Pour que les pages de manuel soient accessibles depuis n'importe quel emplacement, elles doivent être situées dans un chemin correspondant à ce modèle :

<PREFIX>/share/man/man<SECTION>/<NAME>.<SECTION>

Où :

  • <NAME> est le nom de la page de manuel (c'est-à-dire que vous taperez man <NAME> pour l'afficher) ;
  • <SECTION> est le numéro de section de la page de manuel ;
  • <PREFIX> est un préfixe correspondant au répertoire d'installation sous Unix tels que /usr/local ou /opt.

Si la page de manuel de la commande hello était installée avec un paquet Debian binaire (.deb), la commande serait typiquement déployée dans /usr/bin et la page de manuel dans /usr/share/man/man1/hello.1.gz (fichier compressé avec gzip -9).

Page de manuel type

Chaque page de manuel comporte un entête et un pied de page. Elles sont présentées en sections. Celles-ci sont les plus courantes (les sections en gras représentent les sections mimimales) :

  • NAME - Le nom de la commande ou de la fonction et une description minimale.
  • SYNOPSIS - Une liste succincte d'arguments de ligne de commande ou le prototype de fonction.
  • DESCRIPTION - La majeure partie de la page de manuel. Décrit en détail comment utiliser la commande ou la fonction.
  • OPTIONS - Options de ligne de commande (normalement pour les sections 1 et 8)
  • EXIT STATUS - Le code de retour de la commande (normalement pour les sections 1 et 8)
  • RETURN VALUE - (pour les sections 2 et 3)
  • ERRORS - (pour les sections 2 et 3)
  • ENVIRONNEMENT - Description des variables d'environnement pertinentes qui affectent la fonctionnalité.
  • FILES - Descriptions des noms de fichiers importants, tels que les fichiers de configuration.
  • BUGS - bogues connus.
  • EXAMPLES - Exemples d'utilisation informatifs.
  • AUTHORS - Qui l'a fait ? (son utilisation est découragée)
  • SEE ALSO - Références à d'autres pages de manuel.

L'ordre d'apparition des sections doit être respecté au maximum.

Le modèle Markdown

Bien que vous puissiez écrire votre page de manuel dans n'importe quel format d'entrée que Pandoc supporte, le Markdown est intéressant car Pandoc fournit quelques extensions qui sont particulièrement utiles pour la création de pages de manuel3.

Voici un modèle général pour une commande nommée hello (man 1). Il est tiré et adapté d'un autre article4 (la version originale oublie d'échapper certains caractères) :

% HELLO(1) Version 1.0 | Hello World User Manuals
%
% December 17, 2021

# NAME

**hello** - prints Hello, World!

# SYNOPSIS

| **hello** \[**-o**|**\--out** _file_] \[_dedication_]
| **hello** \[**-h**|**\--help**|**-v**|**\--version**]

# DESCRIPTION

Prints "Hello, _dedication_!" to the terminal. If no dedication is
given, uses the default dedication. The default dedication is chosen by
the following sequence:

 1. Using the environment variable *DEFAULT_HELLO_DEDICATION*
 2. Using the per-user configuration file, *~/.hellorc*
 3. Using the system-wide configuration file, */etc/hello.conf*
 4. Finally, using "world".

# OPTIONS

-h, \--help

:   Prints brief usage information.

-o *FILE*, \--output *FILE*

:   Outputs the greeting to the given filename.

-v, \--version

:   Prints the current version number.

# ENVIRONMENT

**DEFAULT_HELLO_DEDICATION**

:   The default dedication if none is given. Has the highest precedence
    if a dedication is not supplied on the command line.

# FILES

*~/.hellorc*

:   Per-user default dedication file.

*/etc/hello.conf*

:   Global default dedication file.

# BUGS

See GitHub Issues: <https://github.com/[owner]/[repo]/issues>

# AUTHORS

Foobar Goodprogrammer <foo@example.org>

# SEE ALSO

**hi(1)**, **hello(3)**, **hello.conf(4)**

Ce modèle est téléchargable ici

Le bloc de métadonnées

Le Markdown de Pandoc analyse les trois premières lignes en tant que métadonnées si elles sont préfixées par un signe %.

% NOM(#) Pied de page | Entête
% auteur(s)
% date

La première ligne est particulière et obligatoire : c'est le titre du document, et pour les pages de manuel en particulier, il s'agit du nom de la commande en majuscules suivi (sans espace) du numéro de section entre parenthèses.

Le numéro de version peut être mentionné en pied de page, et l'entête (après une barre verticale|) indique généralement à quel ensemble de documentation cette page de manuel appartient.

L'utilisation du champs auteurs est découragée dans les pages de manuel, mais également d'un point de la mise en forme : Pandoc va automatiquement l'ajouter dans une section à la fin du document, on ne peut donc pas respecter l'ordre recommandé et on ne contrôle pas la mise en forme.

A la place, on peut laisser le champs vide, si on souhaite spécifier la date sur la dernière ligne, sinon on ne conserve que la première ligne.

Prenons l'exemple d'une commande nommée hello en version 1.0. C'est une commande générale, donc sa section de manuel est 1. Nous voulons indiquer le numéro de version et la date de révision en pied de page, mais pas l'auteur.

% HELLO(1) Version 1.0 | Hello World User Manuals
% 
% December 17, 2021

Les listes de définitions

La liste de définitions est une extension de Pandoc Markdown. Cette extension est utile pour décrire en détail les arguments de ligne de commande, les fichiers et les variables d'environnement.

-o, \--output *FILE*

: L'option --out modifie la sortie par défaut vers le fichier spécifié...

Notez l'échappement du premier tiret - pour l'option longue.

Les blocs de lignes

Les blocs de lignes, qui préservent les espaces de début de ligne et les sauts de ligne, sont utiles pour écrire des synopsis multilignes. Souvent, plusieurs lignes sont nécessaires s'il y a plusieurs appels mutuellement exclusifs (comme l'utilisation de l'option --help dans la plupart des commandes).

| **hello** \[**-o**|**\--out** _file_] \[_dedication_]
| **hello** \[**-v**|**\--version**]
| **hello** \[**-h**|**\--help**]

Notez les crochets échappés (\[ ... ]). Étant donné que les blocs de ligne contiennent toujours du texte formaté, seuls l'espacement initial et les sauts de ligne sont conservés, toute syntaxe Markdown telle que les crochets de lien est toujours interprétée. Le crochet ouvrant doit être échappé pour éviter que le texte soit interprété comme un texte de lien.

Notez également un échappement supplémentaire pour les options longues (\--), sans lequel un seul tiret (-) serait conservé.

Création de la page de manuel

Maintenant, pour transformer notre Markdown (hello.1.md) en une véritable page de manuel (hello.1), nous exécutons simplement cette commande :

pandoc --standalone --to man hello.1.md --output hello.1

L'option --standalone est nécessaire. Sans cela, Pandoc traduira naïvement le Markdown en troff sans fournir l'en-tête, le pied de page ou la structure générale de la page de manuel à la sortie.

En supposant que le fichier est dans le répertoire courant, on peut l'afficher avec la commande :

man ./hello.1

hello1

Sources et références

Partager cet article ...OU NE PAS.?
Commentaires 0


    Laisser un commentaire
    Le commentaire sera publié sur le site après modération. Entrez votre adresse email pour être notifié lorsque le commentaire est publié ou reçoit une réponse.
    captcha
    captcha