Lexique Linux - Page d'anatomie d'un homme

M an pages sont généralement décomposées en une série de sections détaillant le nom et une description, l'utilisation et les mises en garde. Les pages de manuel peuvent être difficiles à lire, mais ce sont des ressources précieuses qui peuvent être exploitées en un clin d'œil, et elles n'ont même pas besoin d'Internet.

NOM
Le premier est le titre du nom, et cela résume à peu près tout. Cette section comprend le nom de l'utilitaire, ainsi qu'une brève description.

SYNOPSIS
Il existe différents degrés de lisibilité d'une page de manuel à l'autre, mais une chose est sûre, la partie la plus difficile est généralement de déchiffrer un synopsis poilu. Il existe plusieurs conventions pour indiquer les éléments d'information requis pour une commande donnée. Ces conventions consistent en différents crochets et parenthèses, ainsi qu'en d'autres formes de notation. Toutes ces différentes conventions peuvent être extrêmement déroutantes pour un débutant, et encore intimidantes pour quelqu'un qui a de l'expérience mais qui ne connaît pas l'art des manuels. Ci-dessous, nous décomposerons le charabia en règles digestes.

Ces règles sont assez simples, mais elles deviennent plus difficiles, voire intimidantes, lorsqu'elles sont utilisées dans de longues définitions de fonctions, en particulier lorsqu'elles sont imbriquées. Nous allons donc jeter un œil à certaines imbrications ci-dessous pour construire ce que nous avons décomposé.

tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ ARG …]

La commande tar a de nombreuses options. Nous voyons le nom de la commande tar en gras car il doit être saisi comme indiqué. Ensuite, nous voyons les accolades s'ouvrir avec des options séparées par des tuyaux indiquant que nous sommes limités à celles-ci et que nous ne devons en choisir qu'une seule. Viennent ensuite les drapeaux facultatifs, nous pouvons utiliser n'importe quel nombre, cependant, ils peuvent ne pas tous fonctionner ensemble, une lecture plus approfondie de la page de manuel éclairera tout conflit potentiel d'options. Et, enfin, nous avons l'argument répétable, dans le cas de tar this pour le ou les fichiers sur lesquels vous travaillez.

su [options] [-] [ utilisateur [ argument …]]

Encore une fois, nous voyons su en gras car c'est le nom de la commande. Deuxièmement, nous voyons qu'aucun drapeau n'est réellement spécifié, seulement qu'ils sont facultatifs. Troisièmement, un seul indicateur est spécifié, mais il est également facultatif. Enfin, nous voyons un argument optionnel qui est répétable à l'intérieur d'un argument optionnel. Maintenant, ce qui avait l'air très mystérieux a plus de sens.

whois [{-h|–host } HOST ] [{-p|–port} PORT ] [-abBcdGHKlLmMrRx] [-g SOURCE:FIRST-LAST ] [-i ATTR [, ATTR ]…] [-s SOURCE [, SOURCE ]…] [-T TYPE [, TYPE ]…] [–verbeux] OBJET

Celui-ci est particulièrement dense. Copiez-le dans votre éditeur de texte préféré et ajoutez-y des espaces supplémentaires si cela vous aide à le lire. Après avoir scanné cela, vous devriez commencer à voir quelques modèles. Les parties hôte et port utilisent le même formatage pour la forme courte et longue de l'option suivie de l'argument de cette option, tout en étant elles-mêmes optionnelles. Ensuite, nous voyons la chaîne de drapeaux optionnels. Le bit suivant sur les sources du premier au dernier est la syntaxe attendue par whois qui est expliquée plus loin dans la page de manuel. Maintenant, nous voyons ce triplet d'indicateurs facultatifs qui prennent soit un seul argument, soit des arguments répétitifs facultatifs, c'est le genre de composition des conventions qui peut être très difficile à saisir pleinement au début. Enfin, il y a l'option verbeuse et l'objet (l'hôte/domaine).

Et voilà comment lire un synopsis de page de manuel. Il existe quelques autres conventions, mais elles sont beaucoup trop obscures pour être couvertes dans cet article.

LA DESCRIPTION
C'est généralement là que l'utilisation prévue du programme ou de l'utilitaire est décrite. Certains manuels seront beaucoup plus détaillés sous cette rubrique que d'autres.

OPTIONS
Vous vous souvenez de tous ces drapeaux et différents arguments qui pourraient être facultatifs ou obligatoires ? C'est là qu'ils sont tous expliqués. Il y a généralement de bonnes informations ici et c'est souvent là que vous trouverez la convention <argument>, indiquant qu'un drapeau donné nécessite un argument correspondant. Parfois, vous constaterez que les options seront dans la partie description car il n'y a pas de règle stricte définissant les pages de manuel, seulement des conventions et la volonté de se conformer aux normes.

EXEMPLES
C'est l'une des pièces les plus pratiques qui n'est malheureusement pas incluse dans tous les manuels. Vous constaterez également que la quantité d'informations et le nombre d'exemples varient considérablement et que tous les exemples n'aident pas réellement à utiliser la commande.

De plus, vous trouverez régulièrement des sections pour l'auteur, des informations sur les droits d'auteur, des rapports de bogues et voir aussi (à propos).

Au-delà de cela, il y a les sections formellement définies des pages de manuel telles que définies ci-dessous.

De nombreuses commandes n'ont pas de manuels dans plus d'une section, mais pour celles qui en ont, ou pour certaines dont le nom peut être ambigu, vous pouvez spécifier la section comme dans l'exemple ci-dessous.

Les commandes ne sont pas les seules choses qui ont des manuels comme vous pouvez le voir dans les sections disponibles. Les appels système, les fichiers de configuration et les périphériques spéciaux peuvent tout aussi probablement avoir une page de manuel correspondante. La quantité d'informations sur une installation Linux typique dans les pages de manuel est incroyable, et il en va de même pour les autres systèmes d'exploitation open source de type UNIX.

Si vous trouvez que la page de manuel ne suffit pas et que vous ne comprenez toujours pas une commande, vérifiez toujours en ligne car de nombreuses personnes offrent des explications plus approfondies sur certains outils, mais aussi, de nombreuses distributions ont leurs propres pages de manuel pour différents packages logiciels. Une fois que vous avez trouvé que vous êtes à l'aise avec un logiciel, mais que vous pensez toujours que le manuel fait défaut, vous pouvez toujours contribuer en écrivant le vôtre et en le soumettant au projet respectif. La documentation est souvent la partie la plus négligée des projets logiciels, donc même si vous ne savez pas écrire de code, vous pouvez écrire des manuels, des articles Wiki et des tutoriels pour aider les autres.

Maintenant que vous connaissez l'anatomie d'une page de manuel, vous n'avez plus d'excuse que de vous rendre sur RTFM (et c'est lire le manuel gratuit pour les moins de 18 ans) ;)

Lisez aussi : Lexique Linux : utilisez la commande Watch pour exécuter une commande toutes les X secondes