  Man page HOWTO
  Auteur : Jens Schweikhardt schweikh@noc.dfn.de

  www.shuttle.de/schweikh/home.html

  Mars 1998

  (Adaptation franaise par Alexandre Devaure adevaure@mail.dotcom.fr, 2
  juin 1999).  Ce HOWTO explique ce que vous devrez avoir en tte quand
  vous prvoyez d'crire une documentation en ligne (plus connue sous le
  nom de page de manuel) que vous voulez rendre accessible via la com
  mande man(1). Tout au long de ce HOWTO, une entre du manuel sera sim
  plement appele page de manuel, quelque soit sa longueur relle et
  sans intention sexiste.

  ______________________________________________________________________

  Table des matires


  1. Quelques vidences  propos de la documentation

  2. Comment accde-t-on aux pages de manuel ?

  3. A quoi ressemble une page de manuel formate ?

  4. Comment documenter plusieurs choses dans une seule page de manuel ?

  5. Quel ensemble de macros utiliser ?

  6. Quels prprocesseurs puis-je utiliser ?

  7. Dois-je distribuer les sources et/ou la documentation dj formate ?

  8. Quelles sont les conventions pour les fontes ?

  9. Comment dois-je prsenter ma page de manuel ?

  10. Comment puis-je avoir un texte en pur ASCII sans tous ces fichus ^H^ de contrle ?

  11. Comment avoir une belle page de manuel en PostScript  ?

  12. Comment faire fonctionner les programmes

  13. La langue franaise

  14. Les conditions de copie



  ______________________________________________________________________

  11..

  QQuueellqquueess vviiddeenncceess  pprrooppooss ddee llaa ddooccuummeennttaattiioonn

  Pourquoi crivons-nous une documentation ? C'est une question bte.
  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 :

    la documentation doit tre accessible. Si elle est cache  un
     endroit non standard o les outils de recherche relatifs  la
     documentation ne la trouveront pas, comment peut-elle remplir son
     rle ?
    la documentation doit tre fiable et prcise. Il n'y a rien de plus
     irritant qu'un programme se comportant diffremment 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.

     La mthode traditionnelle pour accder  la documentation sous UNIX
     fait appel  la commande man(1). Ce HOWTO dcrit ce que vous devez
     faire pour crire une page de manuel qui sera correctement traite
     par les outils prvus  cet effet, dont les plus importants sont
     man(1), xman(1x), apropos(1), makewhatis(8) et catman(8).

  La qualit et la vracit des informations sont, bien sr, de votre
  ressort. Malgr tout, vous trouverez dans ce guide quelques ides qui
  vous permettront d'viter certains piges courants.

  22..

  CCoommmmeenntt aaccccddee--tt--oonn aauuxx ppaaggeess ddee mmaannuueell ??

  Vous devez connatre avec prcision le mcanisme d'accs 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 spcifique, dnote par un simple chiffre.
  Les sections les plus courantes rencontres sous Linux sont :

    1 : commandes utilisateurs pouvant tre excutes par tout le
     monde ;

    2 : appels systmes, c'est--dire les fonctions fournies par le
     noyau ;

    3 : fonctions des bibliothques ;

    4 : priphriques, c'est--dire les fichiers spciaux que l'on
     trouve dans le rpertoire /dev ;

    5 : descriptions des formats de fichiers (comme par exemple
     /etc/passwd ;

    6 : les jeux, sans commentaire...

    7 : divers (macros, conventions particulires, ...) ;

    8 : outils d'administration excutables uniquement par le super
     utilisateur ;

    9 : un autre endroit (spcifique  Linux) destin  la
     documentation des services offerts par le noyau ;

    n : nouvelle documentation, qui pourra tre dplace vers un
     endroit appropri ;

    o : ancienne documentation, qui peut tre conserve encore un
     certain temps ;

    l : documentation locale, propre  ce systme particulier.

     Le nom du fichier source d'une page de manuel (le fichier d'entre
     du systme de formatage) est le nom de la commande dcrite (ou de
     la fonction, du fichier, etc.), suivi d'un point et du numro de
     section.  Si, par exemple, vous documentez le format du fichier
     "_p_a_s_s_w_d", vous devez appeler le fichier source "_p_a_s_s_w_d_._5". Nous
     avons ici un exemple d'un fichier qui porte le  mme nom qu'une
     commande ; nous aurions tout aussi bien avoir une fonction de
     bibliothque appele "_p_a_s_s_w_d". L'organisation en sections constitue
     la mthode habituelle pour rsoudre ces ambiguts : la description
     de la commande se trouvera dans le fichier "_p_a_s_s_w_d_._1" et notre
     hypothtique fonction de bibliothque dans "_p_a_s_s_w_d_._3".

  Quelquefois, une lettre est ajoute au numro de section comme par
  exemple "_x_t_e_r_m_._1_x" ou "_w_i_s_h_._1_t_k". 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 ; xman,
  par exemple affichera "_x_t_e_r_m_(_x_)" et "_w_i_s_h_(_t_k_)" dans la liste des
  documents disponibles.

  S'il vous plat, n'utilisez pas les sections n, o et l : selon le
  standard du systme de fichiers (File System Standard), ces sections
  sont dconseilles, utilisez plutt les sections numriques.

  Attention aux ventuels conflits de noms avec des programmes,
  fonctions ou fichiers dj existants. Ce serait certainement une
  mauvaise ide 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
  excute votre programme et qu'il lise la page de manuel d'un autre ou
  _v_i_c_e _v_e_r_c_a. Vous pouvez ventuellement vous aider de la base de
  donnes "lsm" qui recense beaucoup de programmes disponibles pour
  Linux.

  Maintenant que nous savons quel nom donner  notre fichier, la
  prochaine dcision est de choisir le rpertoire dans lequel nous
  l'installerons (quand l'utilisateur lancera la commande "make
  install"). Sous Linux, toutes les pages de manuel sont dans des sous-
  rpertoires  partir d'une racine mmorise dans la variable
  d'environnement MANPATH. Les outils de traitement de la documentation
  l'utilisent de la mme manire que le shell utilise la variable PATH
  pour trouver les excutables. En fait, MANPATH a le mme format que
  PATH : toutes les deux sont une liste de rpertoires spars 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 exporte, /usr/man est utilise comme valeur par
  dfaut. Dans le but d'acclerer la recherche et pour garder les
  rpertoires de taille raisonable, les rpertoires points dans MANPATH
  (aussi appels rpertoires de base) contiennent une multitude de sous-
  rpertoires nomms "_m_a_n_<_s_>" o <s> dsigne le caractre correspondant
   la section prsent plus haut. Toutes les sections ne sont pas
  reprsentes, il n'y a pas, par exemple de raison de garder une entre
  "_m_a_n_o". Vous pourrez y trouver galement des sous-rpertoires appels
  "_c_a_t_<_s_>", "_d_v_i_<_s_>" et "_p_s_<_s_>", qui contiennent toute la documentation
  formate, prte  tre affiche ou imprime : nous reviendrons sur ce
  sujet plus loin. Le seul fichier  tre prsent  ct de ces sous-
  rpertoires du rpertoire de base s'appelle "_w_h_a_t_i_s". Le but et la
  cration de ce fichier sera dcrit dans la section 11. La mthode la
  plus sre pour installer au bon endroit une page de manuel de la
  section "s" est de mettre le fichier dans le rpertoire
  "_/_u_s_r_/_m_a_n_/_m_a_n_<_s_>". Toutefois, un bon Makefile devra autoriser
  l'utilisateur de choisir un autre rpertoire 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
  configures  l'aide de l'option --prefix=/nom/option. Les pages de
  manuels correspondantes seront alors installes  partir du rpertoire
  de base _/_m_o_n_/_o_p_t_i_o_n_/_m_a_n. Je vous suggre d'utiliser une mthode
  similaire pour vos ralisations personnelles.

  Depuis l'avnement du "_S_y_s_t__m_e _d_e _f_i_c_h_i_e_r_s _s_t_a_n_d_a_r_d" pour Linux (FS-
  STnd), les choses se sont compliques. Le FS-STnd 1.2 stipule que :

       des amnagements doivent tre faits dans la structure de
       _/_u_s_r_/_m_a_n pour supporter des pages de manuel crites dans
  diffrentes (ou mutiples) langues.


  Ceci est fait en introduisant un niveau de rpertoires supplmentaire
  qui distingue les diffrentes langues. Citant encore le FS-Stnd 1.2 :

       Le nommage des sous-rpertoires correspondants aux langues
       de _/_u_s_r_/_m_a_n est bas sur l'appendice E du standard POSIX
       1003.1 qui dcrit la chane de caractres d'authentification
       _l_o_c_a_l_e (qui est la mthode la mieux accepte pour dcrire un
       environement culturel). La chane _l_o_c_a_l_e se prsente sous la
       forme

                   <langage>[_<pays>][.<jeu-de-caracteres>][,<version>]





  (Reportez vous au FS-Stnd pour voir quelques chanes _l_o_c_a_l_ecourantes.)
  D'aprs ces recommandations, nous avons nos pages de manuel dans
  _/_u_s_r_/_m_a_n_/_<_l_o_c_a_l_e_>_/_m_a_n_[_1_-_9_l_n_o_]. Les versions formates se trouveraient
  alors bien entendu dans _/_u_s_r_/_m_a_n_/_<_l_o_c_a_l_e_>_/_c_a_t_[_1_-_9_l_n_o_] : nous pourrions
  ne les fournir que pour une seule langue.

  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

       les systmes qui n'utilisent qu'une seule langue et jeu de
       caractres pour toutes les pages de manuel peuvent omettre
       la sous-chane _<_l_o_c_a_l_e_> et stocker toutes ces pages dans le
       rpertoire _m_a_n_d_i_r. Par exemple, les machines quipes seule
       ment de pages de manuel en anglais codes en ASCII peuvent
       mettre les pages de manuel (les rpertoires _m_a_n_[_1_-_9_])
       directement dans _/_u_s_r_/_m_a_n_/. Il s'agit en fait de l'arrange
       ment habituel.


  Je (l'auteur du document, pas le traducteur) ne changerai pas ma
  configuration tant que tous les outils (comme xman, info, tkman et
  beaucoup d'autres) ne seront pas tous adapts  cette nouvelle
  structure.

  33..

  AA qquuooii rreesssseemmbbllee uunnee ppaaggee ddee mmaannuueell ffoorrmmaattee ??

  Laissez-moi vous prsenter un exemple que j'expliquerai plus tard. En
  raison de la nature et du mode de ralisation de ce document, nous ne
  pouvons pas reproduire les caractres accentus, ni les diffrents
  enrichissements du texte (gras et italiques principalement) ;
  consultez la section traitant des polices de caractres pour obtenir
  des dtails sur ces possibilits.

  Voici comment se prsente la page de manuel de notre programme
  hyphothtique "prout" :









        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    <dugenou@renux.freenix.fr>

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

        Linux                      JANVIER 1996                         1




  Et voici les explications promises :

     LLaa sseeccttiioonn NNAAMMEE ::
        C'est la seule section requise.  Les pages de manuel sans une
        section "NAME" sont aussi utiles que des rfrigerateurs au Ple
        Nord. Cette section a aussi un format standardis constitu
        d'une liste de programmes ou noms de fonctions spars 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
        makewhatis(8) les sections NAME sont incluses dans les fichiers
        de la base de donnes de whatis. makewhatis est la raison pour
        laquelle la section NAME doit exister et pourquoi elle doit
        adhrer au format que j'ai dcrit. Dans le source groff, elle
        doit ressembler  :

          .SH NAME prout \- proutibule de la bibliotheque plaf


     Le \- est important ici : le backslash sert a faire la diffrence
     entre le tiret et une marque de csure qui peut apparatre 
     l'intrieur du nom de la commande ou dans la ligne de description.

     AAtttteennttiioonn : en l'tat actuel des choses, vous ne pouvez pas
     traduire NAME par NOM en franais,  moins de modifier la plupart
     des programmes makewhatis existants. C'est bien dommage.


     LLaa sseeccttiioonn SSYYNNOOPPSSYYSS
        ... est cense donner un aperu 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.


     LLaa sseeccttiioonn DDEESSCCRRIIPPTTIIOONN
        Elle explique en dtail pourquoi votre squence de 0 et de 1 est
        la meilleure de toutes. C'est ici que vous talez tout votre
        savoir ! Gagnez l'estime des autres programmeurs et des
        utilisateurs en faisant de cette section une source
        d'information sre et dtaille.  Expliquez  quoi servent les
        arguments, le format de fichier, les algorithmes qui effectuent
        le plus dur du travail.


     LLaa sseeccttiioonn OOPPTTIIOONNSS
        Elle donne une description pour chaque option, comment elle
        affecte le fonctionnement du programme. Vous le saviez, n'est-ce
        pas ?


     LLaa sseeccttiioonn FFIICCHHIIEERRSS
        Elle indique les fichiers utiliss par le programme ou la
        fonction. Par exemple, les fichiers de configuration, les
        fichiers de dmarrage, les fichiers sur lesquels le programme
        agit. Ce serait une bonne ide de donner les chemins absolus de
        ces fichiers et d'avoir un processus d'installation qui modifie
        la partie rpertoire selon les prfrences de l'utilisateur :
        les manuels de groff ont comme prfixe par dfaut _/_u_s_r_/_l_o_c_a_l,
        donc ils rfrencent _/_u_s_r_l_/_l_o_c_a_l_/_l_i_b_/_g_r_o_f_f_/_* par dfaut.
        Cependant, si vous installez en utilisant "make
        prefix=/opt/gnu", les rfrences dans la page de manuel change
        en _/_o_p_t_/_g_n_u_/_l_i_b_/_g_r_o_f_f_/_*.


     LLaa sseeccttiioonn EENNVVIIRROONNNNEEMMEENNTT
        fait la liste de toutes les variables d'environnement qui
        affectent votre programme ou fonction et, bien sr, explique
        comment. La plupart du temps, les variables contiendront les
        chemins, nom de fichiers, options par dfaut.


     LLaa sseeccttiioonn DDIIAAGGNNOOSSTTIIQQUUEESS
        Elle doit donner une vue d'ensemble des messages d'erreurs les
        plus courants de votre programme et des ventuelles solutions 
        ces problmes. Il n'est pas ncessaire d'expliquer les messages
        d'erreurs du systme (de perror(3)) ou des signaux fatals (de
        psignal(3)) qui peuvent apparatre pendant l'excution de tout
        programme.


     LLaa sseeccttiioonn BBOOGGUUEESS
        Devrait idalement ne pas exister. Si vous tes brave, vous
        pouvez dcrire ici les limitations, les inconvnients, les
        caractristiques que certains pourraient prendre pour des
        dfauts. Si vous n'tes pas brave, renommez-la en section "A
        FAIRE".


     LLaa sseeccttiioonn AAUUTTEEUURR
        Il est apprciable de l'avoir quand il y a des erreurs
        grossires dans la documentation ou dans le comportement du
        programme et que vous voulez envoyer un rapport de bogue.


     LLaa sseeccttiioonn VVOOIIRR AAUUSSSSII
        C'est une liste de pages de manuel relatives  l'application
        cites par ordre alphabtique. Par convention, c'est la dernire
        section.

  Vous tes libres d'en inventer d'autres si elles n'empietent pas sur
  celles dcrites au-dessus. Nous avons volontairement dcrit une ver
  sion francise de page de manuel, puisque ce document est destin aux
  pays francophones. Nanmoins, 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
  ralit, dans l'ordre : NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES,
  ENVIRONMENT, DIAGNOSTICS, BUGS, AUTHOR et SEE ALSO.

  Donc comment gnrer cette page de manuel ? J'attendais cette
  question, voici le source :









   .\" 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    <dugenou@renux.freenix.fr>
   .SH "VOIR AUSSI"
   .BR gloup (1),
   .BR plaf (1),
   .BR prout (5).




  44..

  CCoommmmeenntt ddooccuummeenntteerr pplluussiieeuurrss cchhoosseess ddaannss uunnee sseeuullee ppaaggee ddee mmaannuueell ??

  De nombreux programmes (grep, egrep) et fonctions (printf,
  fprintf,...) sont documentes 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 egrep est en
  fait celle de grep. Il est par consquent indispensable que la page
  soit accessible sous diffrents noms. Vous avez plusieurs possibilits
  pour y arriver :

  1. avoir des copies identiques pour chaque nom ;

  2. connecter toutes les pages de manuels en utilisant des liens
     physiques ;

  3. utiliser les liens symboliques pointant la page de manuel ;

  4. utiliser le mcanisme de "source" de groff fournie par la macro
     ".SO".

     La premire possibilit est une perte de place. La deuxime n'est
     pas recommande parce que les versions intelligentes du programme
     catman peuvent gagner beaucoup de temps en regardant le type du
     fichier et son contenu. Les liens physiques rduiraient
     l'efficacit de cet outil (dont le but est de formater toutes les
     pages de manuel pour qu'elles soient affiches plus rapidement). La
     troisime alternative comporte un pige si vous tes concern par
     la portabilit, vous devez savoir qu'il existe des systmes de
     fichiers qui ne supportent pas les liens symboliques. En bref, la
     Meilleure Chose (TM) est d'utiliser le mcanisme source de groff.

  Voila comment l'utiliser : si vous voulez que votre page soit
  accessible sous les noms truc et bidule dans la section 1, alors
  mettez la page de manuel dans truc.1 et ralisez le fichier bidule.1
  contenant :


           .SO man1/truc.1





  Il est important de spcifier le rpertoire _m_a_n_1_/ aussi bien que le
  nom du fichier truc.1 car lors de l'excution de groff, celui-ci aura
  comme rpertoire courant le rpertoire de base des pages de manuel, et
  il interprtera les arguments de .SO comme tant relatifs  cet
  emplacement.

  55..

  QQuueell eennsseemmbbllee ddee mmaaccrrooss uuttiilliisseerr ??

  Il y a de nombreux ensembles de macros tudis spcialement pour
  crire des pages de manuel. Ils sont habituellement dans le rpertoire
  de macro de groff _/_u_s_r_/_l_i_b_/_g_r_o_f_f_/_t_m_a_c. Les noms de fichiers sont du
  genre _t_m_a_c_._<_q_u_e_l_q_u_e _c_h_o_s_e_>, o _<_q_u_e_l_q_u_e_-_c_h_o_s_e_> est l'argument de
  l'option -m de groff. groff utilisera _t_m_a_c_._<_q_u_e_l_q_u_e_-_c_h_o_s_e_> quand
  l'option -m <quelque-chose> sera donne. Souvent, l'espace entre "-m"
  et  <quelque-chose> est oubli, on crira donc groff -man pour
  formater des pages de manuel en utilisant l'ensemble de macro tman.an.
  Voil la raison de ce nom bizarre "_t_m_a_n_._a_n".

  En plus de _t_m_a_n_._a_n, il existe un autre ensemble de macro populaire,
  _t_m_a_n_._d_o_c, 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 _t_m_a_n_._d_o_c
  sont plus souples mais, hlas, il y a des lecteurs de pages de manuels
  qui ne les utilisent pas mais qui appellent toujours groff -man. Par
  exemple, toutes les versions du programme xman que j'ai rencontres
  faisaient la tte devant les pages de manuels requrant _t_m_a_n_._d_o_c. Donc
  fates-vous une faveur : utilisez _t_m_a_c_._a_n, utiliser un autre ensemble
  de macros est considr comme hasardeux. _t_m_a_c_._a_n_d_o_c est un pseudo
  ensemble de macros qui regarde le source et charge soit _t_m_a_c_._a_n ou
  _t_m_a_c_._d_o_c. En fait, tous les programmes de lecture du manuel devraient
  l'utiliser mais jusqu' prsent, peu le font, aussi il vaut mieux
  assurer le coup en se cantonnant au bon vieux _t_m_a_c_._a_n. Tout ce que je
  dirais  partir de maintenant concernant les macros est valable
  seulement pour _t_m_a_c_._a_n. Si vous voulez quand mme utiliser les macros
  de _t_m_a_c_._d_o_c, voici un pointeur vers leur documentation et un mode
  d'emploi trs dtaill : www.bsdi.com/bsdi-man.  Vous trouverez un
  formulaire de recherche sur cette page. Entrez mdoc et il vous
  trouvera mdoc(7) et mdoc.samples(7), un didacticiel sur la ralisation
  des pages de manuel BSD.

  66..

  QQuueellss pprrpprroocceesssseeuurrss ppuuiiss--jjee uuttiilliisseerr ??

  groff est fourni avec au moins 3 prprocesseurs, tbl, eqn et pic
  (certains systmes les nomment gtbl, geqn et gpic). Ils sont destins
   traduire leurs macros et leurs donnes en code source troff
  standard.  tbl est un prprocesseur de tableaux, eqn en est un
  d'quation et de mathmatiques et pic gre les images. Consultez leurs
  pages de manuel pour dcouvrir les fonctionalits qu'ils proposent.

  Mais autant tre clair : n'crivez pas de pages de manuel qui
  utilisent des prprocesseurs.

  eqn produira gnralement un rsultat catastrophique sur des
  priphriques du genre tltype, qui malheureusement reprsentent 99%
  des visualtions de pages de manuel. Par exemple _X_A_l_l_o_c_C_o_l_o_r_._3_x
  contient des formules avec des exposants. A cause de la nature de ces
  terminaux, l'exposant sera sur la mme ligne que la base. _N _p_u_i_s_s_a_n_c_e
  _d_e_u_x s'affichera "N2".

  Il vaut mieux viter tbl aussi, car je n'ai jamais vu aucun xman qui
  fonctionne avec lui.  xman 3.1.6 utilise la ligne de commande suivante
  pour formater les pages de manuel, par exemple _s_i_g_n_a_l_(_7_) :



  gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \
  /tmp/xmana01760 2> /dev/null



  qui coince sur toutes les sources utilisant gtbl, car sa sortie est
  redirige encore une fois vers gtbl. Le rsultat donne une page de
  manuel sans votre tableau. Je ne sais pas si c'est un bogue ou une
  particularit de gtbl qui s'trangle sur sa propre sortie ou si xman
  devrait tre un peu plus gentil et ne pas utiliser gtbl deux fois...
  De toute faon, si vous voulez un tableau, formatez-le vous-mme et
  mettez-le entre les lignes .nf et .fi ce qui permettra de ne pas le
  formater. Vous ne pourrez pas avoir de gras ou d'italique par cette
  mthode mais elle permettra d'avoir votre tableau dans tous les cas.

  Je n'ai jamais vu une page de manuel ncessitant le prprocesseur pic
  mais je n'aimerais pas a. Comme vous pouvez le voir plus haut, xman
  ne l'utilise pas et groff ferait srement la danse de Saint-Guy en
  voyant les donnes en entre.

  77..

  DDooiiss--jjee ddiissttrriibbuueerr lleess ssoouurrcceess eett//oouu llaa ddooccuummeennttaattiioonn ddjj ffoorrmmaattee ??

  Voyons les avantages (+) et les inconvnients (-) de quelques
  possibilits choisies :

  1. code source uniquement :

    (+) distribution plus petite ;

    (-) inutilisable sur les systmes ne disposant pas de groff.

  2. verison formate non compacte uniquement :

    (+) utilisable mme sur des systmes dpourvus de groff ;

    (-) l'utilisateur ne peut pas gnrer un fichier dvi ou
     PostScript ;

    (-) gchis de l'espace disque sur les systmes sachant grer aussi
     les pages compresses.

  3. version formate et compacte seulement :

    (+) utilisables mme sur des systmes dpourvus de groff ;

    (-) l'utilisateur ne peut pas gnrer de fichier dvi ou
     PostScript ;

    (-) quel format de compactage utiliser ? .Z ? .z ?  .gz ? Tous ?.

  4. code source et la version formate non compacte :

    (+) accessible mme sur les systmes ne disposant pas de groff ;

    (-) taille de la distribution plus grande ;

    (-) certains systmes peuvent ncessiter des pages de manuels
     formattes et compactes ;

    (-) informations redondantes sur les systmes quips de groff.

  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 systmes sans groff 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 distribus avec les pages de manuels formates. Si un
  administrateur a besoin que les pages de manuel soient accessibles, il
  aura forcment install groff.

  88..

  QQuueelllleess ssoonntt lleess ccoonnvveennttiioonnss ppoouurr lleess ffoonntteess ??

  Avant tout, n'utilisez pas les oprateurs directs de fonte comme \fB
  \fP, etc. Employez des macros avec des arguments.  Cette mthode vous
  vitera une erreur classique : 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 !

  Les macros _t_m_a_c_._a_n offrent les possibilits suivantes :

    .B caractres 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 rduite (9/10 du corps normal)

    .SB gras, taille rduite (NON petit et gras en alternance)

  X et Y en alternance signifie que les arguments impairs seront
  imprims en X et les pairs en Y. Par exemple :


       .BI "Arg 1 est gras, " "arg2 est en italiques, " "arg3 en gras"





  Les guillemets sont ncessaires pour placer des espaces dans un
  argument.

  Voil donc pour ce qui est possible. Voyons maintenant comment il faut
  utiliser ces possibilits (des parties ont t honteusement copies de
  man(7)) :

  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 spcifiques  Linux dfinit nos standards :

  Pour les fonctions, les arguments sont toujours en italiques, mme
  dans la section SYNOPSYS, alors que le reste est en gras.  Vous
  crirez donc :

  .BI "mafonction(int " argc ", char **" argv );





  Les noms de fichiers sont toujours en italiques, hormis dans la
  section SYNOPSYS o les fichiers  inclure sont en gras.  Vous crirez
  alors :


       .I /usr/include/stdio.h





  et


       .B #include <stdio.h>





  Les noms des macros, qui sont habituellement en majuscules, sont en
  gras :


       .B MAXINT





  Lors de l'numration d'une liste de codes d'erreurs, ces codes sont
  en gras. Cette liste fait gnralement appel  la macro .TP
  (paragraphe avec titre) comme ci-dessous :


       .TP
       .B EBADF
       .I fd n'est pas un descripteur de fichier valide
       .TP
       .B EINVAL
       .I fd ne convient pas pour tre lu





  Toute rfrence  une autre page de manuel (ou  la page courante) est
  en gras. Si le numro de la section du manuel est indiqu, il s'crit
  en roman, sans espace :


       .BR man (7)





  Les acronymes sont plus lgants lorsqu'ils apparaissent dans un corps
  plus petit. Je recommande donc :

  .SM UNIX
  .SM ASCII
  .SM TAB
  .SM NFS
  .SM LALR(1)





  99..

  CCoommmmeenntt ddooiiss--jjee pprrsseenntteerr mmaa ppaaggee ddee mmaannuueell ??

  Voil quelques conseils pour rendre votre documentation plus sre,
  plus lisible et plus formatable :

    Les exemples doivent fonctionner : 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.

    relisez-vous, corrigez toutes les ventuelles fautes de frappe ou
     d'orthographe, fates-vous relire par un tiers (surtout si vous ne
     rdigez pas le texte dans votre langue natale) . (d'ailleurs ce
     HOWTO n'a pas t relu...  Y a-t-il un volontaire ?)

    testez votre page de manuel : est-ce que groff trouve des erreurs
     lors du formatage ?  C'est agrable de trouver dans un commentaire
     la ligne de commande qu'il faut taper pour le formatage. Est-ce que
     la commande man(1) affiche des erreurs ou des avertissements
     lorsqu'on appelle "man votre_programme" ? Est-ce que la faon dont
     man(1) utilise le systme de formatage produit le rsultat
     escompt ? Est-ce que cela fonctionne aussi bien avec xman(1x) et
     tkman(1tk) ?  XFree86 3.1 contient la version 3.1.6 de xman qui
     dcompacte les pages avec :


       gzip -c -d < %s > %s
       zcat < %s > %s





    Est-ce que makewhatis(8) pourra extraire la ligne de description de
     la section NAME ?

  1100..

  CCoommmmeenntt ppuuiiss--jjee aavvooiirr uunn tteexxttee eenn ppuurr AASSCCIIII ssaannss ttoouuss cceess ffiicchhuuss ^^HH^^
  ddee ccoonnttrrllee ??

  Jetez un oeuil  la commande col(1), col peut enlever ces caractres
  d'effacement. Pour les impatients, voici la commande :


       $ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt





  Les options -t et -e disent  groff d'utiliser les prprocesseurs tbl
  et eqn.  C'est inutile pour les pages de manuel ne ncessitant pas de
  prprocesseur mais cela ne gne pas, si ce n'est une surcharge du
  processeur. D'un autre ct, ne pas utiliser -t alors qu'il est nces
  saire fera que les tableaux seront trs mal formats. Vous pourrez
  mme trouver ("deviner" serait un terme plus exact) la commande nces
  saire pour traiter tel ou tel document groff (pas uniquement des pages
  de manuel) par le biais de grog :


       $ grog /usr/man/man7/signal.7
       groff -t -man /usr/man/man7/signal.7





  En fait, grog signifie "_G_R_O_f_f _G_u_e_s_s", et cet outil fait bien ce qu'il
  dit (en anglais, guess = deviner...) : il tente de deviner la commande
  ncessaire 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 dtermine un mauvais jeu de macros, je ne l'ai par
  contre jamais vu se tromper sur les prprocesseurs  employer.

  Voici un petit script Perl ralis par l'auteur de ce document, qui
  peut supprimer les en-ttes 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 _s_t_r_i_p_-
  _h_e_a_d_e_r et mettez-le en mode 755.


       #!/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;





  Il faut appeler ce programme en tant que premier filtre aprs la
  comande man, car il se base sur le nombre de sauts de ligne issus de
  groff. Par exemple :


       $ man bash | strip-headers | col -bx > bash.txt





  1111..

  CCoommmmeenntt aavvooiirr uunnee bbeellllee ppaaggee ddee mmaannuueell eenn PPoossttSSccrriipptt  ??



       $ groff -t -e -mandoc -Tps manpage.1 > manpage.ps




  Imprimez-la  l'aide de votre imprimante PostScript prfre ou d'un
  interprteur. Voir la section prcdente pour les options.

  1122..

  CCoommmmeenntt ffaaiirree ffoonnccttiioonnnneerr lleess pprrooggrraammmmeess aapprrooppooss  eett wwhhaattiiss  ??

  Supposons que vous recherchiez les compilateurs installs sur votre
  systme et comment les invoquer (nous considrons le cas courant, o
  tout le manuel est en langue anglaise). Pour rpondre  cette question
  (frquemment pose), il faut faire :


       $ apropos compiler
       f77 (1) - Fortran 77 compiler
       gcc (1) - GNU C and C++ compiler
       pc (1) - Pascal compiler





  apropos et whatis sont utilises pour obtenir une rponse rapide sur
  les pages de manuels qui contiennent des informations sur un certain
  sujet. Les deux programmes cherchent dans des fichiers nomms _w_h_a_t_i_s
  qui sont dans chaque rpertoire de base du manuel. Comme je l'ai dj
  dit, les fichiers de la base de donnes _w_h_a_t_i_s contiennent une entre
  d'une ligne pour chaque page de manuel dans l'arborescence des
  rpertoires successifs. En fait, cette ligne est exactement celle de
  la section NAME (pour tre prcis : tout est rduit  une seule ligne
  et le tiret est supprim, la section tant place entre parenthses).
  Ces fichiers sont crs  l'aide du programme makewhatis(8). Il en
  existe plusieurs versions, donc rfrez-vous  la page de manuel du
  programme pour connatre les options possibles. Afin que makefile
  puisse extraire les sections NAME correctement, il est important que
  vous, le rdacteur du manuel, respectiez le format de cette section
  dcrit dans la partie 2. La diffrence entre apropos et whatis est ce
  qu'ils recherchent et o.  apropos (qui est l'quivalent de man -k)
  cherche la chane de caractres qui lui est passe en argument
  n'importe o dans la ligne alors que whatis (quivalent de man -f)
  recherche dans la partie avant le tiret un nom de commande complet.
  Par consquence, whatis dira s'il y a un manuel de cc mais restera
  muet pour gcc.

  1133..

  LLaa llaanngguuee ffrraannaaiissee

  C'est bien sr  vous de dcider si vous allez rdiger votre manuel en
  franais, en anglais ou dans ces deux langues. Le franais possde des
  rgles typographiques trs diffrentes de l'anglais : n'esprez pas
  pouvoir les respecter avec les outils de formatage du manuel.
  Consultez la documentation de groff si vous dsirez lui faire prendre
  en compte les motifs de csure de la langue de Molire, mais en ayant
  conscience que ce ne sera sans doute pas possible sur tous les
  systmes sur lesquels votre documentation est susceptible d'tre
  exploite.

  Vous pouvez utiliser les caractres accentus, pourvu qu'ils soient
  saisis selon la norme ISO-8859-1 (standard sous Linux). Les pages
  devront alors tre formates avec l'option -Tlatin1 .  Mais il faudra
  que toute la chane de visualisation soit capable de grer les
  caractres ISO sur 8 bits, ce qui est rarement le cas sans une
  configuration particulire des utilitaires more ou less gnralement
  employs.

  Vous voil prvenu !

  1144..

  LLeess ccoonnddiittiioonnss ddee ccooppiiee

  Copyright 1995, 96, 97 Jens Schweikardt schweikh@noc.dfn.de

  Tlphone : ++49 7151 909516

  Sauf mention contraire, les documents Linux _H_O_W_T_O portent le copyright
  de leurs auteurs respectifs. Ils peuvent tre reproduits et distribus
  en tout ou  partie, sur n'importe quel support physique ou
  lectronique,  condition que cette notice soit incluse dans chaque
  copie. La redistribution est autorise et encourage ; toutefois,
  l'auteur voudrait en tre prvenu.

  Toutes les traductions, travaux drivs ou compilation de travaux
  incluant des documents Linux _H_O_W_T_O doivent tre couverts par ce
  copyright. C'est--dire que vous ne pouvez pas produire un travail
  driv d'un HOWTO et imposer des restrictions supplmentaires sur sa
  distribution. Des drogations  ces rgles peuvent tre accordes sous
  certaines conditions : contactez le coordinateur des Linux _H_O_W_T_O dont
  l'adresse est donne plus loin.

  En rsum, nous dsirons promouvoir la diffusion de ces informations 
  travers tous les canaux de communication possibles. Cependant, nous
  voulons conserver la proprit des _H_O_W_T_O 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 gregh@sunsite.unc.edu.


































