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, «la seule commande que vous devez savoir 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 écrit 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 prenez en charge Linux de manière native, 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 pour lire le fichier et générer une sortie formatée, selon les macros du fichier. La sortie est dirigée vers less, puis 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 a l'air 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 pandoc Le 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 la page pour 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

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

man les pages contiennent des sections qui suivent une convention de dénomination standard. Les sections votre man les besoins de la 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'utilisation courante.
• Valeurs de sortie: Les codes 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’avez pas à tous les inclure, mais uniquement ceux dont vous avez vraiment besoin. man les pages ne sont pas un endroit pour les mots.

Voici quelques autres sections que vous verrez assez fréquemment:

• 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 est ensuite divisé 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: Packages 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.

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.

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

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 d’autres 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’avez pas besoin d’ajouter une section «Auteurs». Il vous suffit d’inclure 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

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 de 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

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

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 l’outil de suivi des problèmes du projet pour vérifier l’état des bogues ou en signaler de nouveaux.

droits d'auteur

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 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 se passe, 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 -

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 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'elle soit envoyée à stdout.

Nous transmettons également ce résultat à 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 doit ouvrir le fichier nommé. Si le nom du 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.

Créer votre page homme

Une fois que vous avez 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

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 manuelle 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

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

C'est tout! Nous pouvons maintenant appeler notre nouveau man page identique à toute autre en tapant:

man ms

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

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

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

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.