Comment créer une page de manuel sous Linux

Voulez-vous que votre nouveau programme Linux ait l'air professionnel ?? donne un man page. Nous vous montrerons le moyen le plus simple et le plus rapide de le faire.

Les pages de l'homme

Il y a peut-être du vrai dans la vieille blague Unix, “les seule commande dont vous avez besoin savoir est man. ” Les man Les pages contiennent une mine de connaissances et devraient être le premier endroit où aller lorsque vous voulez des informations sur une commande.

Fournir un man la page d'un utilitaire ou d'une commande que vous avez écrite vous fait passer d'un 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. S'il est nativement compatible avec Linux, man La page 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. Quand vous appelez man ouvrir une page, lama groff pour lire le fichier et générer une sortie formatée, selon les macros du fichier. La sortie est acheminée vers less, et par la suite montré pour vous.

Sauf si tu crois man pages souvent, en écrire une et insérer manuellement des macros est un travail difficile. Le fait de créer un man une page qui s'analyse correctement et qui a l'air bien peut dépasser votre objectif de fournir une description concise, mais complet, de votre commande.

Vous devez vous concentrer sur votre contenu, ne combattez pas un ensemble sombre de macros.

EN RELATION: Comment utiliser la commande man de Linux: secrets cachés et bases

pandoc à la rescousse

Les pandoc Programme lit les fichiers de balisage et en génère de nouveaux dans environ 40 différents langages de balisage et formats de documents, y compris celui de man page. Transformez totalement le man procédure d'écriture de page pour que vous n'ayez pas à vous battre avec des hiéroglyphes.

Pour commencer, peut installer pandoc dans Ubuntu avec cette commande:

sudo apt-get install pandoc

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

sudo dnf installer pandoc

à Manjaro, scribe:

sudo pacman -Syu pandoc

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

Sections d'une page de manuel

man Les pages contiennent des sections qui suivent une convention de nommage standard. Les rubriques que vous man les besoins de la page sont dictés par la sophistication de la commande que vous décrivez.

Minimalement, la plupart des pages de manuel contiennent ces sections:

• nom: Le nom de la commande et un bref résumé décrivant sa fonction.
• Synopsis: Une description concise des invocations que quelqu'un peut utiliser pour démarrer le programme. Ceux-ci montrent les types de paramètres de ligne de commande acceptés.
• La description: Une description de la commande ou de la fonction.
• Les choix: Une liste d'alternatives en ligne de commande et ce qu'elles font.
• Exemples de: Quelques exemples d'utilisation courante.
• Valeurs de sortie: Codes de retour possibles et leurs significations.
• Insectes: Une liste de bugs et bizarreries connus. Parfois, ceci est complété par (ou est remplacé par) un lien vers le suivi des problèmes du projet.
• Auteur: La ou les personnes qui ont écrit la commande.
• Droit d'auteur: Votre message sur les droits d'auteur. Ceux-ci incluent également généralement le type de licence sous laquelle le programme est lancé.

Si vous regardez certains des plus compliqués man pages, vous verrez qu'il y a aussi beaucoup d'autres sections. Par exemple, essayer man man. Malgré cela, vous n'êtes pas obligé de tous les inclure, seulement ceux dont vous avez vraiment besoin. man les pages ne sont pas un endroit pour le verbiage.

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

• Voir également: Autres commandes liées au sujet que certains trouveraient utiles ou pertinentes.
• Enregistrements: Une liste des fichiers inclus dans le package.
• Mises en garde: Autres points à connaître ou faire attention.
• Histoire: Un historique des changements pour la commande.

Sections du manuel

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

1. Programmes exécutables: Les 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. Conventions et formats de fichiers: Par exemple, “/ etc / mot de passe”.
6. Jeux.
7. Différent: Paquets de macros et conventions, Quoi groff.
8. Commandes d'administration système: Régulièrement réservé à root.
9. Routines du noyau: Généralement pas installé par défaut.

Chaque man La page doit indiquer à quelle section elle appartient, et doit également être stocké dans l'emplacement approprié pour cette section, comme discuté ci-dessous. Les man les pages de commandes et d'utilitaires appartiennent à la première section.

Le format d'une page de manuel

Les groff Le format macro n'est pas facile à analyser visuellement. Au contraire, la remise est très simple.

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

La même page est montrée ci-dessous en vente.

Avant-propos

Les trois premières lignes forment quelque chose appelé problème principal. Tout cela devrait commencer par un signe de pourcentage (%), pas d'espaces de début, sauf 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 majuscule, 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 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: Les (Les) nom (s) du (Les) Auteur (il est). Ceux-ci sont affichés dans une section auteurs générée automatiquement de la man page. Vous n’avez pas besoin d’ajouter une section “Auteurs”, juste inclure au moins un nom ici.
• La troisième ligne: 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 balisage. Le signe dièse (#) doit être le premier caractère de la ligne, suivi d'un espace.

La section name a une seule ligne qui inclut le nom de la commande, un espace, un tiret (-), un espace, puis une très brève 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 dans le man page. Un seul astérisque (*) des deux côtés d'un texte rend le man page à afficher soulignée.

Par défaut, un saut de ligne est suivi d'une ligne vide. Pour forcer une pause sans ligne blanche, 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. Rappelles toi, vous n'écrivez pas de mode d'emploi.

Utiliser des signes numériques (##) au début d'une ligne créer un titre de niveau deux. Vous pouvez les utiliser pour diviser votre description en parties plus petites.

Les choix

La section alternatives contient une description des alternatives de ligne de commande qui peuvent être utilisées avec la commande. Par convention, ceux-ci sont indiqués en gras, inclure donc deux astérisques (**) avant et après eux. Incluez la description textuelle des alternatives sur la ligne suivante et commencez par deux points (:), suivi d'un espace.

Si la description est assez courte, man l'affichera sur la même ligne que l'option de ligne de commande. Si c'est trop long, s'affiche sous la forme d'un paragraphe en retrait commençant à la ligne sous l'option de ligne de commande.

Exemples de

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 (:), de la même manière que nous l'avons fait avec la section alternatives.

Valeurs de sortie

Cette section répertorie les valeurs de retour que votre commande envoie à la procédure appelante. Cela pourrait être le shell si vous l'appelez depuis la ligne de commande, ou un script si vous l'avez lancé depuis un script shell. Nous commençons les lignes descriptives par un deux-points (:) dans cette section aussi.

Insectes

La section des bogues répertorie les bogues connus, les pièges ou bizarreries que les gens devraient 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..

Droit d'auteur

La section copyright contient votre déclaration de copyright et, en général, 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 de ceux qui prennent en charge la coloration syntaxique connaissent les démarques et colorent le texte pour mettre en évidence les titres, ainsi que le gras et le souligner. C'est cool dans la mesure du possible., mais vous ne voyez pas de rendu man page, qui est le vrai test dans le pudding.

Ouvrez une fenêtre de terminal dans le répertoire qui contient votre fichier de démarques. Avec lui ouvert dans son éditeur, enregistrez périodiquement votre fichier sur votre disque dur. Chaque fois que je le fais, 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 le répéter, puis appuyez sur Entrée.

Cette commande appelle également pandoc dans le dossier de vente (ici, il s'appelle “ms.1.md”):

• Les -s (Indépendant) génère un plein de haut en bas man page, au lieu de simplement du texte dans man format.
• Les -t L'option (le type de sortie) avec l’opérateur “homme” indique pandoc générer sa production en man format. nous n'avons pas dit pandoc pour envoyer votre sortie dans un fichier, il sera donc envoyé à stdout.

Nous acheminons également cette sortie vers man avec lui -l (fichier local) option. Dé man ne cherche pas à travers man base de données à la recherche du man page. À sa place, devrait ouvrir le fichier nommé. Si le nom du fichier est -, man prendra votre avis de stdin.

Cela revient à 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. Après, vous pouvez appuyer sur la flèche vers le haut, suivi de Entrée pour voir une version rendue de votre man page, juste à l'intérieur man.

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

Création de votre page de manuel

Une fois que vous avez terminé votre man page, vous devez créer une version finale puis l'installer sur votre système. La commande suivante dit 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 que vous décrivez 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”, quel est notre nouveau man page. Où le mettons-nous? Cette commande nous dira où man cherche man pages:

chemin de l'homme

Les résultats nous donnent les prochaines informations:

• / usr / partager / homme: L'emplacement de la bibliothèque standard de man pages. Nous n'ajoutons pas de pages à cette bibliothèque.
• / usr / local / partager / homme: Ce lien symbolique pointe vers “/ usr / local / homme”.
• / usr / local / homme: C'est là que nous devrions placer notre nouveau man page.

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

Pour le faire, nous écrivons ce qui suit:

sudo mkdir /usr/local/man/man1

Ensuite, nous copions le fichier “ms.1” vers le répertoire correct:

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

man attends le man pages à compresser, donc on utilisera gzip pour le compresser:

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

Pour faire man ajouter le nouveau fichier à votre base de données, écris ce qui suit:

sudo mandb

C'est tout! Maintenant, nous pouvons appeler notre nouveau man page comme n'importe quel autre écrit:

homme ms

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

Ressemble à n'importe quel autre man page, avec texte en gras, soulignement et indentation aux endroits appropriés.

Les lignes de description qui s'enroulent à côté de 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.

Nous avons également généré automatiquement une section de “Auteurs”. Le pied de page comprend également le numéro de version du logiciel, la date et le nom de la commande, comme indiqué sur la page principale.

Si tu veux . . .

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