Comment créer une page de manuel sous Linux

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

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 man. » le man les pages 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 un man page 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 à un man page à fournir pour un programme qui a été écrit pour Linux. Si vous supportez nativement Linux, un man est obligatoire si vous voulez que votre programme soit pris au sérieux.

Historiquement, le man les pages ont été écrites à l’aide d’un ensemble de macros de formatage. Lorsque vous appelez man pour 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 dirigée vers less, et alors affiché pour vous.

Sauf si vous créez man pages fréquemment, en écrire une et insérer manuellement les macros est un travail difficile. L’acte de créer un man Une page qui analyse correctement et qui semble correcte 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.

Bientôt: Comment utiliser la commande man de Linux: secrets et bases cachés

pandoc à la rescousse

le pandoc programme 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 du man page. Il transforme totalement le man processus d’écriture de page afin que vous n’ayez pas à vous battre avec des hiéroglyphes.

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

sudo apt-get install pandoc

La commande "sudo apt-get install pandoc" dans une fenêtre de terminal.

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

sudo dnf install pandoc

sudo dnf installe pandoc dans une fenêtre de terminal.

Sur Manjaro, tapez:

sudo pacman -Syu pandoc

sudo pacman -Syu pandoc dans une fenêtre de terminal.

Bientôt: Comment utiliser pandoc pour convertir des fichiers sur la ligne de commande Linux

Sections d’une page homme

man les pages contiennent des sections qui suivent une convention de dénomination standard. Les sections votre man les besoins de page sont dictés 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 description succincte 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.
  • La 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 leur signification.
  • Bugs: Une liste de bogues 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.
  • droits d’auteur: Votre message de copyright. Celles-ci incluent également généralement le type de licence sous lequel le programme est publié.

Si vous regardez à travers certains des plus compliqués man pages, vous verrez qu’il existe également de nombreuses autres sections. Par exemple, essayez man man. Vous n’êtes pas obligé de tous les inclure, mais uniquement ceux dont vous avez vraiment besoin. man les pages ne sont pas un endroit pour les mots.

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

  • Voir également: D’autres commandes liées au sujet que certains trouveraient utiles ou pertinentes.
  • Des dossiers: Une liste de fichiers inclus dans le package.
  • Mises en garde: Autres points à connaître ou à surveiller.
  • L’histoire: Un historique des modifications de la commande.

Sections du manuel

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

  1. Programmes exécutables: Ou, des commandes shell.
  2. Appels système: Fonctions fournies par le noyau.
  3. Appels à la 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: Paquets de macros et conventions, tels que groff.
  8. Commandes d’administration système: Habituellement réservé à root.
  9. Routines du noyau: Pas généralement installé par défaut.
En relation :  Comment sortir d'une ornière: 5 façons de passer à autre chose

Chaque man La page 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. le man les pages des commandes et des utilitaires appartiennent à la première section.

Le format d’une page de manuel

le groff le format de macro 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.

Haut d'une page de manuel au format groff.

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

Haut d'une page de manuel au format markdown.

Matière avant

Les trois premières lignes forment quelque chose appelé 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 du man en-tête de page. 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 man page. 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 commençant 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 unique 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 chaque côté du nom de la commande signifie que le nom sera affiché en gras sur le man page. Un seul astérisque (*) de chaque côté d’un texte provoque le man page pour l’afficher 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 ().

La description

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.

En utilisant 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.

Options

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.

Exemples

Section d'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 deux points (:), tout comme nous l’avons fait dans la section des options.

Valeurs de sortie

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é à partir de la ligne de commande ou d’un script si vous l’avez lancé à partir d’un script shell. Nous commençons les lignes de description par deux points (:) dans cette section également.

Bugs

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.

En relation :  Qu'est-ce qu'un point d'écho ?

droits d’auteur

Section Copyright d'une page de manuel dans Markdown.

La section relative aux 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 man page 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 va, mais vous ne regardez pas un rendu man page, qui est la vraie preuve dans le pudding.

Ouvrez une fenêtre de terminal dans le répertoire qui contient votre fichier de démarque. Une fois ouvert dans votre éditeur, enregistrez périodiquement votre fichier sur votre disque dur. Chaque fois que vous le faites, vous pouvez exécuter la commande suivante dans la fenêtre du terminal:

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 invoque également pandoc sur le fichier markdown (ici, il s’appelle «ms.1.md»):

  • le -s (autonome) génère un complet de haut en bas man page, plutôt que juste du texte dans man format.
  • le -t (type de sortie) avec l’opérateur « man » indique pandoc pour générer sa sortie dans man format. Nous n’avons pas dit pandoc pour envoyer sa sortie dans un fichier, afin qu’il soit envoyé à stdout.

Nous envoyons également cette sortie dans man avec le -l (fichier local). Il raconte man ne pas chercher dans le man base de données à la recherche du man page. Au lieu de cela, il devrait ouvrir le fichier nommé. Si le nom de fichier est -, man prendra sa contribution de stdin.

Cela se résume à vous pouvez enregistrer à partir de votre éditeur et appuyez 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, puis sur Entrée pour voir une version rendue de votre man page, juste à l’intérieur man.

Bientôt: Que sont stdin, stdout et stderr sous Linux?

Créer votre page homme

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

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 le man page après la commande qu’il décrit et en ajoutant 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 nouveau man page. Où le mettons-nous? Cette commande nous dira où man recherche man pages:

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 de man pages. 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 là que nous devons placer notre nouveau man page.

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 attend le man pages à compresser, nous allons donc utiliser gzip pour le compresser:

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

Faire man ajoutez le nouveau fichier à sa base de données, tapez ce qui suit:

sudo mandb

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

C’est ça! Nous pouvons maintenant appeler notre nouveau man page identique à toute autre en tapant:

man ms

man ms dans une fenêtre de terminal.

Notre nouveau man La page est trouvée et affichée.

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

Il ressemble à n’importe quel autre man page, avec du texte en gras, souligné et en retrait aux endroits appropriés.

section centrale de la nouvelle page de manuel.

Les lignes de description correspondant à l’option qu’elles décrivent apparaissent sur la même ligne. Les lignes trop longues pour s’adapter apparaissent sous l’option qu’elles décrivent.

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 man page, vous pouvez également modifier directement le fichier dans la groff format de macro avant de le déplacer vers man répertoire de pages, et gzip il.

body #primary .entry-content ul # nextuplist {list-style-type: none; margin-left: 0px; padding-left: 0px;} body #primary .entry-content ul # nextuplist li a {text-decoration: none ; couleur: # 1d55a9;}

Moyens Staff
Moyens I/O Staff vous a motivé, donner des conseils sur la technologie, le développement personnel, le style de vie et des stratégies qui vous aider.