/usr/share/doc/HOWTO/fr-html/Man-Page.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for HTML5 for Linux version 5.2.0">
<meta name="GENERATOR" content="LinuxDoc-Tools 0.9.72">
<title>Man page HOWTO</title>
</head>
<body>
<h1>Man page HOWTO</h1>
<h2>Auteur : Jens Schweikhardt <a href=
"mailto:schweikh@noc.dfn.de">schweikh@noc.dfn.de</a><br>
<a href=
"http://www.shuttle.de/schweikh/home.html">www.shuttle.de/schweikh/home.html</a></h2>
Mars 1998
<hr>
<em>(Adaptation française par Alexandre Devaure <a href=
"mailto:adevaure@mail.dotcom.fr">adevaure@mail.dotcom.fr</a>, 2
juin 1999). Ce HOWTO explique ce que vous devrez avoir en tête
quand vous prévoyez d'écrire une documentation en ligne (plus
connue sous le nom de page de manuel) que vous voulez rendre
accessible via la commande <code>man(1)</code>. Tout au long de ce
HOWTO, une entrée du manuel sera simplement appelée page de manuel,
quelque soit sa longueur réelle et sans intention sexiste.</em>
<hr>
<h2><a name="s1">1. Quelques évidences à propos de la
documentation</a></h2>
<p>Pourquoi écrivons-nous une documentation&nbsp;? C'est une
question bête. Parce que nous voulons que d'autres personnes
puissent utiliser notre programme, notre fonction dans une
librairie ou quoi que ce soit que nous avons écrit et rendu
disponible. Mais écrire une documentation n'est pas
suffisant&nbsp;:</p>
<ul>
<li>la documentation doit être accessible. Si elle est cachée à un
endroit non standard où les outils de recherche relatifs à la
documentation ne la trouveront pas, comment peut-elle remplir son
rôle&nbsp;?</li>
<li>la documentation doit être fiable et précise. Il n'y a rien de
plus irritant qu'un programme se comportant différemment de ce qui
est écrit dans sa documentation. Les utilisateurs vous maudiront,
vous enverront des courriers d'insulte, puis rejetteront à jamais
tout autre travail venant de vous.</li>
</ul>
La méthode traditionnelle pour accéder à la documentation sous UNIX
fait appel à la commande <code>man(1)</code>. Ce HOWTO décrit ce
que vous devez faire pour écrire une page de manuel qui sera
correctement traitée par les outils prévus à cet effet, dont les
plus importants sont <code>man(1)</code>, <code>xman(1x)</code>,
<code>apropos(1)</code>, <code>makewhatis(8)</code> et
<code>catman(8)</code>.
<p>La qualité et la véracité des informations sont, bien sûr, de
votre ressort. Malgré tout, vous trouverez dans ce guide quelques
idées qui vous permettront d'éviter certains pièges courants.</p>
<h2><a name="s2">2. Comment accède-t-on aux pages de manuel
?</a></h2>
<p>Vous devez 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 section spécifique, dénotée
par un simple chiffre. Les sections les plus courantes rencontrées
sous Linux sont :</p>
<ul>
<li>1 : commandes utilisateurs pouvant être exécutées par tout le
monde&nbsp;;</li>
<li>2 : appels systèmes, c'est-à-dire les fonctions fournies par le
noyau&nbsp;;</li>
<li>3 : fonctions des bibliothèques&nbsp;;</li>
<li>4 : périphériques, c'est-à-dire les fichiers spéciaux que l'on
trouve dans le répertoire <code>/dev</code>&nbsp;;</li>
<li>5 : descriptions des formats de fichiers (comme par exemple
<code>/etc/passwd</code>&nbsp;;</li>
<li>6 : les jeux, sans commentaire...</li>
<li>7 : divers (macros, conventions particulières, ...)&nbsp;;</li>
<li>8 : outils d'administration exécutables uniquement par le super
utilisateur&nbsp;;</li>
<li>9 : un autre endroit (spécifique à Linux) destiné à la
documentation des services offerts par le noyau&nbsp;;</li>
<li>n : nouvelle documentation, qui pourra être déplacée vers un
endroit approprié&nbsp;;</li>
<li>o : ancienne documentation, qui peut être conservée encore un
certain temps&nbsp;;</li>
<li>l : documentation locale, propre à ce système particulier.</li>
</ul>
Le nom du fichier source d'une page de manuel (le fichier d'entrée
du système de formatage) est le 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
"<i>passwd</i>", vous devez appeler le fichier source
"<i>passwd.5</i>". Nous avons ici un exemple d'un fichier qui porte
le même nom qu'une commande&nbsp;; nous aurions tout aussi bien
avoir une fonction de bibliothèque appelée "<i>passwd</i>".
L'organisation en sections constitue la méthode habituelle pour
résoudre ces ambiguïtés : la description de la commande se trouvera
dans le fichier "<i>passwd.1</i>" et notre hypothétique fonction de
bibliothèque dans "<i>passwd.3</i>".
<p>Quelquefois, une lettre est ajoutée au numéro de section comme
par exemple "<i>xterm.1x</i>" ou "<i>wish.1tk</i>". Le but de cette
notation est d'indiquer qu'il s'agit respectivement d'une
documentation d'un programme X Window ou d'une application Tk.
Certains programmes d'affichage du manuel peuvent exploiter cette
particularité ; <code>xman</code>, par exemple affichera
"<i>xterm(x)</i>" et "<i>wish(tk)</i>" dans la liste des documents
disponibles.</p>
<p>S'il vous plaît, n'utilisez pas les sections n, o et l&nbsp;:
selon le standard du système de fichiers (File System Standard),
ces sections sont déconseillées, utilisez plutôt les sections
numériques.</p>
<p>Attention aux éventuels conflits de noms avec des programmes,
fonctions ou fichiers déjà existants. Ce serait certainement une
mauvaise idée d'écrire un autre éditeur de texte et de le nommer
ed, sed (pour super ed) ou red (pour Roger edition). En vous
assurant que le nom de votre programme est unique, vous éviterez
que quelqu'un exécute votre programme et qu'il lise la page de
manuel d'un autre ou <i>vice verca</i>. Vous pouvez éventuellement
vous aider de la base de données "lsm" qui recense beaucoup de
programmes disponibles pour Linux.</p>
<p>Maintenant que nous savons quel nom donner à notre fichier, la
prochaine décision est de choisir le répertoire dans lequel nous
l'installerons (quand l'utilisateur lancera la commande "make
install"). Sous Linux, toutes les pages de manuel sont dans des
sous-répertoires à partir d'une racine mémorisée dans la variable
d'environnement MANPATH. Les outils de traitement de la
documentation l'utilisent de la même manière que le shell utilise
la variable PATH pour trouver les exécutables. En fait, MANPATH a
le même format que PATH : toutes les deux sont une liste de
répertoires séparés par des ":" (mais MANPATH n'autorise pas de
champs vides ou des chemins relatifs, seulement des chemins
absolus). Si MANPATH n'existe pas ou si elle n'est pas exportée,
/usr/man est utilisée comme valeur par défaut. Dans le but
d'accélerer la recherche et pour garder les répertoires de taille
raisonable, les répertoires pointés dans MANPATH (aussi appelés
répertoires de base) contiennent une multitude de sous-répertoires
nommés "<i>man&lt;s&gt;</i>" où &lt;s&gt; désigne le caractère
correspondant à la section présenté plus haut. Toutes les sections
ne sont pas représentées, il n'y a pas, par exemple de raison de
garder une entrée "<i>mano</i>". Vous pourrez y trouver également
des sous-répertoires appelés "<i>cat&lt;s&gt;</i>",
"<i>dvi&lt;s&gt;</i>" et "<i>ps&lt;s&gt;</i>", qui contiennent
toute la documentation formatée, prête à être affichée ou
imprimée&nbsp;: nous reviendrons sur ce sujet plus loin. Le seul
fichier à être présent à côté de ces sous-répertoires du répertoire
de base s'appelle "<i>whatis</i>". Le but et la création de ce
fichier sera décrit dans la section 11. La méthode la plus sûre
pour installer au bon endroit une page de manuel de la section "s"
est de mettre le fichier dans le répertoire
"<i>/usr/man/man&lt;s&gt;</i>". Toutefois, un bon
<code>Makefile</code> devra autoriser l'utilisateur de choisir un
autre répertoire de base, disons par exemple par le biais d'une
variable d'environnement que l'on pourrait nommer MANDIR. La
plupart des distributions GNU peuvent être configurées à l'aide de
l'option <code>--prefix=/nom/option</code>. Les pages de manuels
correspondantes seront alors installées à partir du répertoire de
base <i>/mon/option/man</i>. Je vous suggère d'utiliser une méthode
similaire pour vos réalisations personnelles.</p>
<p>Depuis l'avènement du "<i>Système de fichiers standard</i>" pour
Linux (FS-STnd), les choses se sont compliquées. Le FS-STnd 1.2
stipule que&nbsp;:</p>
<blockquote>des aménagements doivent être faits dans la structure
de <i>/usr/man</i> pour supporter des pages de manuel écrites dans
différentes (ou mutiples) langues.</blockquote>
<p>Ceci est fait en introduisant un niveau de répertoires
supplémentaire qui distingue les différentes langues. Citant encore
le FS-Stnd 1.2&nbsp;:</p>
<blockquote>Le nommage des sous-répertoires correspondants aux
langues de <i>/usr/man</i> est basé sur l'appendice E du standard
POSIX 1003.1 qui décrit la chaîne de caractères d'authentification
<i>locale</i> (qui est la méthode la mieux acceptée pour décrire un
environement culturel). La chaîne <i>locale</i> se présente sous la
forme
<pre>
            &lt;langage&gt;[_&lt;pays&gt;][.&lt;jeu-de-caracteres&gt;][,&lt;version&gt;]
          
</pre></blockquote>
(Reportez vous au FS-Stnd pour voir quelques chaînes
<i>locale</i>courantes.) D'après ces recommandations, nous avons
nos pages de manuel dans
<i>/usr/man/&lt;locale&gt;/man[1-9lno]</i>. Les versions formatées
se trouveraient alors bien entendu dans
<i>/usr/man/&lt;locale&gt;/cat[1-9lno]</i>&nbsp;: nous pourrions ne
les fournir que pour une seule langue.
<p>TOUTEFOIS, je (l'auteur du document, pas le traducteur) ne peut
pas recommander de passer a cette structure en l'état actuel des
choses. Le FS-Stnd 1.2 autorise aussi que</p>
<blockquote>les systèmes qui n'utilisent qu'une seule langue et jeu
de caractères pour toutes les pages de manuel peuvent omettre la
sous-chaîne <i>&lt;locale&gt;</i> et stocker toutes ces pages dans
le répertoire <i>mandir</i>. Par exemple, les machines équipées
seulement de pages de manuel en anglais codées en ASCII peuvent
mettre les pages de manuel (les répertoires <i>man[1-9]</i>)
directement dans <i>/usr/man/</i>. Il s'agit en fait de
l'arrangement habituel.</blockquote>
<p>Je (l'auteur du document, pas le traducteur) ne changerai pas ma
configuration tant que tous les outils (comme <code>xman</code>,
<code>info</code>, <code>tkman</code> et beaucoup d'autres) ne
seront pas tous adaptés à cette nouvelle structure.</p>
<h2><a name="s3">3. A quoi ressemble une page de manuel
formatée&nbsp;?</a></h2>
<p>Laissez-moi vous présenter un exemple que j'expliquerai plus
tard. En raison de la nature et du mode de réalisation de ce
document, nous ne pouvons pas reproduire les caractères accentués,
ni les différents enrichissements du texte (gras et italiques
principalement)&nbsp;; consultez la section traitant des polices de
caractères pour obtenir des détails sur ces possibilités.</p>
<p>Voici comment se présente la page de manuel de notre programme
hyphothétique "<code>prout</code>"&nbsp;:</p>
<pre>


      PROUT(1)                Manuel utilisateur               PROUT(1)


      NAME
             prout - proutibule la bibliotheque plaf

      SYNOPSIS
             prout [-plaf] [-c fichier-config ] fichier ...

      DESCRIPTION
             prout  proutibule  la  bibliotheque plaf en mouglifiant la
             table des symboles.  Par  defaut,  la  commande  recherche
             tous  les segments glurb et les trie par ordre betagonique
             decroissant afin que  le  gloupeur  gloup(1)  les  trouve.
             L'entree  symdef  est  alors  compactee selon l'algorithme
             NABOB.   Les  fichiers  sont  traites  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  egalement  les  en-tetes froutz en plus des
                    segments glurb.

             -r     Mode  recursif.  Fonctionne  a  la  vitesse  de  la
                    lumiere,  mais  necessite  plusieurs  megaoctets de
                    memoire virtuelle.

      FICHIERS
             /etc/prout.conf
                    Fichier de  configuration  general,  pour  tout  le
                    systeme. Voir prout(5) pour plus de details.
             ~/.proutrc
                    Fichier  de  configuration propre a chaque utilisa
                    teur. Voir prout(5) pour plus de details. 

      ENVIRONNEMENT
             PROUTCONF
                    Si elle existe, cette  variable  peut  contenir  le
                    chemin  d'acces  complet a un autre fichier de con
                    figuration global  prout.conf.   L'option  -c  rend
                    cette variable inoperante.

      DIAGNOSTICS
             Les  messages suivants peuvent etre affiches sur la sortie
             standard d'erreurs :

             Mauvais nombre magique.
                    Le fichier d'entree ne semble pas etre  un  fichier
                    archive.

             Segments glurb ancien style.
                    prout  ne peut traiter que le nouveau style de seg
                    ments glurb. Les bibliotheques GROBOL ne  sont  pas
                    supportees dans cette version.

      BOGUES
             Le  nom de cette commande aurait du etre choisi de maniere
             a mieux refleter sa fonction.

      AUTEUR
             Marcel Dugenou    &lt;dugenou@renux.freenix.fr&gt;

      VOIR AUSSI
             gloup(1), plaf(1), prout(5).

      Linux                      JANVIER 1996                         1
        
</pre>
<p>Et voici les explications promises&nbsp;:</p>
<dl>
<dt><b>La section NAME&nbsp;:</b></dt>
<dd>
<p>C'est la seule section requise. Les pages de manuel sans une
section "NAME" sont aussi utiles que des réfrigerateurs au Pôle
Nord. Cette section a aussi un format standardisé constitué d'une
liste de programmes ou noms de fonctions séparés par des virgules
suivie d'un tiret et d'une courte description (habituellement une
ligne) de la fonctionnalité que le programme (fonction ou fichier)
est supposé dispenser. A l'aide de <code>makewhatis(8)</code> les
sections NAME sont incluses dans les fichiers de la base de données
de <code>whatis</code>. <code>makewhatis</code> est la raison pour
laquelle la section NAME doit exister et pourquoi elle doit adhérer
au format que j'ai décrit. Dans le source groff, elle doit
ressembler à&nbsp;:</p>
<blockquote><code>.SH NAME prout \- proutibule de la bibliotheque
plaf</code></blockquote>
Le <code>\-</code> est important ici&nbsp;: le backslash sert a
faire la différence entre le tiret et une marque de césure qui peut
apparaître à l'intérieur du nom de la commande ou dans la ligne de
description.
<p><b>Attention</b>&nbsp;: en l'état actuel des choses, vous ne
pouvez pas traduire NAME par NOM en français, à moins de modifier
la plupart des programmes <code>makewhatis</code> existants. C'est
bien dommage.</p>
</dd>
<dt><b>La section SYNOPSYS</b></dt>
<dd>
<p>... est censée donner un aperçu sur les options du programme.
Pour les fonctions, cette section fait la liste des fichiers à
inclure et son prototype pour que le programmeur connaisse le type
et le nombre d'arguments ainsi que le type de retour.</p>
</dd>
<dt><b>La section DESCRIPTION</b></dt>
<dd>
<p>Elle explique en détail pourquoi votre séquence de 0 et de 1 est
la meilleure de toutes. C'est ici que vous étalez tout votre
savoir&nbsp;! Gagnez l'estime des autres programmeurs et des
utilisateurs en faisant de cette section une source d'information
sûre et détaillée. Expliquez à quoi servent les arguments, le
format de fichier, les algorithmes qui effectuent le plus dur du
travail.</p>
</dd>
<dt><b>La section OPTIONS</b></dt>
<dd>
<p>Elle donne une description pour chaque option, comment elle
affecte le fonctionnement du programme. Vous le saviez, n'est-ce
pas&nbsp;?</p>
</dd>
<dt><b>La section FICHIERS</b></dt>
<dd>
<p>Elle indique les fichiers utilisés par le programme ou la
fonction. Par exemple, les fichiers de configuration, les fichiers
de démarrage, les fichiers sur lesquels le programme agit. Ce
serait une bonne idée de donner les chemins absolus de ces fichiers
et d'avoir un processus d'installation qui modifie la partie
répertoire selon les préférences de l'utilisateur&nbsp;: les
manuels de <code>groff</code> ont comme préfixe par défaut
<i>/usr/local</i>, donc ils référencent
<i>/usrl/local/lib/groff/*</i> par défaut. Cependant, si vous
installez en utilisant "<code>make prefix=/opt/gnu</code>", les
références dans la page de manuel change en
<i>/opt/gnu/lib/groff/*</i>.</p>
</dd>
<dt><b>La section ENVIRONNEMENT</b></dt>
<dd>
<p>fait la liste de toutes les variables d'environnement qui
affectent votre programme ou fonction et, bien sûr, explique
comment. La plupart du temps, les variables contiendront les
chemins, nom de fichiers, options par défaut.</p>
</dd>
<dt><b>La section DIAGNOSTIQUES</b></dt>
<dd>
<p>Elle doit donner une vue d'ensemble des messages d'erreurs les
plus courants de votre programme et des éventuelles solutions à ces
problèmes. Il n'est pas nécessaire d'expliquer les messages
d'erreurs du système (de <code>perror(3)</code>) ou des signaux
fatals (de <code>psignal(3)</code>) qui peuvent apparaître pendant
l'exécution de tout programme.</p>
</dd>
<dt><b>La section BOGUES</b></dt>
<dd>
<p>Devrait idéalement ne pas exister. Si vous êtes brave, vous
pouvez décrire ici les limitations, les inconvénients, les
caractéristiques que certains pourraient prendre pour des défauts.
Si vous n'êtes pas brave, renommez-la en section "A FAIRE".</p>
</dd>
<dt><b>La section AUTEUR</b></dt>
<dd>
<p>Il est appréciable de l'avoir quand il y a des erreurs
grossières dans la documentation ou dans le comportement du
programme et que vous voulez envoyer un rapport de bogue.</p>
</dd>
<dt><b>La section VOIR AUSSI</b></dt>
<dd>
<p>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.</p>
</dd>
</dl>
Vous êtes libres d'en inventer d'autres si elles n'empietent pas
sur celles décrites au-dessus. 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
"officiels" de ces sections sont en réalité, dans l'ordre : NAME,
SYNOPSIS, DESCRIPTION, OPTIONS, FILES, ENVIRONMENT, DIAGNOSTICS,
BUGS, AUTHOR et SEE ALSO.
<p>Donc comment générer cette page de manuel ? J'attendais cette
question, voici le source&nbsp;:</p>
<pre>
 .\" 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 general )
 .\"
 .TH PROUT 1 "JANVIER 1996" Linux "Manuel utilisateur"
 .SH NAME
 prout \- proutibule la bibliotheque plaf
 .SH SYNOPSIS
 .B prout [-plaf] [-c
 .I fichier-config
 .B ]
 .I fichier
 .B ...
 .SH DESCRIPTION
 .B prout
 proutibule la bibliotheque plaf en mouglifiant la table des symboles.
 Par defaut, la commande recherche tous les segments glurb et les trie
 par ordre betagonique decroissant afin que le gloupeur 
 .BR gloup (1)
 les trouve. L'entree symdef est alors compactee selon l'algorithme NABOB.
 Les fichiers sont traites 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 egalement les en-tetes froutz en plus des segments glurb.
 .IP -r
 Mode recursif. Fonctionne a la vitesse de la lumiere, mais necessite
 plusieurs megaoctets de memoire virtuelle.
 .SH FICHIERS
 .I /etc/prout.conf
 .RS
 Fichier de configuration general, pour tout le systeme. Voir
 .BR prout (5)
 pour plus de details.
 .RE
 .I ~/.proutrc
 .RS
 Fichier de configuration propre a chaque utilisateur. Voir
 .BR prout (5)
 pour plus de details.
 .SH ENVIRONNEMENT
 .IP PROUTCONF
 Si elle existe, cette variable peut contenir le chemin d'acces complet
 a un autre fichier de configuration global
 .IR prout.conf .
 L'option
 .B -c
 rend cette variable inoperante.
 .SH DIAGNOSTICS
 Les messages suivants peuvent etre affiches sur la sortie standard d'erreurs :
 
 Mauvais nombre magique.
 .RS
 Le fichier d'entree ne semble pas etre un fichier archive.
 .RE
 Segments glurb ancien style.
 .RS
 .B prout
 ne peut traiter que le nouveau style de segments glurb. Les bibliotheques
 GROBOL ne sont pas supportees dans cette version.
 .SH BOGUES
 Le nom de cette commande aurait du etre choisi de maniere a mieux
 refleter sa fonction.
 .SH AUTEUR
 Marcel Dugenou    &lt;dugenou@renux.freenix.fr&gt;
 .SH "VOIR AUSSI"
 .BR gloup (1),
 .BR plaf (1),
 .BR prout (5).
        
</pre>
<h2><a name="s4">4. Comment documenter plusieurs choses dans une
seule page de manuel&nbsp;?</a></h2>
<p>De nombreux programmes (<code>grep</code>, <code>egrep</code>)
et fonctions (<code>printf</code>, <code>fprintf</code>,...) sont
documentées dans une seule page de manuel. Cependant, ces pages
seraient inutilisables si elles n'étaient accessibles que par un
seul nom. Nous ne pouvous nous attendre à ce qu'un utilisateur se
souviennent que la page de manuel de <code>egrep</code> est en fait
celle de <code>grep</code>. Il est par conséquent indispensable que
la page soit accessible sous différents noms. Vous avez plusieurs
possibilités pour y arriver&nbsp;:</p>
<ol>
<li>avoir des copies identiques pour chaque nom&nbsp;;</li>
<li>connecter toutes les pages de manuels en utilisant des liens
physiques&nbsp;;</li>
<li>utiliser les liens symboliques pointant la page de
manuel&nbsp;;</li>
<li>utiliser le mécanisme de "source" de <code>groff</code> fournie
par la macro "<code>.SO</code>".</li>
</ol>
La première possibilité est une perte de place. La deuxième n'est
pas recommandée parce que les versions intelligentes du programme
<code>catman</code> peuvent gagner beaucoup de temps en regardant
le type du fichier et son contenu. Les liens physiques réduiraient
l'efficacité de cet outil (dont le but est de formater toutes les
pages de manuel pour qu'elles soient affichées plus rapidement). La
troisième alternative comporte un piège si vous êtes concerné par
la portabilité, vous devez savoir qu'il existe des systèmes de
fichiers qui ne supportent pas les liens symboliques. En bref, la
Meilleure Chose (TM) est d'utiliser le mécanisme source de
<code>groff</code>.
<p>Voila comment l'utiliser&nbsp;: si vous voulez que votre page
soit accessible sous les noms <code>truc</code> et
<code>bidule</code> dans la section 1, alors mettez la page de
manuel dans <code>truc.1</code> et réalisez le fichier
<code>bidule.1</code> contenant&nbsp;:</p>
<blockquote>
<pre><code>
    .SO man1/truc.1
          
</code></pre></blockquote>
Il est important de spécifier le répertoire <i>man1/</i> aussi bien
que le nom du fichier <code>truc.1</code> car lors de l'exécution
de <code>groff</code>, celui-ci aura comme répertoire courant le
répertoire de base des pages de manuel, et il interprètera les
arguments de <code>.SO</code> comme étant relatifs à cet
emplacement.
<h2><a name="s5">5. Quel ensemble de macros
utiliser&nbsp;?</a></h2>
<p>Il y a de nombreux ensembles de macros étudiés spécialement pour
écrire des pages de manuel. Ils sont habituellement dans le
répertoire de macro de <code>groff</code>
<i>/usr/lib/groff/tmac</i>. Les noms de fichiers sont du genre
<i>tmac.&lt;quelque chose&gt;</i>, où <i>&lt;quelque-chose&gt;</i>
est l'argument de l'option -m de <code>groff</code>.
<code>groff</code> utilisera <i>tmac.&lt;quelque-chose&gt;</i>
quand l'option <code>-m &lt;quelque-chose&gt;</code> sera donnée.
Souvent, l'espace entre "-m" et &lt;quelque-chose&gt; est oublié,
on écrira donc <code>groff -man</code> pour formater des pages de
manuel en utilisant l'ensemble de macro tman.an. Voilà la raison de
ce nom bizarre "<i>tman.an</i>".</p>
<p>En plus de <i>tman.an</i>, il existe un autre ensemble de macro
populaire, <i>tman.doc</i>, originaire de l'université de
Californie à Berkeley (UCB). De nombreuses pages de manuels de BSD
l'utilisent et il semble que UCB en a fait son standard pour la
documentation. Les macros de <i>tman.doc</i> sont plus souples
mais, hélas, il y a des lecteurs de pages de manuels qui ne les
utilisent pas mais qui appellent toujours <code>groff -man</code>.
Par exemple, toutes les versions du programme <code>xman</code> que
j'ai rencontrées faisaient la tête devant les pages de manuels
requérant <i>tman.doc</i>. Donc faîtes-vous une faveur : utilisez
<i>tmac.an</i>, utiliser un autre ensemble de macros est considéré
comme hasardeux. <i>tmac.andoc</i> est un pseudo ensemble de macros
qui regarde le source et charge soit <i>tmac.an</i> ou
<i>tmac.doc</i>. En fait, tous les programmes de lecture 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
<i>tmac.an</i>. Tout ce que je dirais à partir de maintenant
concernant les macros est valable seulement pour <i>tmac.an</i>. Si
vous voulez quand même utiliser les macros de <i>tmac.doc</i>,
voici un pointeur vers leur documentation et un mode d'emploi très
détaillé&nbsp;: <a href=
"http://www.bsdi.com/bsdi-man">www.bsdi.com/bsdi-man</a>. Vous
trouverez un formulaire de recherche sur cette page. Entrez
<code>mdoc</code> et il vous trouvera <code>mdoc(7)</code> et
<code>mdoc.samples(7)</code>, un didacticiel sur la réalisation des
pages de manuel BSD.</p>
<h2><a name="s6">6. Quels préprocesseurs puis-je
utiliser&nbsp;?</a></h2>
<p><code>groff</code> est fourni avec au moins 3 préprocesseurs,
<code>tbl</code>, <code>eqn</code> et <code>pic</code> (certains
systèmes les nomment <code>gtbl</code>, <code>geqn</code> et
<code>gpic</code>). Ils sont destinés à traduire leurs macros et
leurs données en code source <code>troff</code> standard.
<code>tbl</code> est un préprocesseur de tableaux, <code>eqn</code>
en est un d'équation et de mathématiques et <code>pic</code> gère
les images. Consultez leurs pages de manuel pour découvrir les
fonctionalités qu'ils proposent.</p>
<p>Mais autant être clair&nbsp;: n'écrivez pas de pages de manuel
qui utilisent des préprocesseurs.</p>
<p><code>eqn</code> produira généralement un résultat
catastrophique sur des périphériques du genre télétype, qui
malheureusement représentent 99% des visualtions de pages de
manuel. Par exemple <i>XAllocColor.3x</i> contient des formules
avec des exposants. A cause de la nature de ces terminaux,
l'exposant sera sur la même ligne que la base. «<i>N puissance
deux</i>» s'affichera "N2".</p>
<p>Il vaut mieux éviter <code>tbl</code> aussi, car je n'ai jamais
vu aucun <code>xman</code> qui fonctionne avec lui. <code>xman
3.1.6</code> utilise la ligne de commande suivante pour formater
les pages de manuel, par exemple <i>signal(7)</i>&nbsp;:</p>
<pre>
gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \
/tmp/xmana01760 2&gt; /dev/null
        
</pre>
qui coince sur toutes les sources utilisant <code>gtbl</code>, car
sa sortie est redirigée encore une fois vers <code>gtbl</code>. Le
résultat donne une page de manuel sans votre tableau. Je ne sais
pas si c'est un bogue ou une particularité de <code>gtbl</code> qui
s'étrangle sur sa propre sortie ou si <code>xman</code> devrait
être un peu plus gentil et ne pas utiliser <code>gtbl</code> deux
fois... De toute façon, si vous voulez un tableau, formatez-le
vous-même et mettez-le entre les lignes <code>.nf</code> et
<code>.fi</code> ce qui permettra de ne pas le formater. Vous ne
pourrez pas avoir de gras ou d'italique par cette méthode mais elle
permettra d'avoir votre tableau dans tous les cas.
<p>Je n'ai jamais vu une page de manuel nécessitant le
préprocesseur <code>pic</code> mais je n'aimerais pas ça. Comme
vous pouvez le voir plus haut, <code>xman</code> ne l'utilise pas
et <code>groff</code> ferait sûrement la danse de Saint-Guy en
voyant les données en entrée.</p>
<h2><a name="s7">7. Dois-je distribuer les sources et/ou la
documentation déjà formatée&nbsp;?</a></h2>
<p>Voyons les avantages (+) et les inconvénients (-) de quelques
possibilités choisies&nbsp;:</p>
<ol>
<li>code source uniquement&nbsp;:
<ul>
<li>(+) distribution plus petite&nbsp;;</li>
<li>(-) inutilisable sur les systèmes ne disposant pas de
<code>groff</code>.</li>
</ul>
</li>
<li>verison formatée non compactée uniquement&nbsp;:
<ul>
<li>(+) utilisable même sur des systèmes dépourvus de
<code>groff</code>&nbsp;;</li>
<li>(-) l'utilisateur ne peut pas générer un fichier dvi ou
PostScript&nbsp;;</li>
<li>(-) gâchis de l'espace disque sur les systèmes sachant gérer
aussi les pages compressées.</li>
</ul>
</li>
<li>version formatée et compactée seulement&nbsp;:
<ul>
<li>(+) utilisables même sur des systèmes dépourvus de
<code>groff</code>&nbsp;;</li>
<li>(-) l'utilisateur ne peut pas générer de fichier dvi ou
PostScript&nbsp;;</li>
<li>(-) quel format de compactage utiliser&nbsp;? .Z&nbsp;? .z ?
.gz&nbsp;? Tous&nbsp;?.</li>
</ul>
</li>
<li>code source et la version formatée non compactée&nbsp;:
<ul>
<li>(+) accessible même sur les systèmes ne disposant pas de
<code>groff</code>&nbsp;;</li>
<li>(-) taille de la distribution plus grande&nbsp;;</li>
<li>(-) certains systèmes peuvent nécessiter des pages de manuels
formattées et compactées&nbsp;;</li>
<li>(-) informations redondantes sur les systèmes équipés de
<code>groff</code>.</li>
</ul>
</li>
</ol>
<p>A mon avis, la meilleure solution est de distribuer uniquement
le code source. L'argument selon lequel la documentation ne pourra
pas être accessible sur les systèmes sans <code>groff</code> n'a
aucune importance. Plus de 500 pages de manuel du Projet de
Documentation de Linux ne sont que sous forme de code source. Les
pages de manuel de XFree86 ne sont disponibles que sous forme de
code source. Les pages de manuel de la FSF n'existent que sous
forme de code source. En fait, j'ai rarement vu des logiciels
distribués avec les pages de manuels formatées. Si un
administrateur a besoin que les pages de manuel soient accessibles,
il aura forcément installé <code>groff</code>.</p>
<h2><a name="s8">8. Quelles sont les conventions pour les
fontes&nbsp;?</a></h2>
<p>Avant tout, n'utilisez pas les opérateurs directs de fonte comme
<code>\fB \fP</code>, etc. Employez des macros avec des arguments.
Cette méthode vous évitera une erreur classique&nbsp;: oublier un
changement de fonte à la fin d'un mot ce qui provoque la
continuation du gras ou de l'italique jusqu'au prochain changement
de fonte. Croyez-moi, ça arrive plus souvent qu'on ne le
pense&nbsp;!</p>
<p>Les macros <i>tmac.an</i> offrent les possibilités
suivantes&nbsp;:</p>
<ul>
<li><code>.B</code> caractères gras</li>
<li><code>.BI</code> gras et italiques en alternance</li>
<li><code>.BR</code> gras et romain en alternance</li>
<li><code>.I</code> italiques</li>
<li><code>.IB</code> italiques et gras en alternance</li>
<li><code>.IR</code> italiques et romain en alternance</li>
<li><code>.RB</code> romain et gras en alternance</li>
<li><code>.RI</code> romain et italiques en alternance</li>
<li><code>.SM</code> taille réduite (9/10 du corps normal)</li>
<li><code>.SB</code> gras, taille réduite (NON petit et gras en
alternance)</li>
</ul>
<p>X et Y en alternance signifie que les arguments impairs seront
imprimés en X et les pairs en Y. Par exemple&nbsp;:</p>
<blockquote>
<pre><code>
.BI "Arg 1 est gras, " "arg2 est en italiques, " "arg3 en gras"
          
</code></pre></blockquote>
<p>Les guillemets sont nécessaires pour placer des espaces dans un
argument.</p>
<p>Voilà donc pour ce qui est possible. Voyons maintenant comment
il faut utiliser ces possibilités (des parties ont été honteusement
copiées de <code>man(7)</code>)&nbsp;:</p>
<p>Bien qu'il existe de nombreuses conventions typographiques pour
les pages de manuel dans le monde UNIX, l'existence de plusieurs
centaines de pages de manuel spécifiques à Linux définit nos
standards&nbsp;:</p>
<p>Pour les fonctions, les arguments sont toujours en italiques,
même dans la section SYNOPSYS, alors que le reste est en gras. Vous
écrirez donc&nbsp;:</p>
<blockquote>
<pre><code>
.BI "mafonction(int " argc ", char **" argv );
          
</code></pre></blockquote>
<p>Les noms de fichiers sont toujours en italiques, hormis dans la
section SYNOPSYS où les fichiers à inclure sont en gras. Vous
écrirez alors&nbsp;:</p>
<blockquote>
<pre><code>
.I /usr/include/stdio.h
          
</code></pre></blockquote>
et
<blockquote>
<pre><code>
.B #include &lt;stdio.h&gt;
          
</code></pre></blockquote>
<p>Les noms des macros, qui sont habituellement en majuscules, sont
en gras&nbsp;:</p>
<blockquote>
<pre><code>
.B MAXINT
          
</code></pre></blockquote>
<p>Lors de l'énumération d'une liste de codes d'erreurs, ces codes
sont en gras. Cette liste fait généralement appel à la macro
<code>.TP</code> (paragraphe avec titre) comme
ci-dessous&nbsp;:</p>
<blockquote>
<pre><code>
.TP
.B EBADF
.I fd n'est pas un descripteur de fichier valide
.TP
.B EINVAL
.I fd ne convient pas pour être lu
          
</code></pre></blockquote>
<p>Toute référence à une autre page de manuel (ou à la page
courante) est en gras. Si le numéro de la section du manuel est
indiqué, il s'écrit en roman, sans espace&nbsp;:</p>
<blockquote>
<pre><code>
.BR man (7)
          
</code></pre></blockquote>
<p>Les acronymes sont plus élégants lorsqu'ils apparaissent dans un
corps plus petit. Je recommande donc&nbsp;:</p>
<blockquote>
<pre><code>
.SM UNIX
.SM ASCII
.SM TAB
.SM NFS
.SM LALR(1)
          
</code></pre></blockquote>
<h2><a name="s9">9. Comment dois-je présenter ma page de
manuel&nbsp;?</a></h2>
<p>Voilà quelques conseils pour rendre votre documentation plus
sûre, plus lisible et plus «formatable»&nbsp;:</p>
<ul>
<li>Les exemples doivent fonctionner&nbsp;: testez-les (utilisez le
copier-coller pour passer à votre shell ce que contient votre page
de manuel) et redirigez la sortie de votre commande dans votre
page, ne tapez pas ce que vous PENSEZ que votre programme
affichera.</li>
<li>relisez-vous, corrigez toutes les éventuelles fautes de frappe
ou d'orthographe, faîtes-vous relire par un tiers (surtout si vous
ne rédigez pas le texte dans votre langue natale)&nbsp;.
(d'ailleurs ce HOWTO n'a pas été relu... Y a-t-il un
volontaire&nbsp;?)</li>
<li>testez votre page de manuel&nbsp;: est-ce que
<code>groff</code> trouve des erreurs lors du formatage&nbsp;?
C'est agréable de trouver dans un commentaire la ligne de commande
qu'il faut taper pour le formatage. Est-ce que la commande
<code>man(1)</code> affiche des erreurs ou des avertissements
lorsqu'on appelle "<code>man votre_programme</code>"&nbsp;? Est-ce
que la façon dont <code>man(1)</code> utilise le système de
formatage produit le résultat escompté&nbsp;? Est-ce que cela
fonctionne aussi bien avec <code>xman(1x)</code> et
<code>tkman(1tk)</code>&nbsp;? <code>XFree86 3.1</code> contient la
version 3.1.6 de <code>xman</code> qui décompacte les pages
avec&nbsp;:
<blockquote>
<pre><code>
gzip -c -d &lt; %s &gt; %s
zcat &lt; %s &gt; %s
              
</code></pre></blockquote>
</li>
<li>Est-ce que <code>makewhatis(8)</code> pourra extraire la ligne
de description de la section NAME&nbsp;?</li>
</ul>
<h2><a name="s10">10. Comment puis-je avoir un texte en pur ASCII
sans tous ces fichus ^H^ de contrôle&nbsp;?</a></h2>
<p>Jetez un oeuil à la commande <code>col(1)</code>,
<code>col</code> peut enlever ces caractères d'effacement. Pour les
impatients, voici la commande&nbsp;:</p>
<blockquote>
<pre><code>
$ groff -t -e -mandoc -Tascii manpage.1 | col -bx &gt; manpage.txt
          
</code></pre></blockquote>
Les options <code>-t</code> et <code>-e</code> disent à
<code>groff</code> d'utiliser les préprocesseurs <code>tbl</code>
et <code>eqn</code>. C'est inutile pour les pages de manuel ne
nécessitant pas de préprocesseur mais cela ne gêne pas, si ce n'est
une surcharge du processeur. D'un autre côté, ne pas utiliser
<code>-t</code> alors qu'il est nécessaire fera que les tableaux
seront très mal formatés. Vous pourrez même trouver ("deviner"
serait un terme plus exact) la commande nécessaire pour traiter tel
ou tel document groff (pas uniquement des pages de manuel) par le
biais de <code>grog</code>&nbsp;:
<blockquote>
<pre><code>
$ grog /usr/man/man7/signal.7 
groff -t -man /usr/man/man7/signal.7 
          
</code></pre></blockquote>
<p>En fait, <code>grog</code> signifie "<i>GROff Guess</i>", et cet
outil fait bien ce qu'il dit (en anglais, guess =
deviner...)&nbsp;: il tente de deviner la commande nécessaire pour
formater un document groff en fonction de son contenu. S'il était
parfait, nous n'aurions jamais plus besoin d'options. Mais s'il
arrive qu'il détermine un mauvais jeu de macros, je ne l'ai par
contre jamais vu se tromper sur les préprocesseurs à employer.</p>
<p>Voici un petit script 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 longueurs de papier lorsque l'on imprime de
longues et complexes pages de manuel. Sauvez-le dans un fichier
nommé <i>strip-header</i> et mettez-le en mode 755.</p>
<blockquote>
<pre><code>
#!/usr/bin/perl -n
#  pour qu'il avale tout le fichier en une seule fois:
undef $/;
#  on enleve les sauts de page:
s/\n{4}\S.{50,}\n{6}\S.{50,}\n{3}/\n/g;
#  le premier en-tete et le dernier pied de page:
s/\n\S.{50,}\n//g;
#  transorme deux ou plus lignes vides consecutives en une seule:
s/\n{3,}/\n\n/g;
#  et voila ce qui reste...
print; 
            
</code></pre></blockquote>
<p>Il faut appeler ce programme en tant que premier filtre après la
comande man, car il se base sur le nombre de sauts de ligne issus
de groff. Par exemple&nbsp;:</p>
<blockquote>
<pre><code>
$ man bash | strip-headers | col -bx &gt; bash.txt
          
</code></pre></blockquote>
<h2><a name="s11">11. Comment avoir une belle page de manuel en
PostScript &nbsp;?</a></h2>
<blockquote>
<pre><code>
$ groff -t -e -mandoc -Tps manpage.1 &gt; manpage.ps
          
</code></pre></blockquote>
Imprimez-la à l'aide de votre imprimante PostScript préférée ou
d'un interpréteur. Voir la section précédente pour les options.
<h2><a name="s12">12. Comment faire fonctionner les programmes
<code>apropos</code> et <code>whatis</code>&nbsp;?</a></h2>
<p>Supposons que vous recherchiez les compilateurs installés sur
votre système et comment les invoquer (nous considérons le cas
courant, où tout le manuel est en langue anglaise). Pour répondre à
cette question (fréquemment posée), il faut faire&nbsp;:</p>
<blockquote>
<pre><code>
$ apropos compiler
f77 (1) - Fortran 77 compiler
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
          
</code></pre></blockquote>
<p><code>apropos</code> et <code>whatis</code> sont utilisées pour
obtenir une réponse rapide sur les pages de manuels qui contiennent
des informations sur un certain sujet. Les deux programmes
cherchent dans des fichiers nommés <i>whatis</i> qui sont dans
chaque répertoire de base du manuel. Comme je l'ai déjà dit, les
fichiers de la base de données <i>whatis</i> contiennent une entrée
d'une ligne pour chaque page de manuel dans l'arborescence des
répertoires successifs. En fait, cette ligne est exactement celle
de la section NAME (pour être précis&nbsp;: tout est réduit à une
seule ligne et le tiret est supprimé, la section étant placée entre
parenthèses). Ces fichiers sont créés à l'aide du programme
<code>makewhatis(8)</code>. Il en existe plusieurs versions, donc
référez-vous à la page de manuel du programme pour connaître les
options possibles. Afin que <code>makefile</code> puisse extraire
les sections NAME correctement, il est important que vous, le
rédacteur du manuel, respectiez le format de cette section décrit
dans la partie 2. La différence entre <code>apropos</code> et
<code>whatis</code> est ce qu'ils recherchent et où.
<code>apropos</code> (qui est l'équivalent de <code>man -k</code>)
cherche la chaîne de caractères qui lui est passée en argument
n'importe où dans la ligne alors que <code>whatis</code>
(équivalent de <code>man -f</code>) recherche dans la partie avant
le tiret un nom de commande complet. Par conséquence,
<code>whatis</code> dira s'il y a un manuel de <code>cc</code> mais
restera muet pour <code>gcc</code>.</p>
<h2><a name="s13">13. La langue française</a></h2>
<p>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&nbsp;: n'espérez pas pouvoir les respecter avec les
outils de formatage du manuel. Consultez la documentation de
<code>groff</code> 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.</p>
<p>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 -Tlatin1 . 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 <code>more</code> ou
<code>less</code> généralement employés.</p>
<p>Vous voilà prévenu&nbsp;!</p>
<h2><a name="s14">14. Les conditions de copie</a></h2>
<p>Copyright 1995, 96, 97 Jens Schweikardt <a href=
"mailto:schweikh@noc.dfn.de">schweikh@noc.dfn.de</a></p>
<p>Téléphone&nbsp;: ++49 7151 909516</p>
<p>Sauf mention contraire, les documents Linux <i>HOWTO</i> portent
le copyright de leurs auteurs respectifs. Ils peuvent être
reproduits et distribués en tout ou partie, sur n'importe quel
support physique ou électronique, à condition que cette notice soit
incluse dans chaque copie. La redistribution est autorisée et
encouragée&nbsp;; toutefois, l'auteur voudrait en être prévenu.</p>
<p>Toutes les traductions, travaux dérivés ou compilation de
travaux incluant des documents Linux <i>HOWTO</i> doivent être
couverts par ce copyright. C'est-à-dire que vous ne pouvez pas
produire un travail dérivé d'un HOWTO et imposer des restrictions
supplémentaires sur sa distribution. Des dérogations à ces règles
peuvent être accordées sous certaines conditions&nbsp;: contactez
le coordinateur des Linux <i>HOWTO</i> dont l'adresse est donnée
plus loin.</p>
<p>En résumé, nous désirons promouvoir la diffusion de ces
informations à travers tous les canaux de communication possibles.
Cependant, nous voulons conserver la propriété des <i>HOWTO</i> et
aimerions être tenu au courant de tout projet de
redistribution.</p>
<p>Si vous avez des questions, contactez Greg Hankins, le
coordinateur, par courrier électronique à l'adresse <a href=
"mailto:gregh@sunsite.unc.edu">gregh@sunsite.unc.edu</a>.</p>
</body>
</html>
doc-linux-fr-html 2013.01-3ubuntu1 / usr / share / doc / HOWTO / fr-html / Man-Page.html
