  Realisation de pages de manuel
  Jens  Schweikhardt <jens@kssun3.rus.uni-stuttgart.de>, trad.
  Rene.Cougnenc@freenix.fr - Janvier 1996

  Ce document explique ce que l'on doit connaitre pour  pouvoir  rediger
  de la documentation en ligne destinee a etre exploitee par la commande
  man(1) : ce sont les fameuses _p_a_g_e_s _d_e _m_a_n_u_e_l.

  11..  QQuueellqquueess eevviiddeenncceess

  Pourquoi   redigeons-nous    des   documentations   ?    A    question
  stupide, reponse stupide : pour que tout le monde sache utiliser notre
  programme, notre fonction bibliotheque ou tout autre code de notre cru
  que nous diffusons dans ce but. Mais la redaction n'est pas tout :

  +o  la  documentation  doit  etre  accessible. Si elle est placee en un
     endroit non standard tel que les outils destines a son exploitation
     ne la trouvent pas, comment peut-elle remplir son role ?

  +o  la documentation doit etre fiable et a jour.  Il n'y a rien de plus
     irritant que de rencontrer un programme se comportant  differemment
     de  ce  qui  est  decrit  dans  son  manuel.  Les utilisateurs vous
     maudiront, vous enverront des courriers d'insulte, puis rejetteront
     a jamais tout autre travail venant de vous.

  La  methode  traditionnelle  pour  acceder  a  la  documentation  sous
  UNIX  fait appel  a la  commande  man(1).   Ce  document   decrit  les
  operations necessaires pour la redaction d'une page de manuel qui sera
  correctement traitee par  les outils de formatage prevus  a cet effet.
  Parmi   ces   outils,  les  plus  importants  sont  man(1),  xman(1x),
  apropos(1), makewhatis(8) et catman(8).

  La qualite et la veracite des informations sont de votre ressort, bien
  entendu.  Malgre tout, vous trouverez dans ce guide quelques idees qui
  vous permettront d'eviter certains pieges courants.

  22..  OOrrggaanniissaattiioonn eett pprriinncciippee dduu mmaannuueell eenn lliiggnnee

  Il vous vaut  connaitre avec precision le mecanisme d'acces  aux pages
  de  manuel  afin  de  savoir donner un nom correct a vos documents, et
  d'etre capable  de  les installer  au  bon  endroit.  Chaque page   de
  manuel  appartient   a   une   _s_e_c_t_i_o_n   specifique,  denotee  par  un
  simple chiffre. Les  sections les  plus  courantes   rencontrees  sous
  LLiinnuuxx sont :

  +o  11  : commandes utilisateur pouvant etre executees par tout le monde
     ;

  +o  22 : appels systeme, c'est-a-dire  les  fonctions  fournies  par  le
     noyau ;

  +o  33 : fonctions des bibliotheques ;

  +o  44  :  peripheriques,  c'est-a-dire  les  fichiers speciaux que l'on
     trouve dans le repertoire /dev ;

  +o  55 :  descriptions  des  formats  de  fichiers  (comme  par  exemple
     /etc/passwd) ;

  +o  66 : les jeux, sans commentaire...

  +o  77 : divers (macros, conventions particulieres, ...) ;

  +o  88  :  outils d'administration systeme executables uniquement par le
     superutilisateur (root) ;

  +o  99  :  un  autre  endroit  (specifique  a  LLiinnuuxx)   destine   a   la
     documentation des services offerts par le noyau ;

  +o  nn  :  nouvelle  documentation,  qui  pourra  etre  deplacee vers un
     endroit plus approprie ;

  +o  oo : ancienne documentation,  qui  peut  etre  conservee  encore  un
     certain temps ;

  +o  ll : documentation locale, propre a ce systeme particulier.

  Le nom du fichier source d'une  page de manuel (le fichier d'entree du
  systeme de formatage) est constitue du  nom de la commande decrite (ou
  de  la fonction,  du fichier,  etc.), suivi  d'un point  et du  numero
  de  section. Si  par  exemple  vous documentez  le  format du  fichier
  "_p_a_s_s_w_d",   vous  devrez   appeler   votre fichier  source "_p_a_s_s_w_d_._5".
  Vous voyez  ici qu'il peut exister un fichier du   meme   nom   qu'une
  commande   ;   nous  pourrions  tout  aussi  bien avoir  une  fonction
  de  bibliotheque  appelee   "_p_a_s_s_w_d".   L'organisation   en   sections
  constitue    la    methode    habituelle    pour   resoudre   ce  type
  d'ambiguite  :  la description  de  la commande  se trouvera  dans  le
  fichier   "_p_a_s_s_w_d_._1"  et notre hypothetique fonction bibliotheque dans
  "_p_a_s_s_w_d_._3".  (--  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
  "_x_t_e_r_m_._1_x"  ou "_w_i_s_h_._1_t_k". Le but de cette notation est d'indiquer que
  la documentation en question s'applique a un  programme X Window ou  a
  une application  Tk, respectivement.  Certains  programmes d'affichage
  du manuel peuvent exploiter cette particularite ; xman,  par  exemple,
  affichera   "_x_t_e_r_m_(_x_)"   et  "_w_i_s_h_(_t_k_)"   dans  la liste des documents
  disponibles.--)

  Attention  aux  eventuels  conflits   de  noms  avec  des  programmes,
  fonctions  ou  fichiers existants.  Ce  serait  par exemple  une  tres
  mauvaise idee que d'appeler votre nouvel  editeur  de  texte  ed,  sed
  (pour  "super  ed")  ou red (pour "Roger Editions") ! En vous assurant
  que  le nom de votre application  est  unique,  vous   eviterez  qu'un
  utilisateur  execute  votre   programme  par erreur ou lise sa page de
  manuel  a la place de celle dont il desirait prendre connaissance,  ou
  vice  versa.  Vous   pouvez  eventuellement vous aider de  la base  de
  donnees "lsm",  qui recense  beaucoup des programmes disponibles  pour
  LLiinnuuxx.

  Maintenant que nous savons determiner le nom de notre fichier, il nous
  faut  savoir dans  quel  repertoire l'installer  (lorsque la  personne
  qui   installera   votre   application  tapera   la   commande   "make
  install" par exemple).

  Sous  LLiinnuuxx, toutes  les pages  de  manuel   sont  situees   dans  des
  sous-repertoires a partir d'une (ou plusieurs) racine indiquee dans la
  variable  d'environnement MANPATH.  Les outils  de traitement  de   la
  documentation utilisent  cette  variable  de la  meme  maniere que  le
  shell emploie  PATH  pour  localiser les  programmes  executables.  En
  fait,  MANPATH  a  exactement  le  meme format que PATH.  Toutes  deux
  contiennent une  liste  de  repertoires, avec  le    caractere   deux-
  points    comme  element   separateur  (mais MANPATH n'autorise pas de
  champs  vides ou de chemins d'acces relatifs).

  Si MANPATH n'existe pas ou  n'est pas exportee, le repertoire _/_u_s_r_/_m_a_n
  sera    alors   utilise  par  defaut.   Dans  le  but d'accelerer  les
  recherches   et   pour    garder     des    repertoires    de   taille
  raisonnable,   les  repertoires  pointes  par  MANPATH contiennent une
  serie de sous-repertoires  nommes "_m_a_n_S", ou _S  designe  le  caractere
  correspondant  au  numero  de  section  que nous  avons  presente plus
  haut.  Toutes  les  sections ne  sont  pas  representees,  il   n'y  a
  par  exemple   pas  de   raison de  conserver une entree "_m_a_n_o".  Vous
  pourrez  y trouver  egalement des  sous-repertoires  appeles   "_c_a_t_S",
  "_d_v_i_S"   et "_p_s_S",  qui contiennent  la documentation  toute formatee,
  prete a  etre affichee  ou imprimee  : nous  reviendrons sur  ce sujet
  plus  loin. Le  seul  fichier qui  peut  etre present  a  cote de  ces
  sous-repertoires du  repertoire  de  base  s'appelle  "_w_h_a_t_i_s".   Nous
  decrirons son contenu et la maniere de le creer plus tard.

  La  methode   la  plus  sure   pour  installer  au  bon   endroit  une
  page  de   manuel  de    la   section   "S"    est   de    placer   le
  fichier   dans   le    repertoire   _/_u_s_r_/_m_a_n_/_m_a_n_S.   Toutefois  un bon
  Makefile   devra   autoriser  l'utilisateur   a   choisir   un   autre
  repertoire  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  etre   configurees   a  l'aide de
  l'option     --prefix=/mon/option.    Les     pages      de     manuel
  correspondantes seront alors installees a partir du repertoire de base
  _/_m_o_n_/_o_p_t_i_o_n_/_m_a_n.  Nous  vous  conseillons   d'employer   une   methode
  similaire pour vos realisations personnelles.

  22..11..  IIll nn''yy aa ppaass qquuee ll''aannggllaaiiss aauu mmoonnddee......

  Depuis  l'avenement  du  "_S_y_s_t_e_m_e  _d_e  _f_i_c_h_i_e_r_s  _s_t_a_n_d_a_r_d"  pour LLiinnuuxx
  (FSSTnd), les choses se sont un petit peu  compliquees.   Ce  standard
  stipule  que  la structure de _/_u_s_r_/_m_a_n doit etre prevue pour plusieurs
  jeux de pages de manuels,  correspondant  a  differents  langages,  en
  raison de l'internationalisation du systeme. Il est alors introduit un
  niveau d'arborescence  supplementaire  qui  distingue  chaque  langue.
  Voici ce qui est dit dans la version 1.2 de ce standard :

       Le nom des sous-repertoires de langages de _/_u_s_r_/_m_a_n est base
       sur l'annexe E du  standard  POSIX  1003.1,  qui  decrit  la
       chaine  d'identification  _l_o_c_a_l_e  ;  celle-ci constituant la
       methode la mieux acceptee pour decrire un environnement cul-
       turel. Cette chaine _l_o_c_a_l_e est formee ainsi :

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

  Consultez le standard pour obtenir les chaines les plus courantes dans
  nos contrees.  En fonction de ces recommandations,  nous  aurons  donc
  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
  formatees    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 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'etat actuel des choses. Le
  standard  LLiinnuuxx indique  aussi que  "les systemes   n'utilisant  qu'un
  seul  langage et qu'un  seul jeu  de caracteres pour  toutes les pages
  de manuel  peuvent omettre  le  sous-repertoire   _l_o_c_a_l_e  et   stocker
  les   fichiers   dans   _m_a_n_d_i_r".   Par   exemple,  sur   les  machines
  uniquement equipees  pour la  langue anglaise,  qui n'utilise  que  le
  code    ASCII,   on    peut   placer  les   sous-repertoires  _m_a_n_[_1_-_9_]
  directement  dans  _/_u_s_r_/_m_a_n  (en  fait,  il  s'agit  de  l'emplacement
  traditionnel  et  c'est  le  cas le plus frequent  ; c'est  ainsi  que
  sont organises  tous  les systemes  par defaut).
  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  adaptes  a  cette
  nouvelle structure.

  33..  AA qquuooii 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teeee ddooiitt--tt--eellllee rreesssseemmbblleerr ??

  Pour  repondre  a  cette  question,  le  mieux  est  de  presenter  un
  exemple pratique.  En raison de  la nature  et du mode  de realisation
  ce  ce  document,  nous  ne  pouvons  pas  reproduire  les  caracteres
  accentues,  ni  les  differents  enrichissements  du  texte  (gras  et
  italiques principalement) ; consultez  la section traitant des polices
  de caracteres pour obtenir des details sur ces possibilites.

  Voici  comment  se  presente  la  page  de  manuel  de notre programme
  hypothetique "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 indispensable.  Les pages de manuel  sans
        section  NAME  sont  aussi  inutiles qu'un refrigerateur au pole
        nord.  Cette  section  possede  aussi  un   format   standardise
        consistant  en  une  liste de noms de programmes ou de fonctions
        suivis d'un tiret ou d'une  courte  description  (une  ligne  en
        general)  des  fonctionnalites,  l'element  separateur  de cette
        liste  etant  la  virgule.   C'est  le   format   exploite   par
        l'utilitaire makewhatis(8), qui analyse ces noms de section pour
        les integrer dans la base de donnees whatis :  Voila pourquoi il
        est  important  de  respecter  cette  organisation. Dans le code
        source groff, cela donne quelque chose comme ceci :

                .SH NAME
                prout \- proutibule la bibliotheque plaf

     Le "_b_a_c_k_s_l_a_s_h" est tres  important : cette contre-oblique est  nec-
     essaire  pour que le tiret  qui suit soit distingue d'une marque de
     cesure, qui peut apparaitre aussi  bien dans le nom de commande que
     dans la ligne de description.

     AAtttteennttiioonn  :  en  l'etat  actuel  des  choses,  vous  ne pouvez pas
     traduire NAME par NOM en francais, a 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SIISS
        Elle  permet de donner un court apercu des options du programme.
        Dans le cas des fonctions, cette section contient  les  fichiers
        d'en-tetes   qu'il   est  necessaire  d'inclure,  ainsi  que  le
        prototype afin que le  programmeur  connaisse  immediatement  le
        type et le nombre des arguments demandes ainsi que le type de la
        valeur 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
        C'est elle  qui explique  en detail  pourquoi votre  sequence de
        0 et de  1  est  meilleure  que  toutes les  autres.  C'est  ici
        que  vous etalez tout votre savoir !  Gagnez l'estime des autres
        developpeurs et  l'admiration  des utilisateurs  en  faisant  de
        cette  section  la reference   absolue,  contenant   toutes  les
        informations   possibles   sur  votre  application,  avec  force
        details. Expliquez  clairement  le  role  de  chaque   argument,
        decrivez   le  format  des  fichiers  utilises,  les algorithmes
        qui effectuent le plus dur du travail, etc.

      LLaa sseeccttiioonn OOPPTTIIOONNSS
        Elle  donne  une  description  de  chaque  option  modifiant  le
        comportement du programme. Vous deviez vous en douter...
      LLaa sseeccttiioonn FFIICCHHIIEERRSS
        Elle  indique  quels sont les fichiers utilises 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 preferable  de  donner  leur  chemin
        d'acces  complet  et  de  se  debrouiller  pour que la procedure
        d'installation modifie la partie repertoire de ces chemins  dans
        la page de manuel, en fonction des preferences de l'utilisateur.
        Pour citer un exemple, l'application GNU  groff  s'installe  par
        defaut  dans  _/_u_s_r_/_l_o_c_a_l,  les  pages de manuel referencent donc
        _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_g_r_o_f_f_/_*.  Mais  si  vous  l'installez  par  "make
        prefix=/opt/gnu",  toutes  les  pages de manuel seront modifiees
        pour indiquer _/_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
        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'acces,
        des noms de fichiers ou des options par defaut.

      LLaa sseeccttiioonn DDIIAAGGNNOOSSTTIICCSS
        Elle  doit  donner  un  apercu  des  messages  d'erreur les plus
        courants susceptibles d'etre affiches par le programme,  et  les
        eventuelles  solutions  a ces problemes. Il n'est pas necessaire
        de citer les messages d'erreur du systeme (issus  de  perror(3))
        ou  fatals  (issus  de  psignal(3))  car  ils peuvent apparaitre
        durant l'execution de n'importe quel programme.

      LLaa sseeccttiioonn BBOOGGUUEESS
        Dans un monde ideal, cette section n'aurait pas  lieu  d'etre  !
        Si  vous etes brave, vous pourrez decrire ici les limites et les
        inconvenients de votre application, voire  les  caracteristiques
        que  certains  pourraient  considerer  comme des defauts. Sinon,
        faites la meme liste mais renommez cette section "A FAIRE"...

      LLaa sseeccttiioonn AAUUTTEEUURR
        Elle  est tres  utile pour  savoir qui  a fait  quoi,  et   pour
        trouver l'adresse  a laquelle  envoyer un  rapport  de bogue  en
        cas  d'erreur  grossiere  dans  la   documentation  (ce  qui  ne
        devrait   pas   arriver  !)  ou  d'un  comportement  anormal  du
        programme.

      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  a  l'application,
        citees par ordre alphabetique. Par convention, c'est la derniere
        section.

  Vous etes libre d'inventer toute autre  section, si le cas  a  traiter
  ne  peut   se  classer   dans  aucune   de  celles   que  nous  venons
  d'enumerer.  Nous  avons volontairement  decrit une  version francisee
  de  page   de  manuel,  puisque  ce  document  est  destine  aux  pays
  francophones.  Neanmoins, 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   realite,  dans   l'ordre   :   NAME,   SYNOPSIS,
  DESCRIPTION,   OPTIONS,  FILES, ENVIRONMENT, DIAGNOSTICS, BUGS, AUTHOR
  et SEE ALSO.

  Tout cela est tres bien, mais comment  generer  cette  belle  page  de
  manuel  ? Nous nous attendions a cette question ! Alors, voici le code
  source complet :

   .\" 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 ??

  De  nombreux  programmes  (grep, egrep) et fonctions (printf, fprintf,
  ...)  sont  decrits  dans  un   seul   document.    Toutefois,   cette
  documentation  serait quasiment inutile si elle n'etait accessible que
  sous un seul nom. Nous ne pouvons pas  demander  aux  utilisateurs  de
  memoriser que la page de manuel de egrep est en realite celle de grep.
  Il est par consequent indispensable que la page soit  accessible  sous
  plusieurs  noms  differents.   Il  existe  plusieurs possibilites pour
  obtenir cela :

  1. realiser plusieurs copies du document, une par nom ;

  2. connecter toutes ces pages par des liens physiques ;

  3. plusieurs liens symboliques pointant vers un unique document ;

  4. faire appel au mecanisme de "source"  de  groff,  en  employant  la
     macro-instruction ".so".

  La premiere  solution est  une perte  de place,  il faut  l'eviter. La
  seconde n'est pas recommandee, car  les  versions  "intelligentes"  de
  l'utilitaire    catman    peuvent   gagner  beaucoup   de   temps   en
  detectant  le type  ou  le  contenu du  fichier.  Les liens  materiels
  reduiront  l'efficacite  de  cet outil (dont le but est de formater  a
  l'avance toutes  les  pages   de  manuel   existantes   afin  qu'elles
  s'affichent  toutes rapidement, sans que  l'utilisateur doive attendre
  le temps necessaire a ce traitement eventuel).  La troisieme  solution
  comporte  un  piege  :  si vous etes concerne par la portabilite, vous
  devez savoir qu'il existe des systemes de fichiers ne connaissant  pas
  les  liens  symboliques.  En  conclusion,  la  meilleure chose a faire
  consiste a employer la macro  ".so".

  Voici comment operer : si vous desirez que votre page de  manuel  soit
  accessible  par  les noms "truc" et "bidule" dans la section 1, mettez
  le document dans truc.1 et realisez un fichier bidule.1 contenant ceci
  :

          .so man1/truc.1

  Il  est  tres important de ne pas oublier le repertoire _m_a_n_1, car lors
  de l'execution de groff, celui-ci aura  comme  repertoire  courant  le
  repertoire  de  base des pages de manuel, et il interpretera les argu-
  ments a .so comme etant relatifs a 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 cchhooiissiirr ??

  Il existe un certain nombre de jeux  de  macros  etudies  specialement
  pour la confection de pages de manuel. On les trouve generalement dans
  le repertoire _/_u_s_r_/_l_i_b_/_g_r_o_f_f_/_t_m_a_c. Les noms des fichiers sont du genre
  _t_m_a_c_._<_q_u_e_l_q_u_e_-_c_h_o_s_e_>,   ou  _<_q_u_e_l_q_u_e_-_c_h_o_s_e_>  est  l'argument  passe  a
  l'option -m de groff. Souvent, l'espace entre  -m  et  _<_q_u_e_l_q_u_e_-_c_h_o_s_e_>
  est omis, de sorte que l'on peut ecrire groff -man lorsque l'on desire
  formater des pages utilisant le jeu de macros _t_m_a_c_._a_n. Voila la raison
  de ce nom bizarre, "_t_m_a_c_._a_n".

  En  plus  de  ce  _t_m_a_c_._a_n,  il existe un autre ensemble de macros tres
  populaire,  _t_m_a_c_._d_o_c,  qui  provient  de  l'universite  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  _t_m_a_c_._d_o_c sont bien plus souples mais malheureusement, beaucoup
  d'outils de lecture du manuel n'y font pas appel et utilisent toujours
  la commande groff -man. Par exemple, tous les programmes xman que nous
  avons rencontres affichent n'importe quoi lorsqu'ils  rencontrent  des
  pages  prevues  pour  ces  macros  _t_m_a_c_._d_o_c.   Alors,  vous devez vous
  resigner : n'utilisez que _t_m_a_c_._a_n (l'emploi de tout autre ensemble  de
  macros  est tres risque).  Le jeu _t_m_a_c_._a_n_d_o_c est un pseudo ensemble de
  macros qui analyse  le  code  source  et  charge  soit  _t_m_a_c_._a_n,  soit
  _t_m_a_c_._d_o_c   selon   son   contenu.   En   fait,   tous  les  programmes
  d'exploitation du manuel devraient l'utiliser,  mais  jusqu'a  present
  peu  le  font, aussi il vaut mieux assurer le coup en se cantonnant au
  bon vieux _t_m_a_c_._a_n. A partir de maintenant, tout ce que nous  decrirons
  concernant  les  macros  ne sera valable que pour _t_m_a_c_._a_n. (-- Si vous
  voulez malgre tout employer les macros _t_m_a_c_._a_n_d_o_c, voici  un  pointeur
  vers   leur   documentation  et  un  mode  d'emploi  tres  detaille  :
  <http://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 realisation des pages de manuel
  BSD.--)

  66..  QQuueellss pprreepprroocceesssseeuurrss uuttiilliisseerr ??

  Groff  est fourni  avec au moins trois  preprocesseurs : tbl, eqn   et
  pic   (sur  certains   systemes   ils    se   nomment  gtbl,  geqn  et
  gpic).  Ils  sont  destines  a traduire des macro-instructions de pre-
  traitement et leurs arguments  en  code  source  troff   standard.  Le
  programme  tbl   est  un   preprocesseur  de  tableaux,  eqn  gere les
  equations et les  mathematiques  en  general,  et  enfin  pic  est  un
  preprocesseur  d'images. Consultez leurs pages de  manuel  respectives
  pour  decouvrir  les  fonctionnalites  qu'ils proposent.

  Mais  autant  etre  clair  :  n'ecrivez  jamais  de  pages  de  manuel
  necessitant quelque preprocesseur que ce soit.

  Eqn    produira  generalement   une  sortie   catastrophique  pour les
  peripheriques  du  genre    teletype   ;   malheureusement   99%   des
  terminaux  sur  lesquels  sont  lues  les  pages  de  manuel  en  font
  partie. Par  exemple,  _X_A_l_l_o_c_C_o_l_o_r_._3_x  contient  quelques  expressions
  mathematiques  avec  des  exposants.  En   raison  de  la  nature  des
  peripheriques d'affichage,  ces exposants se retrouveront  sur la meme
  ligne   que   le  texte   de  base  : "_N  _p_u_i_s_s_a_n_c_e  _d_e_u_x" s'affichera
  "N2".

  Il faut eviter tbl  car  tous  les  programmes  xman  que  nous  avons
  rencontres  ne  fonctionnent pas avec lui. Xman 3.1.6 utilise la ligne
  de commande suivante pour formater les pages de  manuel,  par  exemple
  signal(7) :

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

  Elle  coince sur toutes les  sources utilisant gtbl, car sa sortie est
  renvoyee une  fois de plus dans son entree.   Le  resultat  donne  une
  page de manuel  sans le tableau voulu. Nous ne  savons pas s'il s'agit
  d'un  bogue ou  d'une particularite  de gtbl,  qui n'aime  pas sa pro-
  pre  sortie,  ou   si  xman devrait etre un peu  plus gentil et ne pas
  l'appeler  deux  fois...  Quoi  qu'il en  soit,  si  vous   voulez  un
  tableau, formatez-le  vous-meme  et inserez-le  entre deux  lignes
  tard. Vous  ne pourrez pas  obtenir de  gras ou d'italiques  par cette
  methode, mais cela  vous evitera de voir votre  beau tableau disparaitre
  au hasard des systemes d'exploitation employes.

  Nous n'avons encore jamais rencontre  de page de manuel necessitant un
  traitement par  pic. Mais  nous n'aimerions  pas   ca  !   Comme  vous
  pouvez  le  voir dans l'exemple ci-dessus, xman ne l'appelle jamais et
  les donnees lui etant destinees donneraient sans doute le vertige a ce
  pauvre groff.

  77..  DDiissttrriibbuuttiioonn :: ccooddee ssoouurrccee eett//oouu ddooccuummeennttaattiioonn ffoorrmmaatteeee ??

  Voyons  les  avantages  (+)  et  les  inconvenients  (-)  de  quelques
  combinaisons possibles :

  1. code source uniquement :

  +o  (+) taille de la distribution tres reduite ;

  +o  (-) inutilisable sur les systemes demunis de groff.

  2. version formatee non compactee uniquement :

  +o  (+) utilisable meme sur les systemes depourvus de groff ;

  +o  (-)  l'utilisateur ne peut pas generer de fichier DVI ou _P_o_s_t_S_c_r_i_p_t
     ;

  +o  (-) gachis de place disque sur les systemes sachant aussi gerer les
     pages compactees.

  3. version formatee et compactee uniquement :

  +o  (+) utilisable meme sur les systemes depourvus de groff ;

  +o  (-)  l'utilisateur ne peut pas generer de fichier DVI ou _P_o_s_t_S_c_r_i_p_t
     ;

  +o  (-) quel format de compactage utiliser ? .Z ? .z ? .gz ?  Tous  les
     trois ?

  4. code source plus version formatee non compactee :

  +o  (+) accessible meme sur les systemes demunis de groff ;

  +o  (-) taille de la distribution plus importante ;

  +o  (-)  certains  systemes  peuvent  necessiter  des  pages  formatees
     compressees ;

  +o  (-) informations redondantes sur les systemes equipes de groff.

  A  notre    avis,   la   meilleure   solution    est   de   distribuer
  uniquement le code  source. Le fait que cette  documentation ne pourra
  pas etre exploitee  sur une machine  sur  laquelle   groff  n'est  pas
  installe  n'a  aucune importance.  Plus  de  500  pages de  manuel  du
  _p_r_o_j_e_t _d_e _d_o_c_u_m_e_n_t_a_t_i_o_n _L_i_n_u_x ne  sont fournies 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,  nous   n'avons
  pratiquement jamais rencontre de logiciels distribues avec leurs pages
  de  manuel  preformatees.  Si  un  administrateur  a  vraiment  besoin
  d'acceder  aux pages  de  manuel  de son  systeme,  il aura  forcement
  installe groff.

  88..  FFoonntteess ddiissppoonniibblleess  eett ccoonnvveennttiioonnss ttyyppooggrraapphhiiqquueess

  N'utilisez jamais des operateurs directs comme \fB \fP, etc.  Employez
  des macros qui prennent des arguments, vous  eviterez  ainsi  l'erreur
  classique  :  l'oubli  du  changement  de fonte a 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 frequente que vous
  ne pouvez l'imaginez !

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

          .B    caracteres 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 reduite (9/10 du corps normal)
          .SB   gras, taille reduite (tout le texte, pas d'alternance)

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

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

  Les  caracteres  de  protection (" ") sont necessaires pour placer des
  espaces dans ces arguments.

  Voila donc pour ce qui est disponible. Voyons  maintenant  comment  il
  faut  utiliser  ces possibilites (nous avons honteusement copie ce qui
  est decrit dans man(7)) :

  Bien  qu'il  existe  dans  le monde  UNIX  de  nombreuses  conventions
  typographiques  arbitraires pour  la realisation  de pages  de manuel,
  plusieurs  centaines de  pages specifiques  a Linux  se conforment  au
  standard suivant :

  Les  fonctions  et  les arguments sont toujours indiques en italiques,
  meme dans la section SYNOPSYS, le reste de la fonction  etant  imprime
  en corps gras :

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

  Les  noms de fichiers sont toujours en italiques, sauf dans la section
  SYNOPSYS, ou les fichiers a inclure sont en gras. Vous ecrirez donc :
          .I /usr/include/stdio.h
          .B #include <stdio.h>

  Les noms de macros, qui sont la plupart du temps en  majuscules,  sont
  typographies en gras :

          .B MAXINT

  Dans  les  enumerations  de  codes  d'erreur,  les codes sont en gras.
  Cette liste fait generalement appel a 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
          a une valeur incorrecte.

  Toute  reference  a  une  autre page de manuel (ou au sujet de la page
  courante) est en gras. Si la  section  correspondante  du  manuel  est
  indiquee, elle s'ecrit en roman, sans espace :

          .BR man (7)

  Les acronymes sont plus elegants lorsqu'ils apparaissent dans un corps
  plus petit, nous vous recommandons par consequent d'employer :

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

  99..  CCoonnsseeiillss,, ttrruuccss eett aassttuucceess

  99..11..  PPeeaauuffiinneezz vvoottrree ppaaggee ddee mmaannuueell

  Voici quelques conseils pour ameliorer la lisibilite, la validite  des
  informations   fournies   et   la   facilite  de  formatage  de  votre
  documentation :

  +o  vos  exemples  doivent   fonctionner,   testez-les   (utilisez   le
     couper/coller  pour passer a votre shell le code exact indique dans
     la page de manuel), redirigez l'affichage dans votre fichier source
     (ne  tapez  pas  vous-meme  ce  que vous pensez que votre programme
     affichera) ;

  +o  relisez-vous, faites relire votre document par des tiers,  corrigez
     toutes  les  eventuelles fautes de frappe ou d'orthographe (surtout
     si vous ne redigez pas le texte dans votre langue natale) ;

  +o  testez votre page : est-ce que groff trouve  des  erreurs  lors  du
     formatage  ?  Il  est  agreable  de  trouver dans un commentaire la
     commande necessaire pour formater le document.  Est-ce  que  man(1)
     affiche  des  avertissement  ou des erreurs lorsque vous tapez "man
     votre-programme" ?  Est-ce que la facon  dont  man(1)  utilise  les
     outils  de  formatage produit les resultats escomptes ?  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 decompacte les pages par
     ces commandes :

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

  +o  est-ce que makewhatis(8) arrive a extraire les descriptions sur une
     ligne de la section NAME ?

  99..22..   CCoommmmeenntt oobbtteenniirr uunnee ssoorrttiiee ppuurr aasscciiii ssaannss cceess ffiicchhuuss ccaarraacctteerreess
  ddee ccoonnttrroollee ??

  Jetez  un  coup  d'oeil  a  col(1)  ;  il  s'agit d'un filtre qui peut
  eliminer ces sequences de surimpression. Au cas ou  vous  seriez  trop
  paresseux  pour  reflechir  vous-meme  au  probleme, voici la commande
  magique :

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

  Les options -t et -e indique a groff de faire appel aux preprocesseurs
  tbl  et  eqn.  C'est  inutile  pour les pages de manuel ne necessitant
  aucun pre-traitement, mais cela ne gene pas, si ce n'est par la petite
  charge supplementaire induite. En revanche, ne pas utiliser -t lorsque
  ce serait necessaire est une tres mauvaise chose  :  le  tableau  sera
  extremement  mal formate. Vous pourrez meme trouver (deviner serait un
  terme plus exact) la commande necessaire pour traiter tel ou tel docu-
  ment 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...) : il tente de deviner la commande necessaire
  pour formater un document groff en fonction de son contenu. S'il etait
  parfait,  nous  n'aurions jamais plus besoin d'options. Mais il arrive
  qu'il determine un mauvais jeu de macros ; nous ne l'avons par  contre
  jamais vu se tromper sur les preprocesseurs a employer.

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

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

  Il  faut  appeler  ce  programme  en  tant que premier filtre apres 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

  99..33..  CCoommmmeenntt oobbtteenniirr uunnee ssoorrttiiee _P_o_s_t_S_c_r_i_p_t ddee hhaauuttee qquuaalliittee ??

  C'est tres simple :

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

  Imprimez _m_a_n_p_a_g_e_._p_s avec votre imprimante PostScript  preferee.   Con-
  sultez  la  section  precedente  pour obtenir des explications sur les
  options.

  99..44..  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 ccoommmmaannddeess aapprrooppooss et whatis ?

  Supposons  que  vous recherchiez quels sont les compilateurs installes
  sur votre systeme, et comment les invoquer( nous  considerons  le  cas
  courant,  ou  tout  le manuel est en langue anglaise). Pour repondre a
  cette question (frequemment posee), il faut faire :

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

  Les commandes apropos et whatis sont destinees a obtenir rapidement le
  nom  de la page de manuel traitant de tel ou tel sujet. Tous deux font
  appel a un certain nombre de fichiers nommes "_w_h_a_t_i_s", que  l'on  peut
  trouver  dans  chaque repertoire de base du manuel. Comme nous l'avons
  dit auparavant, cette base de donnees _w_h_a_t_i_s contient une entree d'une
  ligne  pour  chaque page de manuel presente dans l'arborescence corre-
  spondante. En fait, cette ligne est exactement  celle  de  la  section
  NAME  (pour etre precis, tout est reduit a une seule ligne et le tiret
  est supprime, la section etant placee entre parentheses). Les fichiers
  constituant  cette  base  de donnees sont crees par le programme make-
  whatis(8). Il en existe plusieurs versions,  par  consequent  nous  ne
  pouvons que vous renvoyer a leur propre documentation pour leur utili-
  sation. Afin que cet outil fonctionne correctement, il est  necessaire
  que  vous, le redacteur des pages de manuel, vous conformiez au format
  de la section NAME decrit plus haut dans ce document.

  La difference entre apropos et whatis est  le  mode  de  recherche  et
  l'affichage  obtenu  : apropos (qui est equivalent a man -k) recherche
  la chaine passee en argument a n'importe quel  endroit  de  la  ligne,
  alors  que  whatis  (equivalent a man -f) recherche un nom de commande
  complet,  uniquement  sur  la  partie  situee  avant  le  tiret.   Par
  consequent,  "whatis cc" indiquera s'il existe une page de manuel pour
  cc, mais ne dira rien a propos de gcc.

  99..55..  LLaa llaanngguuee ffrraannccaaiissee

  C'est bien sur a vous de decider si vous allez rediger votre manuel en
  francais, en anglais ou dans ces deux langues. Le francais possede des
  regles typographiques tres differentes de l'anglais  :  n'esperez  pas
  pouvoir  les  respecter  avec  les  outils  de  formatage  du  manuel.
  Consultez la documentation de groff si vous desirez lui faire  prendre
  en  compte les motifs de cesure de la langue de Moliere, mais en ayant
  conscience que ce ne  sera  sans  doute  pas  possible  sur  tous  les
  systemes  sur  lesquels  votre  documentation  est  susceptible d'etre
  exploitee.

  Vous pouvez utiliser les caracteres accentues,  pourvu  qu'ils  soient
  saisis  selon  la  norme  ISO-8859-1  (standard sous Linux). Les pages
  devront alors etre formatees avec l'option  -Tlatin1 .  Mais il faudra
  que  toute  la  chaine  de  visualisation  soit  capable  de gerer les
  caracteres ISO sur 8 bits,  ce  qui  est  rarement  le  cas  sans  une
  configuration   particuliere   des   utilitaires   "more"   ou  "less"
  generalement employes.

  Vous voila prevenu  !

  1100..  CCooppyyrriigghhtt

  Ce    document   est    copyright   (C)    1995   Jens    Schweikhardt
  <jens@kssun3.rus.uni-stuttgart.de>.   Il    peut   etre  reproduit  et
  distribue  en  tout  ou  partie,  sur   tout   support   physique   ou
  electronique, a condition  que cette notice soit  incluse dans chacune
  des copies.  Sa diffusion  commerciale est  autorisee et  encouragee ;
  toutefois l'auteur desire etre prevenu dans ce cas.

  Toute traduction,  travail derive, ou compilation  de travaux incluant
  quelque  document  Linux _H_O_W_T_O  que  ce  soit doit  etre  couvert  par
  ce   present   copyright.   C'est-a-dire   que   vous  ne  pouvez  pas
  realiser un ouvrage derive d'un  _H_O_W_T_O  et  imposer  des  restrictions
  supplementaires  sur sa  distribution.  Des derogations  a ces  regles
  peuvent  etre  accordees  sous  certaines conditions  ;  contactez  le
  coordinateur a l'adresse donnee ci-apres pour plus de precisions.

  En  resume,  nous  avons  le  desir  de promouvoir la diffusion de ces
  informations par le  plus  de  canaux  possibles.  Malgre  tout,  nous
  voulons  conserver la propriete des documents _H_O_W_T_O, et aimerions etre
  tenu au courant de tout projet de redistribution.

  Si vous avez  des questions, contactez Greg  Hankins, le coordinateur,
  par  courrier  electronique a l'adresse  gregh@sunsite.unc.edu, ou par
  telephone au +1 404 853 9989.

