C'est un fait très courant que personne n'aime écrire de la documentation. Heck, personne n'aime non plus le lire. Mais il y a des moments où nous devons le lire pour, disons, terminer le projet à temps, ou, surtout lorsque vous travaillez dans le développement de logiciels, même l'écrivez. Si vous n'avez qu'à le lire, nous vous avons toujours encouragé à le faire, mais si vous devrez écrire les pages manuelles et avoir besoin d'un kickstart, voici l'article pour vous. Si vous avez travaillé auparavant avec HTML, votre vie sera plus facile, mais sinon ça va. Les pages manuelles d'écriture pour Linux ne sont pas si difficiles, malgré l'apparence des pages lorsqu'ils sont lus en texte ordinaire. Donc, fondamentalement, vous aurez besoin de connaissances Linux et de la possibilité d'utiliser un éditeur de texte. Vous apprendrez (avec des exemples, bien sûr) les principaux concepts de la mise en forme du texte tels qu'appliqués aux pages de l'homme et comment rédiger une page manuelle simple. Puisque nous avons utilisé YEST comme exemple pour notre tutoriel de développement C, nous utiliserons des extraits de sa page manuelle pour illustrer notre point pendant cet article.

Un peu d'histoire

Les premiers packages manuels écrits seraient rédigés par Dennis Ritchie et Ken Thompson en 1971. Le logiciel de formatage utilisé était TROFF, et ce format continue d'être utilisé à ce jour, bien que les outils puissent être différents. L'outil de formatage de texte sur les systèmes Linux est maintenant Groff, avec le principal «G» provenant de GNU. L'existence de Groff est due au fait que lorsque Troff a été écrit, les terminaux signifiaient quelque chose de différent en termes de capacités que ce qu'ils signifient aujourd'hui. Une autre forte incitation pour le projet GNU pour créer Groff a été la licence propriétaire de Troff. Troff vit toujours sur d'autres systèmes UNIX, comme OpenSolaris ou Plan9, bien que sous des licences open source.

Avant de commencer, nous devons vous dire quelque chose sur * Roff: c'est un logiciel de composition, comme Tex par exemple, et c'est une langue à part entière. Nous ne transformerons pas cet article en un manuel de Groff, et nous ne ferons pas de liste de différences entre Groff et Troff. Ceci est juste un démarreur pour la rédaction de pages manuelles simples, et si vous en avez besoin de plus, vous trouverez beaucoup de documentation sur Internet.

Alternatives

Si après avoir lu ceci, vous sentirez que la syntaxe est intimidante, nous avons une solution pour votre problème: pod2man. POD signifie une ancienne documentation et offre une syntaxe plus simple, et il y a pod2man, qui est un module Perl (partie de Perlpod) qui traduit la documentation écrite au format POD au format de page d'homme. Perlpod propose également des outils pour convertir POD en texte ou HTML, alors reportez-vous à la documentation de votre distribution sur la façon de l'installer.

Pages manuelles

Catégories

Les pages manuelles sont divisées en catégories, selon le sujet qu'ils traitent. Ils ne diffèrent pas sur les distributions Linux, mais d'autres systèmes Unix ont des façons différentes de diviser les pages manuelles. En utilisant

 $ man man

vous donnera ces catégories et bien plus en ce qui concerne la façon d'utiliser la commande man. Les catégories sur Linux sont les suivantes:

 1 programmes exécutables ou commandes de shell
2 appels système (fonctions fournies par le noyau)
3 appels de bibliothèque (fonctions dans les bibliothèques de programme)
4 fichiers spéciaux (généralement trouvés dans / dev)
5 formats de fichiers et conventions, par exemple
6 matchs
7 Divers (y compris les packages macro et les conventions), E.g. Homme (7), Groff (7)
8 Commandes d'administration du système (généralement uniquement pour la racine)
9 routines du noyau [Non standard]

Il est conseillé de lire la page manuelle de l'homme, car ce n'est pas un tutoriel sur la façon de utiliser eux, mais comment écrire eux.

Disposition d'une page manuelle

Depuis quelques années, il existe une norme sur la façon d'écrire des pages manuelles, ce qu'ils devraient contenir et les problèmes de style. Ils devraient être concis, respecter la disposition et comprimer autant d'informations dans le moins d'espace possible. Quand on voit un manuel de 100 pages, le premier réflexe sera de s'enfuir.

Très très loin. D'un autre côté, une page manuelle courte mais informative qui donnera au lecteur ce qu'il veut savoir sera d'une véritable aide, effrayant / ennuyant l'utilisateur. Si le programme pour lequel vous écrivez des pages manuels n'est pas écrit par vous (entièrement), travaillez avec le ou les développeurs jusqu'à ce que vous vous régliez à quoi ressemble le manuel. Maintenant, nous voulons éviter d'être ennuyeux ou effrayant, commençons par la mise en page.

Tout d'abord, le nom du fichier doit être $ commandName.$ catégorie, comme, par exemple, vim.1. Ce fichier, lorsqu'il est installé, doit être gzippé et copié dans le répertoire approprié, qui pour VIM devrait être / usr / share / man / man1. Le fichier non compressé est un fichier texte brut, rien de plus. La lecture de n'importe quelle page manuelle vous donnera une idée de la façon dont le vôtre devrait ressembler: nom, synopsis, description, options, exemples, aide, fichiers, voir aussi, auteur et bogues. Tous ces éléments ne sont pas obligatoires, mais il est recommandé de les fournir si l'espace suffit, pour une meilleure expérience utilisateur.

La langue de balisage

Comme indiqué précédemment, si vous avez l'habitude d'écrire XML ou HTML, vous trouverez la syntaxe simple. En fait, c'est simple de toute façon une fois que vous vous y êtes habitué. Nous commençons par le titre, Et le premier titre est le titre de titre. Les autres macros généralement rencontrés (l'équivalent des balises dans les langues de balisage) sont Heures de sujet et paragraphes, Mais plus sur ceux plus tard.

Le titre de titre doit contenir les éléments suivants: nom, chapitre (catégorie) et la date de la dernière modification de la page. Donc, pour vous mouiller les pieds, voici à quoi il devrait ressembler:

.E Yest 1 «19 avril 2010»

Th signifie tit-titres, et comme c'est une macro, il doit être préfixé par point. Yest est le nom de l'application, catégorie 1, édité pour la dernière fois le 19 avril 2010. Avant d'aller plus loin, vous voudrez peut-être insérer des commentaires dans votre fichier avant le titre de titre. Ceux-ci commencent par .\ ”(Dot Backslash Quote) et peut ressembler à ceci:

.\ ”Copyright 2004, 2006, 2010 Kimball Hawkins .

.\" Tous les droits sont réservés.

Maintenant, insérez ces lignes (le cap et le commentaire au-dessus) et vérifiez le résultat avec

 $ Groff -Man -Tascii Yest.1

-Tascii demande à Groff de sortir au format ASCII (texte), mais Groff prend en charge d'autres types de sortie. Nous vous invitons à consulter la page du manuel Groff pour cela.

Ensuite, maintenant que nous savons comment gérer les titres du titre, allons au section rubriques. Comme vous l'avez peut-être deviné, la macro est .Sh et ce qu'il fait, c'est qu'il présente le nom, le synopsis, la description, etc. Sections telles qu'elles sont écrites ci-dessus. La syntaxe sera donc:

.Shot Nom Yest - Utilitaire de manipulation de date.

.Shot SYNOPSIS .B Yest \ fr -help

.P .B Yest \ Fr -License

.P .B Yest \ Fr -version

.P .B Yest \ Fr [\ fb-idf = \ Fistr \ Fr] [\ fb-tz = \ fitzone \ fr] [[\ fb- \ fr | \ fb + \ fr] \ fiadjust \ fr [\ fbd \ fr | \ fbh \ fr | \ fbm \ fr]] [\ Fidate \ Fr] [\ fiformat-string \ Fr] .

Shot Description C'est ce qu'on appelle «Yest» car la valeur par défaut est la date d'hier \. Cet utilitaire connaît l'année de saut, l'heure d'été et de telles variations. Cet utilitaire ajoute ou soustrait les jours, les heures et / ou les minutes à partir d'une date donnée, et obtient les résultats au format spécifié. La valeur par défaut, si aucun ajustement n'est spécifié, est «-1D»

Ceci n'est bien sûr qu'une partie du manuel, mais voyons ce que les nouvelles macros signifient… B signifie Bold, et nous vous recommandons de coller ce code dans un fichier et de le tester au fur et à mesure, avec la commande Groff ci-dessus… P se traduit pour le paragraphe, car comme vous pouvez le voir, après chacun .P Il y a une double nouvelle ligne dans la page formatée. Les \ f * sont des séquences d'évasion de la police, et ce que cela signifie, c'est qu'après le mot «synopsis» .B dit à Groff d'imprimer en gras. Cependant, après le mot «Yest» qui est en effet imprimé en gras, nous avons besoin de «-help» pour être imprimé avec des polices régulières, c'est donc ce que \ fr représente. Inversement, \ fb signifie «imprimer en gras» et il peut être utilisé de manière interchangeable avec .B . En utilisant la logique, vous pouvez comprendre ce que signifie par exemple.

Le texte simple, c'est-à-dire un texte qui n'est pas un titre ou une section, est contenu dans les paragraphes. Un paragraphe simple est délimité par un .PP Macro, qui crée un petit espace vertical entre le paragraphe réel et le suivant. Si vous voulez un paragraphe étiqueté, vous pouvez l'avoir avec .Tp . Ensuite, nous parlerons de échancrure.

L'indentation relative signifie que le texte est en retrait par rapport au texte précédent et suivant. Pour démarrer un morceau de texte relativement inteinte, utilisez .Rs (démarrage relatif), et pour mettre fin à son utilisation .Re (fin relative). Voici un exemple:

.Rs.7i S'il y a des espaces ou des caractères spéciaux dans la chaîne, il doit être cité. Le programme reconnaîtra la plupart des conventions d'évacuation de type \ fbecho \ fr telles que «\\ n» (newline) et «\\ t» (onglet) dans \ fiformat-string \ fr et les évasions octales (\\ 0nn) sont prises en charge.

.P Si seulement un ajustement d'une journée est spécifié, la valeur par défaut \ fiforat-string \ fr est «% x». Si \ Fiadjustment \ FR comprend un élément temporel, la valeur par défaut \ fiformat-string \ Fr devient «% x-% r».

.CONCERNANT

Comme vous pouvez le voir, vous pouvez avoir un .P macro à l'intérieur d'un texte de texte relativement en retrait… P n'est qu'un alias pour .Pp, afin qu'ils puissent être utilisés de manière interchangeable. Vous avez peut-être remarqué le «.7i ""après .RS: Cela dit à Groff de mettre en place avec sept espaces le texte à l'intérieur.

L'utilisation de tables est tout aussi simple que l'utilisation d'un indentation relative: .Ts et .Te. Vous pouvez, comme indiqué plus tôt, modifier un mot ou un paragraphe entier (d'un point de vue typographique, c'est-à-dire) avec des macros. Les trois façons dont vous pouvez modifier un personnage sont, comme tout le monde le sait, audacieux, italique et romain. Donc, par exemple, .BI modifie le texte qui le suivant en ce qu'il apparaîtra les deux gras et italique.

Conclusion

Veuillez noter que cela peut être suffisant pour vous aider à démarrer, mais ce n'est pas complet. Ce ne sont pas toutes les macros, et si vous passez à un système BSD, vous pourriez constater qu'ils utilisent Mandoc au lieu de Groff, vous devrez donc faire un apprentissage par vous-même si vous voulez devenir compétent. Ensuite, veuillez lire quelques pages manuelles pour voir les principales conventions qui doivent être respectées, comme mettre les arguments facultatifs à votre application (si c'est le cas) entre crochets ou utiliser pour montrer qu'au moins l'un des arguments à l'intérieur Les accolades doivent être utilisées. Dans l'ensemble, documenter votre logiciel, même si vous n'êtes pas obligé par votre employeur, est bon pour vous et les utilisateurs de votre logiciel. Vous serez considéré comme un développeur prudent et les utilisateurs peuvent utiliser votre création plus facilement, sachant ce qu'ils peuvent et ce qu'ils ne peuvent pas faire.

Tutoriels Linux connexes:

• Choses à installer sur Ubuntu 20.04
• Choses à faire après l'installation d'Ubuntu 20.04 Focal Fossa Linux
• Comment effectuer des installations Linux sans surveillance avec Kickstart
• Comment vérifier la durée de vie de la batterie sur Ubuntu
• Choses à faire après l'installation d'Ubuntu 22.04 Jammy Jellyfish…
• Une introduction à l'automatisation Linux, des outils et des techniques
• Système linux hung? Comment s'échapper vers la ligne de commande et…
• Choses à installer sur Ubuntu 22.04
• Mint 20: Mieux que Ubuntu et Microsoft Windows?
• Installez Arch Linux dans VMware Workstation