Vous voulez que votre nouveau programme Linux ait l'air professionnel? Donnez-lui un homme page. Nous allons vous montrer le moyen le plus simple et le plus rapide de le faire.
Il y a un noyau de vérité dans la vieille blague Unix, "le seule commande dont vous avez besoin savoir c'est homme. » le homme 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 homme 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 homme page à fournir pour un programme qui a été écrit pour Linux. Si vous prenez en charge Linux de manière native, un homme est obligatoire si vous voulez que votre programme soit pris au sérieux.
Historiquement, le homme les pages ont été écrites à l'aide d'un ensemble de macros de formatage. Lorsque vous appelez homme 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 Moins, puis affiché pour vous.
Sauf si vous créez homme pages fréquemment, en écrire une et insérer manuellement les macros est un travail difficile. L'acte de créer un homme 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.
EN RELATION: Comment utiliser la commande man de Linux: secrets et bases cachés
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 homme page. Il transforme totalement le homme 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 installer pandoc
Sur Fedora, la commande dont vous avez besoin est la suivante:
sudo dnf installer pandoc
Sur Manjaro, tapez:
sudo pacman -Syu pandoc
EN RELATION: Comment utiliser pandoc pour convertir des fichiers sur la ligne de commande Linux
homme les pages contiennent des sections qui suivent une convention de dénomination standard. Les sections votre homme 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:
Si vous regardez à travers certains des plus compliqués homme pages, vous verrez qu'il existe également de nombreuses autres sections. Par exemple, essayez homme homme. Vous n’avez pas à tous les inclure, mais uniquement ceux dont vous avez vraiment besoin. homme les pages ne sont pas un endroit pour les mots.
Voici quelques autres sections que vous verrez assez fréquemment:
Le manuel Linux est composé de tous les homme pages, qui est ensuite divisé en ces sections numérotées:
groff.Chaque homme 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 homme les pages des commandes et des utilitaires appartiennent à la première section.
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.
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:
homme 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.homme page. Vous n’avez pas besoin d’ajouter une section «Auteurs». Il vous suffit d’inclure au moins un nom ici.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.
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 homme page. Un seul astérisque (*) de chaque côté d'un texte provoque le homme 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 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.
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, homme 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.
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.
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.
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.
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é.
Vous pouvez modifier votre homme 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 homme 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 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 markdown (ici, il s'appelle "ms.1.md"):
-s (autonome) génère un complet de haut en bas homme page, plutôt que du texte dans homme format.-t (type de sortie) avec l'opérateur "man" indique pandoc pour générer sa sortie dans homme 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 à homme avec le -l (fichier local). Il raconte homme ne pas chercher dans le homme base de données à la recherche du homme page. Au lieu de cela, il doit ouvrir le fichier nommé. Si le nom du fichier est -, homme prendra sa contribution de stdin.
Cela se résume à vous pouvez enregistrer à partir de votre éditeur et appuyez sur Q pour fermer homme 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 homme page, juste à l'intérieur homme.
EN RELATION: Que sont stdin, stdout et stderr sous Linux?
Une fois que vous avez terminé votre homme 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 homme page appelée «ms.1»:
pandoc ms.1.md -s -t homme -o ms.1
Cela suit la convention de nommer le homme 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 homme page. Où le mettons-nous? Cette commande nous dira où homme recherche homme pages:
manpath
Les résultats nous donnent les informations suivantes:
homme pages. Nous n'ajoutons pas de pages à cette bibliothèque.homme 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
homme attend le homme pages à compresser, nous allons donc utiliser gzip pour le compresser:
sudo gzip /usr/local/man/man1/ms.1
Faire homme ajoutez le nouveau fichier à sa base de données, tapez ce qui suit:
sudo mandb
C'est tout! Nous pouvons maintenant appeler notre nouveau homme page identique à toute autre en tapant:
homme ms
Notre nouveau homme La page est trouvée et affichée.
Il ressemble à n'importe quel autre homme 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.
Une fois que pandoc a créé votre homme page, vous pouvez également modifier directement le fichier dans la groff format de macro avant de le déplacer vers homme répertoire de pages, et gzip il.