Réalisation de pages de manuel <author> Jens Schweikhardt <jens@kssun3.rus.uni-stuttgart.de>, trad. Rene.Cougnenc@freenix.fr - Janvier 1996 <abstract> Ce document explique ce que l'on doit connaître pour pouvoir rédiger de la documentation en ligne destinée à être exploitée par la commande <tt>man(1)</tt> : ce sont les fameuses <em/pages de manuel/. </abstract> <toc> <sect> Quelques évidences Pourquoi rédigeons-nous des documentations ? À question stupide, réponse stupide : pour que tout le monde sache utiliser notre programme, notre fonction bibliothèque ou tout autre code de notre cru que nous diffusons dans ce but. Mais la rédaction n'est pas tout : <itemize> <item> la documentation doit être accessible. Si elle est placée en un endroit non standard tel que les outils destinés à son exploitation ne la trouvent pas, comment peut-elle remplir son rôle ? <item> la documentation doit être fiable et à jour. Il n'y a rien de plus irritant que de rencontrer un programme se comportant différemment de ce qui est décrit dans son manuel. Les utilisateurs vous maudiront, vous enverront des courriers d'insulte, puis rejetteront à jamais tout autre travail venant de vous. </itemize> La méthode traditionnelle pour accéder à la documentation sous UNIX fait appel à la commande <tt/man(1)/. Ce document décrit les opérations nécessaires pour la rédaction d'une page de manuel qui sera correctement traitée par les outils de formatage prévus à cet effet. Parmi ces outils, les plus importants sont <tt/man(1)/, <tt/xman(1x)/, <tt/apropos(1)/, <tt/makewhatis(8)/ et <tt/catman(8)/. La qualité et la véracité des informations sont de votre ressort, bien entendu. Malgré tout, vous trouverez dans ce guide quelques idées qui vous permettront d'éviter certains pièges courants. <sect> Organisation et principe du manuel en ligne Il vous vaut connaître avec précision le mécanisme d'accès aux pages de manuel afin de savoir donner un nom correct à vos documents, et d'être capable de les installer au bon endroit. Chaque page de manuel appartient à une <em/section/ spécifique, dénotée par un simple chiffre. Les sections les plus courantes rencontrées sous <bf/Linux/ sont : <itemize> <item> <bf/1/ : commandes utilisateur pouvant être exécutées par tout le monde ; <item> <bf/2/ : appels système, c'est-à-dire les fonctions fournies par le noyau ; <item> <bf/3/ : fonctions des bibliothèques ; <item> <bf/4/ : périphériques, c'est-à-dire les fichiers spéciaux que l'on trouve dans le répertoire <tt>/dev</tt> ; <item> <bf/5/ : descriptions des formats de fichiers (comme par exemple <tt>/etc/passwd</tt>) ; <item> <bf/6/ : les jeux, sans commentaire... <item> <bf/7/ : divers (macros, conventions particulières, ...) ; <item> <bf/8/ : outils d'administration système exécutables uniquement par le superutilisateur (<tt/root/) ; <item> <bf/9/ : un autre endroit (spécifique à <bf/Linux/) destiné à la documentation des services offerts par le noyau ; <item> <bf/n/ : nouvelle documentation, qui pourra être déplacée vers un endroit plus approprié ; <item> <bf/o/ : ancienne documentation, qui peut être conservée encore un certain temps ; <item> <bf/l/ : documentation locale, propre à ce système particulier. </itemize> Le nom du fichier source d'une page de manuel (le fichier d'entrée du système de formatage) est constitué du nom de la commande décrite (ou de la fonction, du fichier, etc.), suivi d'un point et du numéro de section. Si par exemple vous documentez le format du fichier <sq>passwd</sq>, vous devrez appeler votre fichier source <sq><em/passwd.5/</sq>. Vous voyez ici qu'il peut exister un fichier du même nom qu'une commande ; nous pourrions tout aussi bien avoir une fonction de bibliothèque appelée <sq><em/passwd/</sq>. L'organisation en sections constitue la méthode habituelle pour résoudre ce type d'ambiguïté : la description de la commande se trouvera dans le fichier <sq><em/passwd.1/</sq> et notre hypothétique fonction bibliothèque dans <sq><em/passwd.3/</sq>. <footnote> Vous rencontrerez quelquefois des pages de manuel dont le nom ne se termine pas par un chiffre, mais par un chiffre et une ou plusieurs lettres comme par exemple <sq><em/xterm.1x/</sq> ou <sq><em/wish.1tk/</sq>. Le but de cette notation est d'indiquer que la documentation en question s'applique à un programme X Window ou à une application Tk, respectivement. Certains programmes d'affichage du manuel peuvent exploiter cette particularité ; <tt/xman/, par exemple, affichera <sq><em/xterm(x)/</sq> et <sq><em/wish(tk)/</sq> dans la liste des documents disponibles. </footnote> Attention aux éventuels conflits de noms avec des programmes, fonctions ou fichiers existants. Ce serait par exemple une très mauvaise idée que d'appeler votre nouvel éditeur de texte <tt>ed</tt>, <tt>sed</tt> (pour <sq>super ed</sq>) ou <tt>red</tt> (pour <sq>Roger Editions</sq>) ! En vous assurant que le nom de votre application est unique, vous éviterez qu'un utilisateur exécute votre programme par erreur ou lise sa page de manuel à la place de celle dont il désirait prendre connaissance, ou vice versa. Vous pouvez éventuellement vous aider de la base de données <sq>lsm</sq>, qui recense beaucoup des programmes disponibles pour <bf/Linux/. Maintenant que nous savons déterminer le nom de notre fichier, il nous faut savoir dans quel répertoire l'installer (lorsque la personne qui installera votre application tapera la commande <sq><tt/make install/</sq> par exemple). Sous <bf/Linux/, toutes les pages de manuel sont situées dans des sous-répertoires à partir d'une (ou plusieurs) racine indiquée dans la variable d'environnement <tt>MANPATH</tt>. Les outils de traitement de la documentation utilisent cette variable de la même manière que le shell emploie <tt>PATH</tt> pour localiser les programmes exécutables. En fait, <tt>MANPATH</tt> a exactement le même format que <tt>PATH</tt>. Toutes deux contiennent une liste de répertoires, avec le caractère deux-points comme élément séparateur (mais <tt>MANPATH</tt> n'autorise pas de champs vides ou de chemins d'accès relatifs). Si <tt>MANPATH</tt> n'existe pas ou n'est pas exportée, le répertoire /usr/man sera alors utilisé par défaut. Dans le but d'accélérer les recherches et pour garder des répertoires de taille raisonnable, les répertoires pointés par <tt>MANPATH</tt> contiennent une série de sous-répertoires nommés <sq><em/manS/</sq>, où <em/S/ désigne le caractère correspondant au numéro de section que nous avons présenté plus haut. Toutes les sections ne sont pas représentées, il n'y a par exemple pas de raison de conserver une entrée <sq>mano</sq>. Vous pourrez y trouver également des sous-répertoires appelés <sq><em/catS/</sq>, <sq><em/dviS/</sq> et <sq><em/psS/</sq>, qui contiennent la documentation toute formatée, prête à être affichée ou imprimée : nous reviendrons sur ce sujet plus loin. Le seul fichier qui peut être présent à côté de ces sous-répertoires du répertoire de base s'appelle <sq><em/whatis/</sq>. Nous décrirons son contenu et la manière de le créer plus tard. La méthode la plus sûre pour installer au bon endroit une page de manuel de la section <sq>S</sq> est de placer le fichier dans le répertoire /usr/man/manS. Toutefois un bon <tt>Makefile</tt> devra autoriser l'utilisateur à choisir un autre répertoire de base, disons par exemple par le biais d'une variable d'environnement que l'on pourrait nommer <tt>MANDIR</tt>. La plupart des distributions GNU peuvent être configurées à l'aide de l'option <tt>--prefix=/mon/option</tt>. Les pages de manuel correspondantes seront alors installées à partir du répertoire de base /mon/option/man. Nous vous conseillons d'employer une méthode similaire pour vos réalisations personnelles. <sect1> Il n'y a pas que l'anglais au monde... Depuis l'avènement du <sq>Système de fichiers standard</sq> pour <bf/Linux/ (FSSTnd), les choses se sont un petit peu compliquées. Ce standard stipule que la structure de /usr/man doit être prévue pour plusieurs jeux de pages de manuels, correspondant à différents langages, en raison de l'internationalisation du système. Il est alors introduit un niveau d'arborescence supplémentaire qui distingue chaque langue. Voici ce qui est dit dans la version 1.2 de ce standard : <quote><sf> Le nom des sous-répertoires de langages de /usr/man est basé sur l'annexe E du standard POSIX 1003.1, qui décrit la chaîne d'identification locale ; celle-ci constituant la méthode la mieux acceptée pour décrire un environnement culturel. Cette chaîne locale est formée ainsi : </sf> <verb> <langage>[_<pays>][.<jeu-de-caractères>][,<version>] </verb> </quote> Consultez le standard pour obtenir les chaînes les plus courantes dans nos contrées. En fonction de ces recommandations, nous aurons donc nos pages de manuel dans /usr/man/<locale>/man[1-9lno]. Les versions formatées se trouveraient alors bien entendu dans /usr/man/<locale>/cat[1-9lno] ; nous pourrions aussi ne les fournir que pour une seule langue. Toutefois, je (l'auteur du document, pas le traducteur) ne peut pas recommander d'employer cette structure en l'état actuel des choses. Le standard <bf/Linux/ indique aussi que <sq>les systèmes n'utilisant qu'un seul langage et qu'un seul jeu de caractères pour toutes les pages de manuel peuvent omettre le sous-répertoire locale et stocker les fichiers dans mandir</sq>. Par exemple, sur les machines uniquement équipées pour la langue anglaise, qui n'utilise que le code ASCII, on peut placer les sous-répertoires man[1-9] directement dans /usr/man (en fait, il s'agit de l'emplacement traditionnel et c'est le cas le plus fréquent ; c'est ainsi que sont organisés tous les systèmes par défaut). Je (l'auteur du document, pas le traducteur) ne changerai pas ma configuration tant que tous les outils (comme <tt>xman</tt>, <tt/info/, <tt/tkman/ et beaucoup d'autres) ne seront pas tous adaptés à cette nouvelle structure. <sect> À quoi une page de manuel formatée doit-t-elle ressembler ? Pour répondre à cette question, le mieux est de présenter un exemple pratique. En raison de la nature et du mode de réalisation ce ce document, nous ne pouvons pas reproduire les caractères accentués, ni les différents enrichissements du texte (gras et italiques principalement) ; consultez la section traitant des polices de caractères pour obtenir des détails sur ces possibilités. Voici comment se présente la page de manuel de notre programme hypothétique <sq><tt/prout/</sq> : <tscreen><verb> PROUT(1) Manuel utilisateur PROUT(1) NAME prout - proutibule la bibliothèque plaf SYNOPSIS prout [-plaf] [-c fichier-config ] fichier ... DESCRIPTION prout proutibule la bibliothèque plaf en mouglifiant la table des symboles. Par défaut, la commande recherche tous les segments glurb et les trie par ordre bêtagonique décroissant afin que le gloupeur gloup(1) les trouve. L'entrée symdef est alors compactée selon l'algorithme NABOB. Les fichiers sont traités dans leur ordre d'apparition sur la ligne de commandes. OPTIONS -b N'affiche pas `bidouille en cours' sur la sortie standard pendant le traitement. -c fichier-config Utilise le fichier de configuration fichier-config au lieu du fichier global /etc/prout.conf. Cela supprime aussi l'effet de la variable d'environnement PROUTCONF. -a Traite également les en-têtes froutz en plus des segments glurb. -r Mode récursif. Fonctionne à la vitesse de la lumière, mais nécessite plusieurs mégaoctets de mémoire virtuelle. FICHIERS /etc/prout.conf Fichier de configuration général, pour tout le système. Voir prout(5) pour plus de détails. ~/.proutrc Fichier de configuration propre à chaque utilisa teur. Voir prout(5) pour plus de détails. ENVIRONNEMENT PROUTCONF Si elle existe, cette variable peut contenir le chemin d'accès complet à un autre fichier de con figuration global prout.conf. L'option -c rend cette variable inopérante. DIAGNOSTICS Les messages suivants peuvent être affichés sur la sortie standard d'erreurs : Mauvais nombre magique. Le fichier d'entrée ne semble pas être un fichier archive. Segments glurb ancien style. prout ne peut traiter que le nouveau style de seg ments glurb. Les bibliothèques GROBOL ne sont pas supportées dans cette version. BOGUES Le nom de cette commande aurait du être choisi de manière à mieux refléter sa fonction. AUTEUR Marcel Dugenou <dugenou@renux.freenix.fr> VOIR AUSSI gloup(1), plaf(1), prout(5). Linux JANVIER 1996 1 </verb></tscreen> Et voici les explications promises. <descrip> <tag>La section <tt>NAME</tt></tag> C'est la seule section indispensable. Les pages de manuel sans section <tt/NAME/ sont aussi inutiles qu'un réfrigérateur au pôle nord. Cette section possède aussi un format standardisé consistant en une liste de noms de programmes ou de fonctions suivis d'un tiret ou d'une courte description (une ligne en général) des fonctionnalités, l'élément séparateur de cette liste étant la virgule. C'est le format exploité par l'utilitaire <tt/makewhatis(8)/, qui analyse ces noms de section pour les intégrer dans la base de données <tt/whatis/ : Voilà pourquoi il est important de respecter cette organisation. Dans le code source <tt/groff/, cela donne quelque chose comme ceci : <verb> .SH NAME prout \- proutibule la bibliothèque plaf </verb> Le <sq>backslash</sq> est très important : cette contre-oblique est nécessaire pour que le tiret qui suit soit distingué d'une marque de césure, qui peut apparaître aussi bien dans le nom de commande que dans la ligne de description. <bf/Attention/ : en l'état actuel des choses, vous ne pouvez pas traduire <tt/NAME/ par <tt/NOM/ en français, à moins de modifier la plupart des programmes <tt/makewhatis/ existants. C'est bien dommage... <tag>La section <tt>SYNOPSIS</tt></tag> Elle permet de donner un court aperçu des options du programme. Dans le cas des fonctions, cette section contient les fichiers d'en-têtes qu'il est nécessaire d'inclure, ainsi que le prototype afin que le programmeur connaisse immédiatement le type et le nombre des arguments demandés ainsi que le type de la valeur de retour. <tag>La section <tt>DESCRIPTION</tt></tag> C'est elle qui explique en détail pourquoi votre séquence de 0 et de 1 est meilleure que toutes les autres. C'est ici que vous étalez tout votre savoir ! Gagnez l'estime des autres développeurs et l'admiration des utilisateurs en faisant de cette section la référence absolue, contenant toutes les informations possibles sur votre application, avec force détails. Expliquez clairement le rôle de chaque argument, décrivez le format des fichiers utilisés, les algorithmes qui effectuent le plus dur du travail, etc. <tag> La section <tt>OPTIONS</tt></tag> Elle donne une description de chaque option modifiant le comportement du programme. Vous deviez vous en douter... <tag> La section <tt>FICHIERS</tt></tag> Elle indique quels sont les fichiers utilisés par le programme ou la fonction. Ce sont par exemple les fichiers de configuration et d'initialisation auxquels il est directement fait appel. Il est toujours préférable de donner leur chemin d'accès complet et de se débrouiller pour que la procédure d'installation modifie la partie répertoire de ces chemins dans la page de manuel, en fonction des préférences de l'utilisateur. Pour citer un exemple, l'application GNU <tt>groff</tt> s'installe par défaut dans /usr/local, les pages de manuel référencent donc /usr/local/lib/groff/*. Mais si vous l'installez par <sq><tt>make prefix=/opt/gnu</tt></sq>, toutes les pages de manuel seront modifiées pour indiquer /opt/gnu/lib/groff/*. <tag> La section <tt>ENVIRONNEMENT</tt></tag> Indique toutes les variables d'environnement prises en compte par votre programme ou votre fonction, et leur action. La plupart du temps, ces variables contiennent des chemins d'accès, des noms de fichiers ou des options par défaut. <tag> La section <tt>DIAGNOSTICS</tt></tag> Elle doit donner un aperçu des messages d'erreur les plus courants susceptibles d'être affichés par le programme, et les éventuelles solutions à ces problèmes. Il n'est pas nécessaire de citer les messages d'erreur du système (issus de <tt>perror(3)</tt>) ou fatals (issus de <tt>psignal(3)</tt>) car ils peuvent apparaître durant l'exécution de n'importe quel programme. <tag> La section <tt>BOGUES</tt></tag> Dans un monde idéal, cette section n'aurait pas lieu d'être ! Si vous êtes brave, vous pourrez décrire ici les limites et les inconvénients de votre application, voire les caractéristiques que certains pourraient considérer comme des défauts. Sinon, faites la même liste mais renommez cette section <sq><tt>A FAIRE</tt></sq>... <tag> La section <tt>AUTEUR</tt></tag> Elle est très utile pour savoir qui a fait quoi, et pour trouver l'adresse à laquelle envoyer un rapport de bogue en cas d'erreur grossière dans la documentation (ce qui ne devrait pas arriver !) ou d'un comportement anormal du programme. <tag> La section <tt>VOIR AUSSI</tt></tag> C'est une liste de pages de manuel relatives à l'application, citées par ordre alphabétique. Par convention, c'est la dernière section. </descrip> Vous êtes libre d'inventer toute autre section, si le cas à traiter ne peut se classer dans aucune de celles que nous venons d'énumérer. Nous avons volontairement décrit une version francisée de page de manuel, puisque ce document est destiné aux pays francophones. Néanmoins, vous devez avoir conscience que si vous devez diffuser une application dans le monde entier, il vous faudra fournir un manuel en langue anglaise (ce qui est la version standard, traditionnelle), et que les noms <sq>officiels</sq> de ces sections sont en réalité, dans l'ordre : <tt>NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, ENVIRONMENT, DIAGNOSTICS, BUGS, AUTHOR</tt> et <tt>SEE ALSO</tt>. Tout cela est très bien, mais comment générer cette belle page de manuel ? Nous nous attendions à cette question ! Alors, voici le code source complet : <verb> .\" Formater ce fichier par la commande : .\" groff -man -Tlatin1 prout.1 (si vous avez saisi des accents Iso-8859-1) .\" groff -man -Tascii prout.1 (cas général ) .\" .TH PROUT 1 "JANVIER 1996" Linux "Manuel utilisateur" .SH NAME prout \- proutibule la bibliothèque plaf .SH SYNOPSIS .B prout [-plaf] [-c .I fichier-config .B ] .I fichier .B ... .SH DESCRIPTION .B prout proutibule la bibliothèque plaf en mouglifiant la table des symboles. Par défaut, la commande recherche tous les segments glurb et les trie par ordre bêtagonique décroissant afin que le gloupeur .BR gloup (1) les trouve. L'entrée symdef est alors compactée selon l'algorithme NABOB. Les fichiers sont traités dans leur ordre d'apparition sur la ligne de commandes. .SH OPTIONS .IP -b N'affiche pas `bidouille en cours' sur la sortie standard pendant le traitement. .IP "-c fichier-config" Utilise le fichier de configuration .I fichier-config au lieu du fichier global .IR /etc/prout.conf . Cela supprime aussi l'effet de la variable d'environnement .B PROUTCONF. .IP -a Traite également les en-têtes froutz en plus des segments glurb. .IP -r Mode récursif. Fonctionne à la vitesse de la lumière, mais nécessite plusieurs mégaoctets de mémoire virtuelle. .SH FICHIERS .I /etc/prout.conf .RS Fichier de configuration général, pour tout le système. Voir .BR prout (5) pour plus de détails. .RE .I ~/.proutrc .RS Fichier de configuration propre à chaque utilisateur. Voir .BR prout (5) pour plus de détails. .SH ENVIRONNEMENT .IP PROUTCONF Si elle existe, cette variable peut contenir le chemin d'accès complet à un autre fichier de configuration global .IR prout.conf . L'option .B -c rend cette variable inopérante. .SH DIAGNOSTICS Les messages suivants peuvent être affichés sur la sortie standard d'erreurs : Mauvais nombre magique. .RS Le fichier d'entrée ne semble pas être un fichier archive. .RE Segments glurb ancien style. .RS .B prout ne peut traiter que le nouveau style de segments glurb. Les bibliothèques GROBOL ne sont pas supportées dans cette version. .SH BOGUES Le nom de cette commande aurait du être choisi de manière à mieux refléter sa fonction. .SH AUTEUR Marcel Dugenou <dugenou@renux.freenix.fr> .SH "VOIR AUSSI" .BR gloup (1), .BR plaf (1), .BR prout (5). </verb> <sect> Comment documenter plusieurs choses dans une seule page ? De nombreux programmes (<tt>grep</tt>, <tt>egrep</tt>) et fonctions (<tt/printf/, <tt/fprintf/, ...) sont décrits dans un seul document. Toutefois, cette documentation serait quasiment inutile si elle n'était accessible que sous un seul nom. Nous ne pouvons pas demander aux utilisateurs de mémoriser que la page de manuel de <tt/egrep/ est en réalité celle de <tt/grep/. Il est par conséquent indispensable que la page soit accessible sous plusieurs noms différents. Il existe plusieurs possibilités pour obtenir cela : <enum> <item> réaliser plusieurs copies du document, une par nom ; <item> connecter toutes ces pages par des liens physiques ; <item> plusieurs liens symboliques pointant vers un unique document ; <item> faire appel au mécanisme de <sq>source</sq> de <tt/groff/, en employant la macro-instruction <sq><tt>.so</tt></sq>. </enum> La première solution est une perte de place, il faut l'éviter. La seconde n'est pas recommandée, car les versions <sq>intelligentes</sq> de l'utilitaire <tt/catman/ peuvent gagner beaucoup de temps en détectant le type ou le contenu du fichier. Les liens matériels réduiront l'efficacité de cet outil (dont le but est de formater à l'avance toutes les pages de manuel existantes afin qu'elles s'affichent toutes rapidement, sans que l'utilisateur doive attendre le temps nécessaire à ce traitement éventuel). La troisième solution comporte un piège : si vous êtes concerné par la portabilité, vous devez savoir qu'il existe des systèmes de fichiers ne connaissant pas les liens symboliques. En conclusion, la meilleure chose à faire consiste à employer la macro <sq><tt>.so</tt></sq>. Voici comment opérer : si vous désirez que votre page de manuel soit accessible par les noms <sq>truc</sq> et <sq>bidule</sq> dans la section 1, mettez le document dans <tt/truc.1/ et réalisez un fichier <tt/bidule.1/ contenant ceci : <verb> .so man1/truc.1 </verb> Il est très important de ne pas oublier le répertoire <em/man1/, car lors de l'exécution de <tt/groff/, celui-ci aura comme répertoire courant le répertoire de base des pages de manuel, et il interprètera les arguments à <tt/.so/ comme étant relatifs à cet emplacement. <sect> Quel ensemble de macros choisir ? Il existe un certain nombre de jeux de macros étudiés spécialement pour la confection de pages de manuel. On les trouve généralement dans le répertoire /usr/lib/groff/tmac. Les noms des fichiers sont du genre tmac.<quelque-chose>, où <quelque-chose> est l'argument passé à l'option <tt/-m/ de <tt/groff/. Souvent, l'espace entre <tt/-m/ et <quelque-chose> est omis, de sorte que l'on peut écrire <tt/groff -man/ lorsque l'on désire formater des pages utilisant le jeu de macros <em/tmac.an/. Voilà la raison de ce nom bizarre, <sq><em/tmac.an/</sq>. En plus de ce <em/tmac.an/, il existe un autre ensemble de macros très populaire, <em/tmac.doc/, qui provient de l'université de Berkeley, Californie (UCB). De nombreuses pages de manuel BSD l'utilisent et il semble que l'UCB en ait fait un standard pour la documentation. Les macros <em/tmac.doc/ sont bien plus souples mais malheureusement, beaucoup d'outils de lecture du manuel n'y font pas appel et utilisent toujours la commande <tt/groff -man/. Par exemple, tous les programmes <tt/xman/ que nous avons rencontrés affichent n'importe quoi lorsqu'ils rencontrent des pages prévues pour ces macros <em/tmac.doc/. Alors, vous devez vous résigner : n'utilisez que <em/tmac.an/ (l'emploi de tout autre ensemble de macros est très risqué). Le jeu <em/tmac.andoc/ est un pseudo ensemble de macros qui analyse le code source et charge soit <em/tmac.an/, soit <em/tmac.doc/ selon son contenu. En fait, tous les programmes d'exploitation du manuel devraient l'utiliser, mais jusqu'à présent peu le font, aussi il vaut mieux assurer le coup en se cantonnant au bon vieux <em/tmac.an/. À partir de maintenant, tout ce que nous décrirons concernant les macros ne sera valable que pour <em/tmac.an/. <footnote> Si vous voulez malgré tout employer les macros <em/tmac.andoc/, voici un pointeur vers leur documentation et un mode d'emploi très détaillé : <url url="http://www.bsdi.com/bsdi-man">. Vous trouverez un formulaire de recherche sur cette page. Entrez <tt/mdoc/ et il vous trouvera <tt/mdoc(7)/ et <tt/mdoc.samples(7)/, un didacticiel sur la réalisation des pages de manuel BSD. </footnote> <sect> Quels préprocesseurs utiliser ? <tt/Groff/ est fourni avec au moins trois préprocesseurs : <tt/tbl/, <tt/eqn/ et <tt/pic/ (sur certains systèmes ils se nomment <tt/gtbl/, <tt/geqn/ et <tt/gpic/). Ils sont destinés à traduire des macro-instructions de pré-traitement et leurs arguments en code source <tt/troff/ standard. Le programme <tt/tbl/ est un préprocesseur de tableaux, <tt/eqn/ gère les équations et les mathématiques en général, et enfin <tt/pic/ est un préprocesseur d'images. Consultez leurs pages de manuel respectives pour découvrir les fonctionnalités qu'ils proposent. Mais autant être clair : n'écrivez jamais de pages de manuel nécessitant quelque préprocesseur que ce soit. <tt/Eqn/ produira généralement une sortie catastrophique pour les périphériques du genre télétype ; malheureusement 99% des terminaux sur lesquels sont lues les pages de manuel en font partie. Par exemple, <em/XAllocColor.3x/ contient quelques expressions mathématiques avec des exposants. En raison de la nature des périphériques d'affichage, ces exposants se retrouveront sur la même ligne que le texte de base : <sq>N puissance deux</sq> s'affichera <sq><tt>N2</tt></sq>. Il faut éviter <tt/tbl/ car tous les programmes <tt/xman/ que nous avons rencontrés ne fonctionnent pas avec lui. <tt/Xman 3.1.6/ utilise la ligne de commande suivante pour formater les pages de manuel, par exemple <tt/signal(7)/ : <verb> gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \ > /tmp/xmana01760 2> /dev/null </verb> Elle coince sur toutes les sources utilisant <tt/gtbl/, car sa sortie est renvoyée une fois de plus dans son entrée. Le résultat donne une page de manuel sans le tableau voulu. Nous ne savons pas s'il s'agit d'un bogue ou d'une particularité de <tt/gtbl/, qui n'aime pas sa propre sortie, ou si <tt/xman/ devrait être un peu plus gentil et ne pas l'appeler deux fois... Quoi qu'il en soit, si vous voulez un tableau, formatez-le vous-même et insérez-le entre deux lignes <tt>.nf</tt> et <tt>.ni</tt> de sorte qu'il ne soit pas traité plus tard. Vous ne pourrez pas obtenir de gras ou d'italiques par cette méthode, mais cela vous évitera de voir votre beau tableau disparaître au hasard des systèmes d'exploitation employés. Nous n'avons encore jamais rencontré de page de manuel nécessitant un traitement par <tt/pic/. Mais nous n'aimerions pas ça ! Comme vous pouvez le voir dans l'exemple ci-dessus, <tt/xman/ ne l'appelle jamais et les données lui étant destinées donneraient sans doute le vertige à ce pauvre <tt/groff/. <sect> Distribution : code source et/ou documentation formatée ? Voyons les avantages <tt/(+)/ et les inconvénients <tt/(-)/ de quelques combinaisons possibles : <enum> <item> code source uniquement : <itemize> <item> <tt/(+)/ taille de la distribution très réduite ; <item> <tt/(-)/ inutilisable sur les systèmes démunis de <tt/groff/. </itemize> <item> version formatée non compactée uniquement : <itemize> <item> <tt/(+)/ utilisable même sur les systèmes dépourvus de <tt/groff/ ; <item> <tt/(-)/ l'utilisateur ne peut pas générer de fichier <tt/DVI/ ou <em/PostScript/ ; <item> <tt/(-)/ gâchis de place disque sur les systèmes sachant aussi gérer les pages compactées. </itemize> <item> version formatée et compactée uniquement : <itemize> <item> <tt/(+)/ utilisable même sur les systèmes dépourvus de <tt/groff/ ; <item> <tt/(-)/ l'utilisateur ne peut pas générer de fichier <tt/DVI/ ou <em/PostScript/ ; <item> <tt/(-)/ quel format de compactage utiliser ? <tt/.Z/ ? <tt/.z/ ? <tt/.gz/ ? Tous les trois ? </itemize> <item> code source plus version formatée non compactée : <itemize> <item> <tt/(+)/ accessible même sur les systèmes démunis de <tt/groff/ ; <item> <tt/(-)/ taille de la distribution plus importante ; <item> <tt/(-)/ certains systèmes peuvent nécessiter des pages formatées compressées ; <item> <tt/(-)/ informations redondantes sur les systèmes équipés de <tt/groff/. </itemize> </enum> À notre avis, la meilleure solution est de distribuer uniquement le code source. Le fait que cette documentation ne pourra pas être exploitée sur une machine sur laquelle <tt/groff/ n'est pas installé n'a aucune importance. Plus de 500 pages de manuel du <em/projet de documentation Linux/ ne sont fournies que sous forme de code source. Les pages de manuel de <tt/XFree86/ ne sont disponibles que sous forme de code source. Les pages de manuel de la <tt/FSF/ n'existent que sous forme de code source. En fait, nous n'avons pratiquement jamais rencontré de logiciels distribués avec leurs pages de manuel préformatées. Si un administrateur a vraiment besoin d'accéder aux pages de manuel de son système, il aura forcément installé <tt/groff/. <sect> Fontes disponibles et conventions typographiques N'utilisez jamais des opérateurs directs comme <tt>\fB \fP</tt>, etc. Employez des macros qui prennent des arguments, vous éviterez ainsi l'erreur classique : l'oubli du changement de fonte à la fin d'un mot, qui provoque la continuation du gras ou de l'italique jusqu'au changement suivant. Croyez-nous, c'est une erreur bien plus fréquente que vous ne pouvez l'imaginez ! Les macros <em/tmac.an/ offrent les possibilités suivantes :  <verb> .B caractères gras .BI gras et italiques en alternance .BR gras et romain en alternance .I italiques .IB italiques et gras en alternance .IR italiques et romain en alternance .RB romain et gras en alternance .RI romain et italiques en alternance .SM taille réduite (9/10 du corps normal) .SB gras, taille réduite (tout le texte, pas d'alternance) </verb> X en alternance avec Y signifie que les arguments impairs seront imprimés en X et les pairs en Y. Par exemple : <verb> .BI "Arg 1 est gras, " "arg2 est en italiques, " "arg3 est en gras." </verb> Les caractères de protection (<tt>" "</tt>) sont nécessaires pour placer des espaces dans ces arguments. Voilà donc pour ce qui est disponible. Voyons maintenant comment il faut utiliser ces possibilités (nous avons honteusement copié ce qui est décrit dans <tt/man(7)/) : Bien qu'il existe dans le monde UNIX de nombreuses conventions typographiques arbitraires pour la réalisation de pages de manuel, plusieurs centaines de pages spécifiques à Linux se conforment au standard suivant : Les fonctions et les arguments sont toujours indiqués en italiques, même dans la section <tt/SYNOPSYS/, le reste de la fonction étant imprimé en corps gras : <verb> .BI "mafonction(int " argc ", char **" argv ); </verb> Les noms de fichiers sont toujours en italiques, sauf dans la section <tt/SYNOPSYS/, où les fichiers à inclure sont en gras. Vous écrirez donc : <verb> .I /usr/include/stdio.h .B #include <stdio.h> </verb> Les noms de macros, qui sont la plupart du temps en majuscules, sont typographiés en gras : <verb> .B MAXINT </verb> Dans les énumérations de codes d'erreur, les codes sont en gras. Cette liste fait généralement appel à la macro <tt/.TP/ (paragraphe avec titre) comme ci-dessous : <verb> .TP .B EBADF .I fd n'est pas un descripteur de fichier valide. .TP .B EINVAL .I fd a une valeur incorrecte. </verb> Toute référence à une autre page de manuel (ou au sujet de la page courante) est en gras. Si la section correspondante du manuel est indiquée, elle s'écrit en roman, sans espace : <verb> .BR man (7) </verb> Les acronymes sont plus élégants lorsqu'ils apparaissent dans un corps plus petit, nous vous recommandons par conséquent d'employer : <verb> .SM UNIX .SM ASCII .SM TAB .SM NFS .SM LALR(1) </verb> <sect> Conseils, trucs et astuces <sect1> Peaufinez votre page de manuel Voici quelques conseils pour améliorer la lisibilité, la validité des informations fournies et la facilité de formatage de votre documentation : <itemize> <item> vos exemples doivent fonctionner, testez-les (utilisez le couper/coller pour passer à votre shell le code exact indiqué dans la page de manuel), redirigez l'affichage dans votre fichier source (ne tapez pas vous-même ce que vous pensez que votre programme affichera) ; <item> relisez-vous, faites relire votre document par des tiers, corrigez toutes les éventuelles fautes de frappe ou d'orthographe (surtout si vous ne rédigez pas le texte dans votre langue natale) ; <item> testez votre page : est-ce que <tt/groff/ trouve des erreurs lors du formatage ? Il est agréable de trouver dans un commentaire la commande nécessaire pour formater le document. Est-ce que <tt/man(1)/ affiche des avertissement ou des erreurs lorsque vous tapez <sq><tt/man votre-programme/</sq> ? Est-ce que la façon dont <tt/man(1)/ utilise les outils de formatage produit les résultats escomptés ? Est-ce que cela fonctionne aussi bien avec <tt/xman(1x)/ et <tt/tkman(1tk)/ ? <tt/XFree86 3.1/ contient la version <tt/3.1.6/ de <tt/xman/, qui décompacte les pages par ces commandes : <verb> gzip -c -d < %s > %s zcat < %s > %s </verb> <item> est-ce que <tt/makewhatis(8)/ arrive a extraire les descriptions sur une ligne de la section <tt/NAME/ ? </itemize> <sect1> Comment obtenir une sortie pur ascii sans ces fichus caractères de contrôle ? Jetez un coup d'oeil à <tt/col(1)/ ; il s'agit d'un filtre qui peut éliminer ces séquences de surimpression. Au cas où vous seriez trop paresseux pour réfléchir vous-même au problème, voici la commande magique : <verb> $ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt </verb> Les options <tt>-t</tt> et <tt>-e</tt> indique à <tt/groff/ de faire appel aux préprocesseurs <tt/tbl/ et <tt/eqn/. C'est inutile pour les pages de manuel ne nécessitant aucun pré-traitement, mais cela ne gêne pas, si ce n'est par la petite charge supplémentaire induite. En revanche, ne pas utiliser <tt/-t/ lorsque ce serait nécessaire est une très mauvaise chose : le tableau sera extrêmement mal formaté. Vous pourrez même trouver (deviner serait un terme plus exact) la commande nécessaire pour traiter tel ou tel document <tt/groff/ (pas uniquement des pages de manuel) par le biais de <tt/grog/ : <verb> $ grog /usr/man/man7/signal.7 groff -t -man /usr/man/man7/signal.7 </verb> En fait, <sq><tt>grog</tt></sq> signifie <sq>GROff Guess</sq>, et cet outil fait bien ce qu'il dit (en anglais...) : il tente de deviner la commande nécessaire pour formater un document <tt>groff</tt> en fonction de son contenu. S'il était parfait, nous n'aurions jamais plus besoin d'options. Mais il arrive qu'il détermine un mauvais jeu de macros ; nous ne l'avons par contre jamais vu se tromper sur les préprocesseurs à employer. Voici un petit script <tt/perl/ réalisé par l'auteur de ce document, qui peut supprimer les en-têtes et les pieds de page, ce qui permet de gagner quelques feuilles de papier lorsque l'on imprime de longues et complexes pages de manuel. Sauvez-le dans un fichier nommé <em/strip-header/ et donnez-lui le mode 755. <verb> #!/usr/bin/perl -n # make it slurp the whole file at once: undef $/; # delete page breaks: s/\n{4}\S.{50,}\n{6}\S.{50,}\n{3}/\n/g; # delete first header & last footer: s/\n\S.{50,}\n//g; # collapse two or more blank lines into a single one: s/\n{3,}/\n\n/g; # see what's left... print; </verb> Il faut appeler ce programme en tant que premier filtre après la comande <tt/man/, car il se base sur le nombre de sauts de ligne issus de <tt/groff/. Par exemple: <verb> $ man bash | strip-headers | col -bx > bash.txt </verb> <sect1> Comment obtenir une sortie PostScript de haute qualité ? C'est très simple : <verb> $ groff -t -e -mandoc -Tps manpage.1 > manpage.ps </verb> Imprimez <em/manpage.ps/ avec votre imprimante PostScript préférée. Consultez la section précédente pour obtenir des explications sur les options. <sect1> Comment faire fonctionner les commandes <tt/apropos/ et <tt/whatis/ ? Supposons que vous recherchiez quels sont les compilateurs installés sur votre système, et comment les invoquer( nous considérons le cas courant, ou tout le manuel est en langue anglaise). Pour répondre à cette question (fréquemment posée), il faut faire : <verb> $ apropos compiler f77 (1) - Fortran 77 compiler gcc (1) - GNU C and C++ compiler pc (1) - Pascal compiler </verb> Les commandes <tt/apropos/ et <tt/whatis/ sont destinées à obtenir rapidement le nom de la page de manuel traitant de tel ou tel sujet. Tous deux font appel à un certain nombre de fichiers nommés <sq>whatis</sq>, que l'on peut trouver dans chaque répertoire de base du manuel. Comme nous l'avons dit auparavant, cette base de données <em/whatis/ contient une entrée d'une ligne pour chaque page de manuel présente dans l'arborescence correspondante. En fait, cette ligne est exactement celle de la section <tt/NAME/ (pour être précis, tout est réduit à une seule ligne et le tiret est supprimé, la section étant placée entre parenthèses). Les fichiers constituant cette base de données sont créés par le programme <tt/makewhatis(8)/. Il en existe plusieurs versions, par conséquent nous ne pouvons que vous renvoyer à leur propre documentation pour leur utilisation. Afin que cet outil fonctionne correctement, il est nécessaire que vous, le rédacteur des pages de manuel, vous conformiez au format de la section <tt/NAME/ décrit plus haut dans ce document. La différence entre <tt/apropos/ et <tt/whatis/ est le mode de recherche et l'affichage obtenu : <tt/apropos/ (qui est équivalent à <tt/man -k/) recherche la chaîne passée en argument à n'importe quel endroit de la ligne, alors que <tt/whatis/ (équivalent à <tt/man -f/) recherche un nom de commande complet, uniquement sur la partie située avant le tiret. Par conséquent, <sq><tt>whatis cc</tt></sq> indiquera s'il existe une page de manuel pour <tt/cc/, mais ne dira rien à propos de <tt/gcc/. <sect1> La langue française C'est bien sûr à vous de décider si vous allez rédiger votre manuel en français, en anglais ou dans ces deux langues. Le français possède des règles typographiques très différentes de l'anglais : n'espérez pas pouvoir les respecter avec les outils de formatage du manuel. Consultez la documentation de <tt/groff/ si vous désirez lui faire prendre en compte les motifs de césure de la langue de Molière, mais en ayant conscience que ce ne sera sans doute pas possible sur tous les systèmes sur lesquels votre documentation est susceptible d'être exploitée. Vous pouvez utiliser les caractères accentués, pourvu qu'ils soient saisis selon la norme ISO-8859-1 (standard sous Linux). Les pages devront alors être formatées avec l'option <tt> -Tlatin1 </tt>. Mais il faudra que toute la chaîne de visualisation soit capable de gérer les caractères ISO sur 8 bits, ce qui est rarement le cas sans une configuration particulière des utilitaires <sq><tt>more</tt></sq> ou <sq><tt>less</tt></sq> généralement employés. Vous voilà prévenu ! <sect> Copyright Ce document est copyright (C) 1995 Jens Schweikhardt <tt/<jens@kssun3.rus.uni-stuttgart.de>/. Il peut être reproduit et distribué en tout ou partie, sur tout support physique ou électronique, à condition que cette notice soit incluse dans chacune des copies. Sa diffusion commerciale est autorisée et encouragée ; toutefois l'auteur désire être prévenu dans ce cas. Toute traduction, travail dérivé, ou compilation de travaux incluant quelque document Linux <em/HOWTO/ que ce soit doit être couvert par ce présent copyright. C'est-à-dire que vous ne pouvez pas réaliser un ouvrage dérivé d'un <em/HOWTO/ et imposer des restrictions supplémentaires sur sa distribution. Des dérogations à ces règles peuvent être accordées sous certaines conditions ; contactez le coordinateur à l'adresse donnée ci-après pour plus de précisions. En résumé, nous avons le désir de promouvoir la diffusion de ces informations par le plus de canaux possibles. Malgré tout, nous voulons conserver la propriété des documents <em/HOWTO/, et aimerions être tenu au courant de tout projet de redistribution. Si vous avez des questions, contactez Greg Hankins, le coordinateur, par courrier électronique à l'adresse <tt/gregh@sunsite.unc.edu/, ou par téléphone au +1 404 853 9989. </article>