Vous voulez que votre nouveau programme Linux ait l’air professionnel? Donnez-lui une page de manuel. Nous allons vous montrer le moyen le plus simple et le plus rapide de le faire.
Table des matières
Les pages de l’homme
Il y a un noyau de vérité dans la vieille blague Unix, «le seule commande dont vous avez besoin savoir c’est l’homme. Les pages de manuel contiennent une mine de connaissances, et elles devraient être le premier endroit où vous devez vous tourner lorsque vous voulez en savoir plus sur une commande.
Fournir une page de manuel pour un utilitaire ou une commande que vous avez écrite l’élève d’un morceau de code utile à un package Linux entièrement formé. Les gens s’attendent à ce qu’une page de manuel soit fournie pour un programme qui a été écrit pour Linux. Si vous supportez nativement Linux, une page de manuel est obligatoire si vous voulez que votre programme soit pris au sérieux.
Historiquement, les pages de manuel ont été écrites à l’aide d’un ensemble de macros de formatage. Lorsque vous appelez l’homme à ouvrir une page, il appelle Groff à 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é pour vous.
À moins que vous ne créiez fréquemment des pages de manuel, en rédiger une et insérer manuellement les macros est un travail difficile. Le fait de créer une page de manuel qui analyse correctement et semble correct peut dépasser votre objectif de fournir une description concise, mais complète, de votre commande.
Vous devriez vous concentrer sur votre contenu, et non vous battre contre un ensemble obscur de macros.
pandoc à la rescousse
le programme pandoc lit les fichiers de démarque 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 manuel. Cela transforme totalement le processus d’écriture de la page de manuel pour que vous n’ayez pas à vous 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 install pandoc
Sur Manjaro, tapez:
sudo pacman -Syu pandoc
Sections d’une page homme
Les pages de manuel contiennent des sections qui suivent une convention de dénomination standard. Les sections dont votre page de manuel 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 une simple ligne simple qui décrit sa fonction.
Synopsis: Une brève description des appels que quelqu’un peut utiliser pour lancer le programme. Ceux-ci affichent 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’utilisation courante.
Valeurs de sortie: les codes de retour possibles et leur signification.
Bugs: une liste de bugs et de bizarreries connus. Parfois, cela est complété par (ou remplacé par) un lien vers le suivi des problèmes du projet.
Auteur: La ou les personnes qui ont écrit la commande.
Copyright: votre message de copyright. Celles-ci incluent également généralement le type de licence sous lequel le programme est publié.
Si vous parcourez certaines des pages de manuel les plus compliquées, vous verrez qu’il existe également de nombreuses autres sections. Par exemple, essayez homme homme. Vous n’êtes pas obligé de tous les inclure, mais uniquement ceux dont vous avez vraiment besoin. les pages de manuel ne sont pas un endroit pour les mots.
Certaines autres sections que vous verrez assez fréquemment sont:
Voir aussi: D’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: 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 ces sections numérotées:
Programmes exécutables: Ou, commandes shell.
Appels système: fonctions fournies par le noyau.
Appels de bibliothèque: fonctions dans les bibliothèques de programmes.
Fichiers spéciaux.
Formats de fichier et conventions: par exemple, «/ etc / passwd».
Jeux.
Divers: packages de macros et conventions, comme groff.
Commandes d’administration système: généralement réservées à root.
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 tard. 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 à analyser visuellement. En revanche, la démarque est un jeu d’enfant.
Vous trouverez ci-dessous une page de manuel dans groff.
La même page est affichée ci-dessous dans le démarque.
Matière avant
Les trois premières lignes forment ce qu’on appelle la matière première. Ceux-ci doivent tous commencer par un signe de pourcentage (%), sans espace de début mais un après, suivi de:
La première ligne: contient 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.
La deuxième ligne: Le (s) nom (s) des auteurs. Ceux-ci sont affichés dans une section auteurs automatiquement générée de la page de manuel. 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 la démarque. Le signe dièse (#) doit être le premier caractère de la ligne, suivi d’un espace.
La section de nom contient une ligne unique qui comprend le nom de la commande, un espace, un tiret (-), 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 chaque côté du nom de la commande signifient que le nom sera affiché en gras sur la page de manuel. Un seul astérisque
de chaque côté du texte, la page de manuel l’affiche soulignée.
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 de fin ().
Section de description d’une page de manuel dans Markdown.
La description explique ce que fait la commande ou le programme. Il doit couvrir les détails importants de manière succincte. 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 petits morceaux.
Section Options d’une page de manuel dans Markdown.
La section 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, donc incluez deux astérisques (**) avant et après eux. Incluez la description textuelle des options sur la ligne suivante et démarrez-la par deux points (:), suivi 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 qui commence sur la ligne sous l’option de ligne de commande.
Section Exemples d’une page de manuel dans Markdown.
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 un deux-points (:), tout comme nous l’avons fait dans la section des options.
Quittez la section des valeurs d’une page de manuel dans 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é depuis la ligne de commande, ou d’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.
Section Bugs d’une page de manuel dans Markdown.
La section bugs 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.
Section Copyright d’une page de manuel dans 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 préféré. La plupart des personnes qui prennent en charge la coloration syntaxique seront conscientes du démarquage et colorieront le texte pour mettre en évidence les en-têtes, ainsi que le mettre en gras et le souligner. C’est génial dans la mesure où cela se passe, mais vous ne regardez pas une page de manuel rendue, ce qui est la vraie preuve dans le pudding.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
pandoc ms.1.md -s -t homme | / 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 également pandoc sur le fichier markdown (ici, elle s’appelle «ms.1.md»):
L’option -s (autonome) 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 dit à pandoc d’envoyer sa sortie dans un fichier, donc il sera envoyé à stdout.
Nous envoyons également cette sortie dans man avec l’option -l (fichier local). Il indique à man de ne pas chercher dans la base de données man à la recherche de la page de manuel. Au lieu de cela, il devrait ouvrir le fichier nommé. Si le nom du fichier est -, man prendra ses entrées de stdin.
En résumé, vous pouvez enregistrer à partir de 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, juste à l’intérieur de man.
Créer votre page homme
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 de nommer la page de manuel 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.
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 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.
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 gzippour le compresser
sudo gzip /usr/local/man/man1/ms.1
:
sudo mandb
sudo mkdir / usr / local / man / man1 dans une fenêtre de terminal.
man ms
man ms dans une fenêtre de terminal.
section supérieure d’une nouvelle page de manuel.
section centrale de la nouvelle page de manuel.
Section inférieure d’une nouvelle page de manuel.
Nous avons également généré automatiquement une section «Auteurs». Le pied de page comprend également le numéro de version du logiciel, la date et le nom de la commande, tels que définis dans l’avant-propos.
Si tu veux . . .
Une fois que pandoc a créé votre page de manuel, vous pouvez également éditer directement le fichier au format de macro groff avant de le déplacer vers le répertoire de la page de manuel, et le gzip.