Tutoriel complet sur la commande man sous Linux

Si vous avez un peu bidouillé avec GNU/Linux, vous avez probablement utilisé cette commande plus d'une fois. un homme pour vous sortir d'une situation délicate avec la syntaxe d'un programme, une option inhabituelle ou un fichier de configuration. Pourtant, beaucoup ne l'utilisent que superficiellement et ignorent tout ce qu'il recèle : sections, formats, raccourcis, et même la possibilité de créer leurs propres manuels.

Dans les lignes qui suivent, vous trouverez un Tutoriel complet sur l'utilisation de la commande man sous LinuxCe guide vous expliquera précisément ce qu'est un manuel, comment ses pages sont organisées, comment les consulter efficacement, où ils sont stockés, comment les créer manuellement à l'aide des macros Groff et comment les générer facilement avec des outils comme Pandoc. L'objectif est que vous soyez capable non seulement de lire des manuels, mais aussi d'en rédiger vous-même pour documenter vos scripts et applications.

Qu'est-ce que l'homme et pourquoi est-il si important sous Linux ?

Dans les systèmes de type UNIX, notamment GNU/Linux, la documentation principale est organisée en sections appelées pages de manuel ou pages man, accessible via la commande manCes pages décrivent en détail les commandes, les utilitaires, les appels système, les fonctions de bibliothèque, les fichiers spéciaux et bien plus encore.

Chaque contribution humaine apporte le Résumé de l'utilisation des commandes, une description détaillée, la liste des options, des exemples et souvent des informations supplémentaires telles que les fichiers associés, les variables d'environnement, les erreurs connues ou des références à d'autres pages de manuel connexes.

Pour accéder à l'aide d'un outil installé, il suffit de taper une phrase aussi simple que : man command_name dans le terminalLe résultat s'affiche de manière paginée (généralement à l'aide du visualiseur LESS), ce qui vous permet de naviguer confortablement dans les longs documents sans encombrer l'écran.

Dans de nombreuses distributions, les pages sont disponibles en plusieurs langues et sont stockées dans différents répertoires selon la langue. Tout le contenu n'est pas traduit en espagnolMais sous Debian et ses dérivés, vous pouvez installer des paquets comme pages de manuel y manpages-es-extra faire en sorte qu'une bonne partie du manuel soit disponible en espagnol.

Au sein de l'écosystème GNU, on trouve également le bien connu Le projet de documentation Linux (TLDP)qui coordonne la documentation officielle en anglais et propose une version espagnole (es.tldp.org). Vous pouvez également consulter le Guide complet des manuels de serveurBien que ne se limitant pas aux pages de manuel, ce projet a joué un rôle clé dans la diffusion de la documentation technique sous Linux.

Organisation du manuel par sections

Le manuel UNIX et Linux est divisé en sections numérotées qui regroupent des types d'informations spécifiquesCela empêche, par exemple, de mélanger une commande utilisateur avec un appel système du noyau portant le même nom.

Les sections classiques (et les plus répandues) du manuel sont les suivantes, chacune étant associée à un type de contenu bien défini chez l'homme :

• Section 1: commandes exécutables par l'utilisateur (programmes lancés depuis le shell).
• Section 2: appels système ou syscalls fournis par le noyau.
• Section 3: fonctions de bibliothèque (C, C++, Perl, etc.).
• Section 4: fichiers de périphérique spéciaux, généralement dans / dev.
• Section 5: formats et conventions de fichiers (par exemple / Etc / passwd).
• Section 6: jeux et économiseurs d'écran.
• Section 7: divers (protocoles, normes, conventions diverses, etc.).
• Section 8: commandes et démons d'administration système (destinés à l'utilisateur root).
• Section 9: routines internes du noyau (pas toujours présentes ou standardisées).

Cette division se reflète à la fois dans la structure logique du manuel et dans les répertoires système : Chaque section possède son propre dossier manN (man1, man2, man3, etc.), où les pages correspondantes sont stockées, généralement compressées avec gzip.

Il est fréquent de trouver des noms répétés dans différentes sections. Par exemple, La commande chmod existe à la fois comme commande utilisateur et comme appel système.Dans ces cas-là, c'est la section qui fait la différence entre une page et une autre, et il est essentiel de savoir à laquelle on souhaite accéder.

Comment utiliser efficacement l'homme

L'utilisation de base de cette commande est très simple : si nous voulons consulter l'aide d'un programme, il suffit de taper quelque chose comme ceci dans le terminal : commande man pour ouvrir sa page de manuelDe là, nous accédons à une visionneuse paginée (généralement moins de pages) qui nous permet de naviguer dans le contenu.

Lorsque le même nom apparaît dans plusieurs sections, l'homme consulte le manuel. de la section la plus basse à la plus haute et affiche la première correspondance trouvée. Par exemple, si vous exécutez man chmodVous verrez la page de commande utilisateur (section 1) car cette section a priorité sur la section 2.

Si vous devez forcer une section spécifique, vous pouvez la spécifier explicitement avant le nom : lors de l'exécution man 1 chmod vous obtenez le manuel de commande, avec homme 2 chmod Vous accédez à la description de l'appel système chmod du noyau.

Le format général que suit la commande est très facile à retenir : nom d'homme…Si vous omettez cette section, la recherche s'effectuera par ordre croissant ; si vous l'incluez, vous accéderez directement à la page correcte sans ambiguïté.

Sur la page, le résultat est présenté paginé, généralement à l'aide de moins comme viseur interneVous pouvez naviguer à l'aide des touches fléchées, des touches Page précédente et Page suivante, de la barre d'espace ou des raccourcis clavier Less habituels. Pour quitter et revenir à la ligne de commande, appuyez simplement sur la touche Entrée. q.

Raccourcis utiles lors de la consultation de manuels avec moins de détails

Quand l'homme s'appuie sur moins, il hérite toute une panoplie de raccourcis qui facilitent la lecture de longs manuels d'utilisation. Certains passent inaperçus, mais une fois qu'on les a utilisés, il est difficile de s'en passer.

Si vous naviguez sur une page particulièrement longue et que vous trouvez un point clé sur lequel vous souhaitez revenir plus tard, vous pouvez indiquer la position actuelle dans le documentIl suffit d'appuyer sur la touche m suivi d'une lettre (az ou AZ) pour créer un marqueur.

Pour revenir à cette marque, il vous suffit d'appuyer sur les guillemets simples. suivi de la même lettre que vous avez utilisée lors de sa création. Ainsi, vous pouvez passer rapidement d'une position importante à l'autre sans vous casser la tête à essayer de vous rappeler où tout se trouvait.

On notera que Les marques ne survivent que tant que vous avez la page ouverte.Dès que vous fermez `man` (et donc `less`), les pages de manuel disparaissent. Cependant, cette astuce fonctionne aussi pour tout autre fichier ouvert directement avec `less`, et pas seulement pour les pages de manuel.

Un autre détail très pratique est la possibilité de Exécuter des commandes shell sans fermer la page de manuelTout comme dans les éditeurs tels que vi ou vim, vous pouvez appuyer sur ! Dans le champ « less », saisissez la commande que vous souhaitez tester et exécutez-la ; une fois terminé, revenez à l’endroit où vous en étiez dans le manuel en appuyant simplement sur Entrée.

Comment la syntaxe est-elle décrite dans les pages de manuel ?

L'une des parties les plus importantes de toute page de manuel est le SYNOPSISCette section présente la syntaxe de la commande, de la fonction ou du fichier. Afin d'assurer concision et précision, un ensemble de conventions est utilisé et il est important de les maîtriser.

Lorsque vous voyez un élément entre Cela signifie que c'est facultatif.Si le texte apparaît comme Vous pouvez choisir de sélectionner cette option ou non ; toutefois, si elle s'affiche comme {x,y}Les éléments entre accolades sont des alternatives, mais vous devez en choisir une.

Si le synopsis inclut quelque chose comme ceci Cela indique que vous pouvez utiliser x, je ne suis rienPrécisément parce que l'expression entière est encadrée par des crochets. Par conséquent, si elle apparaît X…Cela signifie que x peut être répété autant de fois que nécessaire sur la ligne de commande.

Les options sont parfois résumées par une syntaxe comme Cela suggère qu'aucun d'eux n'est obligatoire, mais si vous les utilisez, Vous pouvez combiner les lettres dans n'importe quel ordre.Ainsi, -x, -y, -z, -xy, -zx, etc. seraient valides, pourvu que le programme accepte cette combinaison.

Cette manière compacte d'exprimer la syntaxe permet la condensation toutes les possibilités en une seule ligneBien que cela puisse paraître un peu cryptique au premier abord, une fois que vous l'aurez assimilé, la lecture des manuels deviendra beaucoup plus efficace.

Structure typique d'une page de manuel

Derrière chaque page de manuel se cache un fichier texte dans un format spécifique basé sur Groff et dans un ensemble de macros qui définissent les sections, les titres, les styles, les paragraphes, etc. Bien qu'à première vue le résultat ne soit « que du texte », il y a bien plus que cela.

L'anatomie de base d'une page de manuel comprend généralement plusieurs éléments. sections bien connues sous le nom de NOM, SYNOPSIS et DESCRIPTIONCes éléments peuvent être complétés par d'autres selon les documents à fournir. Il n'y a pas d'obligation stricte, mais plusieurs conventions sont largement utilisées.

Les sections les plus courantes que vous trouverez (ou que vous devriez utiliser lors de la création de vos propres pages) sont, entre autres, les suivantes, regroupant les l'information de manière prévisible pour l'utilisateur:

• NOM: nom de la commande ou du fichier et une brève description.
• SYNOPSIS: ligne ou lignes récapitulant les paramètres et les options.
• DESCRIPTION: explication détaillée de son fonctionnement.
• OPTIONS / OPTIONS: description de toutes les options de ligne de commande (principalement dans les sections 1 et 8).
• COMMANDES: liste des sous-commandes ou actions internes, si l'outil en possède.
• ENVIRONNEMENT: les variables d'environnement pertinentes et la manière dont le programme les utilise.
• FICHIERS / ARCHIVES: fichiers que l'outil utilise ou modifie (configuration, journaux, etc.).
• BOGUES / ERREURS: problèmes ou limitations connus.
• EXEMPLE: des exemples d'utilisation concrets, très utiles au quotidien.
• AUTEURS: les auteurs du programme ou du manuel lui-même, souvent joignables par courriel.
• VOIR AUSSI / VÉASE TBIÍA: références à d'autres pages de manuel connexes.

En plus de ceux-ci, il est courant d'en inclure d'autres tels que STATUT DE SORTIE, MISES EN GARDE, REMARQUES, VALEUR DE RETOUR ou DIAGNOSTIC lorsque vous souhaitez examiner plus en détail les codes de sortie, les avertissements, les notes supplémentaires ou les messages d'erreur spécifiques.

Bien que cela puisse paraître un peu fastidieux au premier abord, le respect de ces sections lors de la rédaction de vos manuels facilitera grandement leur utilisation. Les utilisateurs se sentent « comme chez eux ».car ils sauront où trouver chaque type d'information sans avoir à chercher à l'aveuglette.

Macros de formatage Groff utilisées dans les pages de manuel

Si vous ouvrez le fichier source d'une page de manuel classique (par exemple, en décompressant gpg.1.gz), vous verrez un texte assez brut rempli de lignes commençant par un point suivi d'acronymesCes acronymes correspondent précisément aux macros de formatage que le système manuel comprend.

La macro qui ouvre la page s'appelle .TH et définit l'en-tête principalLa structure générale qui suit est quelque chose comme ceci : .TH nom-de-commande numéro-de-section date Auteur titre, le tout sur une seule ligne, avec des lettres majuscules pour le nom de la commande.

Un exemple concret pourrait ressembler à ceci : .TH GPG 1 2015-03-08 «GnuPG 1.4.12» «GNU Privacy Guard», où sont spécifiés le nom du programme, la section, la date de révision du manuel, le nom de la version et un titre descriptif.

Les différentes parties du contenu sont structurées à l'aide de macros .SH, qui introduit de nouvelles sections dans le documentSa forme de base est très simple : .SH NOM_DE_SECTION, puis le texte qui compose cette section, jusqu'à ce qu'une nouvelle soit déclarée.

Pour formater des fragments de texte spécifiques, on utilise des macros telles que : .B, .I et .RCes extensions indiquent respectivement le gras, l'italique/souligné et le texte normal (police romaine). Il existe également des combinaisons comme .BI ou .IR pour mélanger les styles sur une même ligne.

Un exemple très simple serait quelque chose comme ceci : .B ceci est un test .Ice qui s'afficherait approximativement ainsi : « ceci est un » en surbrillance et « preuve » en italique. L'inconvénient est que Ces macros affectent généralement le reste de la ligne entière si elles ne sont pas soigneusement contrôlées.

Pour un contrôle plus précis, il est courant d'utiliser des séquences de commutation de source telles que : \fB, \fI et \fRqui modifient brièvement le style au sein d'une même ligne. On pourrait donc écrire quelque chose comme : Ceci est un test pour obtenir un résultat plus précis.

Les sauts de ligne explicites sont indiqués par .br, tandis que les nouveaux paragraphes sont créés avec .PPDe cette manière, l'auteur du manuel décide de la structure visuelle du texte lors de son affichage, sans se fier uniquement aux espaces blancs.

Si nécessaire, partez Commentaires internes que les utilisateurs ne verront pas Lors de l'exécution de la commande `man`, vous pouvez utiliser une macro de commentaire (par exemple avec des lignes commençant par un point et une barre oblique inverse), utile pour donner des indications aux futurs responsables de la maintenance du manuel sans que cela apparaisse dans la version finale.

Emplacement et organisation des pages de manuel dans le système

Pour bien comprendre le fonctionnement des pages de manuel, il est très utile de savoir où les fichiers sont physiquement stockés dans le systèmeCeci est particulièrement utile lorsque vous souhaitez consulter, copier ou créer vos propres manuels.

Un itinéraire très typique où se trouvent ces pages est / usr / share / manbien que vous puissiez également trouver d'autres lieux tels que /usr/man, /usr/local/man ou /usr/local/share/manselon la distribution ou s'il s'agit d'un logiciel installé localement.

Chaque section du manuel correspond à un sous-répertoire appelé hommeN (homme1, homme2, homme3, etc.)Par exemple, un programme utilisateur typique pourrait avoir son manuel dans /usr/share/man/man1/programa.1.gz, tandis qu'une page d'administration pourrait résider dans man8.

Si vous souhaitez localiser les fichiers associés à un programme spécifique (y compris sa page de manuel), vous pouvez utiliser où est le nom_du_programme afin que le système indique les chemins pertinentsLe résultat inclura généralement le chemin exact vers le fichier .N.gz indiqué sur la page de manuel.

Lorsque vous avez besoin de « disséquer » un manuel pour comprendre son fonctionnement sans risquer de tout casser, vous pouvez Copiez le fichier depuis /usr/share/man vers un répertoire sécurisé comme /usr/src, puis décompressez-le avec gzip pour analyser son contenu avec votre éditeur préféré.

N'oubliez pas que la numérotation des sections n'est pas décorative : lors de l'inspection /usr/share/man vous verrez les répertoires man1 à man8 (et parfois man9)Chaque classeur regroupe les manuels d'un type spécifique. On obtient ainsi une structure cohérente et facile à maintenir.

Comment créer ses propres pages de manuel « à la main »

Une fois que vous aurez compris la structure et les macros de base, vous pourrez vous lancer. Créez votre propre manuel pour les scripts ou les programmes (par exemple, un Manuel BashLe processus n'est pas aussi compliqué qu'il n'y paraît, même s'il nécessite un certain soin pour garantir sa propreté et son utilisation.

Une approche classique consiste à choisir une page de manuel existante comme référence (par exemple, celle de gpg ou d'iptables), à la copier dans un autre répertoire, à la décompresser, et Utilisez-le comme modèle pour apprendre la syntaxe réelle.À partir de là, vous supprimez le contenu et ne conservez que la structure nécessaire.

Lors de la dénomination du fichier, la convention suivante est suivie : nom de sectionSi votre script s'appelle test et qu'il s'agit d'un programme utilisateur normal, la procédure habituelle consiste à l'appeler test.1 car il se rapporte à la section 1Ensuite, à l'intérieur, vous définirez le titre avec .TH, les sections avec .SH et le contenu formaté avec les macros que vous connaissez déjà.

Une fois que vous avez tout préparé, l'étape suivante est compresser le fichier avec gzipCela générera le fichier test.1.gz, prêt à être installé à l'emplacement approprié. Le format compressé est celui utilisé par le système manuel par défaut.

Pour le rendre accessible aux autres utilisateurs, il suffit de Copiez le fichier compressé dans le répertoire de section appropriéPar exemple, /usr/share/man/man1/ s'il s'agit d'une commande normale, ou man8 s'il s'agit d'une commande d'administration.

Une fois le fichier placé au bon endroit, vous pouvez ouvrir votre manuel simplement en tapant : test manuel depuis n'importe quel terminal systèmeÀ partir de ce moment-là, elle se comportera comme n'importe quelle autre page de manuel installée de manière standard.

Création de manuels avec pandoc et Markdown

L'édition directe au format Groff convient pour l'apprentissage, mais peut s'avérer un peu rudimentaire. Si vous préférez une solution plus conviviale, vous pouvez Utilisez Markdown et convertissez-le au format man avec des outils comme pandoc.ce qui accélère considérablement le processus de documentation.

La première étape consiste à installer pandoc en utilisant le gestionnaire de paquets de votre distribution (apt, dnf, pacman, etc.). Une fois installé, vous pouvez créer votre page de manuel dans un fichier avec l'extension .N.md, par exemple. hello.1.md pour une commande appelée hello.

Dans ce fichier Markdown, vous pouvez rédiger votre documentation avec sections qui reflètent NOM, SYNOPSIS, DESCRIPTION, OPTIONS, EXEMPLES et tout autre outil dont vous pourriez avoir besoin. N'importe quel éditeur de texte simple comme vim, nano, gedit ou similaire fera l'affaire.

Une fois votre contenu rédigé en Markdown, il est temps de demander à pandoc de le convertir en format manuel qui comprend l'hommePour ce faire, on utilise une commande comme celle-ci : pandoc -s -t man -o hola.1 hola.1.md, où le nom de la sortie a la section comme extension.

Le choix -s (standalone) indique à pandoc de générer une page de manuel complèteavec toute la structure nécessaire, et non pas un simple fragment de texte sans titre. Pour sa part, l'option La clause `-t man` spécifie que le type de sortie doit correspondre exactement au format du manuel. que le système comprend alors.

Une fois le fichier hola.1 généré, vous pouvez le compresser si vous le souhaitez, puis le copier dans /usr/local/man/man1 ou un autre chemin approprié Vérifiez ensuite son bon fonctionnement en tapant `man hola`. Vous obtiendrez ainsi un manuel clair et facile à maintenir, avec l'avantage supplémentaire de l'avoir rédigé en Markdown.

Installation, localisation et suppression de vos pages de manuel

Lorsque vous développez votre propre script ou programme, il est judicieux non seulement d'installer le binaire, mais aussi Placez votre page de manuel dans le bon chemin. afin que n'importe quel utilisateur puisse facilement l'appeler depuis le terminal.

Si vous avez créé, par exemple, un fichier exécutable appelé hello, l'emplacement typique de ce fichier binaire serait : /usr/bin/helloVous pouvez donc l'appeler simplement en tapant « hello » sans avoir à accéder à son dossier source ni à modifier le chemin d'accès.

La page de manuel correspondante devrait se trouver à /usr/share/man/man1/hola.1.gz ou un répertoire similaire Conformément à la section et à la politique de votre distribution, s'il s'agit d'un outil d'administration, vous préférerez peut-être le placer dans man8.

Dans les environnements où vous distribuez votre logiciel à des tiers, c'est très pratique. inclure les scripts d'installation et de désinstallation Cette méthode consiste à copier ou supprimer à la fois le fichier binaire et la page de manuel. Ainsi, si l'utilisateur décide de supprimer votre outil, aucune documentation orpheline ne restera éparpillée dans le système.

Pour désinstaller manuellement, il vous suffit de Supprimez le fichier binaire de son chemin d'accès (par exemple, /usr/bin/hello) et la page de manuel de son répertoire de manuel correspondant.Après cela, toute tentative d'exécution de la commande man hola renverra une erreur indiquant que l'entrée n'existe pas.

L'utilisation régulière de ces lieux permet Votre logiciel s'intègre « nativement » au système, suivant les mêmes modèles utilisés par les outils inclus dans la distribution.

En définitive, la maîtrise de la commande man et du format des pages de manuel permet non seulement de consulter la documentation Linux très efficacement, mais aussi Transformez vos propres scripts et applications en outils bien documentés et faciles à utiliserEn intégrant des manuels comportant des sections claires, des exemples et des références, vous améliorez considérablement l'expérience de quiconque utilisera votre travail, que ce soit quelqu'un d'autre ou vous-même dans quelques mois, lorsque vous ne vous souviendrez plus des détails.