Comment créer une page de manuel sous Linux

Vous voulez que votre nouveau programme Linux ait l'air professionnel ? Donnez-lui une page de man . Nous allons vous montrer le moyen le plus simple et le plus rapide de le faire.

Les pages d'homme

Il y a un noyau de vérité dans la vieille blague Unix, "la seule commande que vous devez connaître est man ". Les pages de man contiennent une mine de connaissances et doivent être le premier endroit où vous devez vous tourner lorsque vous souhaitez en savoir plus sur une commande.

Fournir une page de man pour un utilitaire ou une commande que vous avez écrit l'élève d'un morceau de code utile à un package Linux entièrement formé. Les gens s'attendent à ce qu'une page de man soit fournie pour un programme écrit pour Linux. Si vous supportez nativement Linux, une page de man est obligatoire si vous voulez que votre programme soit pris au sérieux.

Historiquement, les pages de man ont été écrites à l'aide d'un ensemble de macros de formatage. Lorsque vous appelez man pour ouvrir une page, il appelle groff pour lire le fichier et générer une sortie formatée, selon les macros du fichier. La sortie est redirigée vers less , puis affichée pour vous.

À moins que vous ne créiez fréquemment des pages de man , en écrire une et insérer manuellement les macros est un travail difficile. Le fait de créer une page de man qui analyse correctement et qui semble correcte peut dépasser votre objectif de fournir une description concise mais complète de votre commande.

Vous devez vous concentrer sur votre contenu, et non sur un ensemble obscur de macros.

CONNEXION: Comment utiliser la commande man de Linux: Secrets cachés et bases

pandoc à la rescousse

Le programme pandoc lit les fichiers de démarquage et en génère de nouveaux dans environ 40 langages de balisage et formats de document différents, y compris celui de la page de man . Il transforme totalement le processus d'écriture des pages de man afin que vous n'ayez pas à vous débattre avec les hiéroglyphes.

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

 sudo apt-get install pandoc 

Sur Fedora, la commande dont vous avez besoin est la suivante :

 sudo dnf installer pandoc 

Sur Manjaro, tapez :

 sudo pacman -Syu pandoc 

CONNEXION: Comment utiliser pandoc pour convertir des fichiers sur la ligne de commande Linux

Sections d'une page d'homme

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

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

• Nom : Le nom de la commande et un one-liner concis qui décrit sa fonction.
• Synopsis : Une description succincte des invocations que quelqu'un peut utiliser pour lancer le programme. Ceux-ci montrent les types de paramètres de ligne de commande acceptés.
• Description : Une description de la commande ou de la fonction.
• Options : Une liste d'options de ligne de commande, et ce qu'elles font.
• Exemples : Quelques exemples d'usage courant.
• Valeurs de sortie : Les codes de retour possibles et leurs significations.
• Bugs : Une liste des bugs et bizarreries connus. Parfois, cela est complété par (ou remplacé par) un lien vers le suivi des problèmes pour le projet.
• Auteur : La ou les personnes qui ont écrit la commande.
• Copyright : Votre message de copyright. Ceux-ci incluent également généralement le type de licence sous laquelle le programme est publié.

Si vous parcourez certaines des pages de man les plus compliquées, vous verrez qu'il existe également de nombreuses autres sections. Par exemple, essayez man man . Vous n'êtes pas obligé de les inclure tous, mais seulement ceux dont vous avez vraiment besoin. les pages de man ne sont pas un endroit pour la verbosité.

Certaines autres sections que vous verrez assez fréquemment sont :

• Voir aussi : Autres commandes liées au sujet que certains trouveraient utiles ou pertinentes.
• Fichiers : une liste de fichiers inclus dans le package.
• Mises en garde : Autres points à connaître ou à surveiller.
• Historique : Un historique des modifications pour la commande.

Sections du manuel

Le manuel Linux est composé de toutes les pages de man , qui sont ensuite divisées en ces 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 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, telles que groff .
8. Commandes d'administration système : généralement réservées à root.
9. Routines du noyau : elles ne sont généralement pas installées par défaut.

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

Le format d'une page d'homme

Le format de macro groff n'est pas facile à analyser visuellement. En revanche, la démarque est un jeu d'enfant.

Ci-dessous se trouve une page de manuel dans groff .

La même page est affichée ci-dessous dans le démarquage.

Matière avant

Les trois premières lignes forment ce qu'on appelle la matière liminaire . Ceux-ci doivent tous commencer par un signe de % (                                                                                                                                                           et

• La première ligne : Contient le nom de la commande, suivi de la section du manuel entre parenthèses, sans espace. Le nom devient les sections gauche et droite de l'en-tête de la page de man . Par convention, le nom de la commande est en majuscule, bien que vous en trouviez beaucoup qui ne le soient pas. Tout ce qui suit le nom de la commande et le numéro de section du manuel devient la section gauche du pied de page. Il est pratique de l'utiliser pour le numéro de version du logiciel.
• La deuxième ligne : Le(s) nom(s) de(s) l'auteur(s). Ceux-ci sont affichés dans une section auteurs générée automatiquement de la page de man . Vous n'êtes pas obligé d'ajouter une section "Auteurs" - incluez simplement au moins un nom ici.
• La troisième ligne : la date, qui devient également la partie centrale du pied de page.

Nom

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

La section de nom contient une ligne rapide qui comprend le nom de la commande, un espace, un trait d'union ( - ), un espace, puis une très courte description de ce que fait la commande.

Synopsis

Le synopsis contient les différents formats que la ligne de commande peut prendre. Cette commande peut accepter un modèle de recherche ou une option de ligne de commande. Les deux astérisques ( ** ) de part et d'autre du nom de la commande signifient que le nom sera affiché en gras sur la page de man . Un astérisque unique ( * ) de part et d'autre d'un texte fait que la page de man l'affiche souligné.

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

La description

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

L'utilisation de deux signes dièse ( ## ) au début d'une ligne crée un titre de niveau deux. Vous pouvez les utiliser pour diviser votre description en plus petits morceaux.

Choix

La section des options contient une description de toutes les options de ligne de commande pouvant être utilisées avec la commande. Par convention, ceux-ci sont affichés en gras, incluez donc deux astérisques ( ** ) avant et après eux. Incluez la description textuelle des options sur la ligne suivante et commencez 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. S'il est trop long, il s'affiche sous la forme d'un paragraphe en retrait commençant sur la ligne située sous l'option de ligne de commande.

Exemples

La section des exemples contient une sélection de différents formats de ligne de commande. Notez que nous commençons les lignes de description par deux-points ( : ), tout comme nous l'avons fait dans la section des options.

Valeurs de sortie

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

Insectes

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

droits d'auteur

La section des droits d'auteur contient votre déclaration de droits d'auteur 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 man dans votre éditeur préféré. La plupart de ceux qui prennent en charge la coloration syntaxique seront conscients du démarquage et coloreront le texte pour mettre en évidence les titres, ainsi que pour le mettre en gras et le souligner. C'est très bien, mais vous ne regardez pas une page de man rendue, qui est la vraie preuve dans le pudding.

Ouvrez une fenêtre de terminal dans le répertoire contenant votre fichier Markdown. Avec celui-ci ouvert dans votre éditeur, enregistrez périodiquement votre fichier sur votre disque dur. A chaque fois, vous pouvez exécuter la commande suivante dans la fenêtre du terminal :

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

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 invoque également pandoc sur le fichier de démarquage (ici, il s'appelle "ms.1.md") :

• L'option -s (autonome) génère une page de man complète de haut en bas, plutôt qu'un simple 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 dit à pandoc d'envoyer sa sortie dans un fichier, elle sera donc envoyée à stdout .

Nous dirigeons également cette sortie vers man avec l'option -l (fichier local). Il dit à l' man de ne pas chercher dans la base de données de l' man à la recherche de la page de man . Au lieu de cela, il devrait ouvrir le fichier nommé. Si le nom de fichier est - , man prendra son entrée de stdin .

En résumé, vous pouvez enregistrer à partir de votre éditeur et appuyer sur Q pour fermer man s'il s'exécute dans la fenêtre du terminal. Ensuite, vous pouvez appuyer sur la flèche vers le haut, suivie de la touche Entrée pour voir une version rendue de votre page de man , directement dans man .

CONNEXION: Qu'est-ce que stdin, stdout et stderr sous Linux?

Création de votre page de manuel

Après avoir terminé votre page de man , vous devez en créer une version finale, puis l'installer sur votre système. La commande suivante indique à pandoc de générer une page de man appelée « ms.1 » :

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

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

Cela crée un fichier "ms.1", qui est notre nouvelle page de man . Où le met-on ? Cette commande nous indiquera où man recherche les pages de man :

 chemin d'homme 

Les résultats nous donnent les informations suivantes :

• /usr/share/man : L'emplacement de la bibliothèque standard des pages de man . 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 man .

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

Pour ce faire, nous tapons ce qui suit :

 sudo mkdir /usr/local/man/man1

Nous copions ensuite le fichier "ms.1" dans le bon répertoire :

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

man s'attend à ce que les pages de man soient compressées, nous allons donc utiliser gzip pour le compresser :

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

Pour que man ajoute le nouveau fichier à sa base de données, tapez ce qui suit :

 mandb sudo 

C'est ça! Nous pouvons maintenant appeler notre nouvelle page de man comme n'importe quelle autre en tapant :

 homme mme 

Notre nouvelle page de man est trouvée et affichée.

Elle ressemble à n'importe quelle autre page de man , avec du texte en gras, souligné et en retrait aux endroits appropriés.

Les lignes de description qui correspondent à côté de l'option qu'elles décrivent apparaissent sur la même ligne. Les lignes trop longues pour tenir s'affichent sous l'option qu'elles décrivent.

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

Si tu veux . . .

Une fois que pandoc a créé votre page de man , vous pouvez également éditer directement le fichier au format macro groff avant de le déplacer vers le répertoire de la page de man et le gzip .