このページは大阪弁化フィルタによって翻訳生成されたんですわ。

翻訳前ページへ
que l'on trouve dans le r駱ertoire /dev ;
  • 5 : descriptions des formats de fichiers (comme par exemple /etc/passwd ;
  • 6 : les jeux, sans commentaire...
  • 7 : divers (macros, conventions particuli鑽es, ...) ;
    • Le nom du fichier source d'une page de manuel (le fichier d'entr馥 du syst鑪e de formatage) est le nom de la commande d馗rite (ou de la fonction, du fichier, etc.), suivi d'un point et du num駻o de section. Si, par exemple, vous documentez le format du fichier "passwd", vous devez appeler le fichier source "passwd.5". Nous avons ici un exemple d'un fichier qui porte le m麥e nom qu'une commande ; nous aurions tout aussi bien avoir une fonction de biblioth鑷ue appel馥 "passwd". L'organisation en sections constitue la par exemple "xterm.1x" ou "wish.1tk". 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 mauvaise id馥 d'馗rire un autre 馘iteur 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 騅iterez que quelqu'un ex馗ute votre programme et qu'il lise la page de manuel documentation l'utilisent de la m麥e mani鑽e que le shell utilise la variable PATH pour trouver les ex馗utables. En fait, MANPATH a le m麥e format que PATH : toutes les deux sont une liste de r駱ertoires s駱ar駸 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馥, /usr/man est utilis馥 comme valeur par d馭aut. Dans le but d'acc駘erer la recherche et pour garder les r駱ertoires de taille ne sont pas repr駸ent馥s, il n'y a pas, par exemple de raison de garder une entr馥 "mano". Vous pourrez y trouver 馮alement des sous-r駱ertoires appel駸 "cat<s>", "dvi<s>" et "ps<s>", qui contiennent cr饌tion de ce fichier sera d馗rit dans la section 11. La m騁hode la plus s?e pour installer au bon endroit une page de manuel de la section "s" est de mettre le fichier dans le r駱ertoire "/usr/man/man<s>". Toutefois, un bon

    Depuis l'av鈩ement du "Syst鑪e de fichiers standard" pour Linux (FS-STnd), les choses se sont compliqu馥s. Le FS-STnd 1.2 stipule que :

    des am駭agements doivent 黎re faits dans la structure de /usr/man pour supporter des pages de manuel 馗rites dans diff駻entes (ou mutiples) langues.

    Ceci est fait en introduisant un niveau de r駱ertoires suppl駑entaire qui distingue les diff駻entes langues. Citant encore le FS-Stnd 1.2 :

    Le nommage des sous-r駱ertoires correspondants aux langues cha?e locale se pr駸ente sous la forme 
                <langage>[_<pays>][.<jeu-de-caracteres>][,<version>]
    (Reportez vous au FS-Stnd pour voir quelques cha?es localecourantes.) D'apr鑚 ces recommandations, nous avons nos pages de manuel dans /usr/man/<locale>/man[1-9lno]. Les versions format馥s se trouveraient alors bien entendu dans /usr/man/<locale>/cat[1-9lno] : 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'騁at actuel des choses. Le FS-Stnd 1.2 autorise aussi que

    les syst鑪es qui n'utilisent qu'une seule langue et jeu de caract鑽es pour toutes les pages de manuel peuvent omettre la sous-cha?e <locale> et stocker toutes ces pages dans le r駱ertoire mandir. Par exemple, les machines 駲uip馥s seulement de pages de manuel en anglais cod馥s en ASCII peuvent mettre les pages de manuel (les r駱ertoires man[1-9]) directement dans /usr/man/. Il s'agit en fait de l'arrangement habituel.

    Je (l'auteur du document, pas le traducteur) ne changerai pas ma configuration tant que tous les outils (comme

    Laissez-moi vous pr駸enter un exemple que j'expliquerai plus tard. En raison de la nature et du mode de r饌lisation de ce document, nous ne pouvons pas reproduire les caract鑽es accentu駸, ni les diff駻ents enrichissements du texte (gras et italiques principalement) ; consultez la section traitant des polices de caract鑽es pour obtenir des d騁ails sur ces possibilit駸.

    Voici comment se pr駸ente la page de manuel de notre programme hyphoth騁ique "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 :

    La section NAME :

    C'est la seule section requise.

    La section DESCRIPTION

    Elle explique en d騁ail pourquoi votre s駲uence de 0 et de 1 est la meilleure de toutes. C'est ici que vous 騁alez tout votre savoir ! Gagnez l'estime des autres programmeurs et des utilisateurs en faisant de cette section une source d'information s?e et programme. Vous le saviez, n'est-ce pas ?

    La section FICHIERS

    Elle indique les fichiers utilis駸 par le programme ou la fonction. Par exemple, les fichiers de configuration, les fichiers de d駑arrage, les fichiers sur lesquels le programme agit. Ce serait une bonne id馥 de donner les chemins absolus de ces fichiers et d'avoir un processus d'installation qui modifie la partie r駱ertoire selon les pr馭駻ences de l'utilisateur : les manuels de groff ont comme pr馭ixe par d馭aut /usr/local, donc ils r馭駻encent /usrl/local/lib/groff/* par d馭aut. Cependant, si vous installez en utilisant "make prefix=/opt/gnu", les r馭駻ences dans la page de manuel change en /opt/gnu/lib/groff/*.

    La section ENVIRONNEMENT

    fait la liste de toutes les variables d'environnement qui affectent votre programme ou fonction et, bien s?, explique comment. La plupart du temps, les variables syst鑪e (de perror(3)) ou des signaux fatals (de psignal(3)) qui peuvent appara?re pendant l'ex馗ution de tout programme.

    La section BOGUES

    Devrait id饌lement ne pas exister. Si vous 黎es brave, vous pouvez d馗rire ici les limitations, les inconv駭ients, les caract駻istiques que certains pourraient prendre pour des d馭auts. Si vous n'黎es pas brave, renommez-la en section "A FAIRE".

    La section AUTEUR

    Il est appr馗iable de l'avoir quand il y a des erreurs grossi鑽es dans la documentation ou dans le comportement du programme et que vous voulez envoyer un rapport de bogue.

    La section VOIR AUSSI

    C'est une liste de pages de manuel 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. Comment documenter plusieurs choses dans une seule page de manuel ?

    De nombreux programmes (grep, egrep) et fonctions (printf, fprintf,...) sont document馥s dans une seule page de manuel. Cependant, ces pages seraient inutilisables si elles n'騁aient accessibles que par un seul nom. Nous ne pouvous nous

  • avoir des copies identiques pour chaque nom ;
  • connecter toutes les pages de manuels en utilisant des liens physiques ;
  • utiliser les liens symboliques pointant la page de manuel ;

    • 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 r饌lisez le fichier bidule.1 contenant : 

        .SO man1/truc.1
    Il est important de sp馗ifier le r駱ertoire man1/ aussi bien que le nom du fichier truc.1 car lors de l'ex馗ution de <quelque-chose> est l'argument de l'option -m de groff. groff utilisera tmac.<quelque-chose> quand l'option -m <quelque-chose> sera donn馥. Souvent, l'espace mais, h駘as, 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 rencontr馥s faisaient la t黎e devant 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 r饌lisation des pages de manuel BSD.

    6. Quels pr駱rocesseurs puis-je utiliser ?

    groff est fourni avec au moins 3 pr駱rocesseurs, tbl, eqn et pic (certains syst鑪es les nomment gtbl, geqn et pic g鑽e les images. Consultez leurs pages de manuel pour d馗ouvrir les fonctionalit駸 qu'ils proposent.

    Mais autant 黎re clair : n'馗rivez pas de pages de manuel qui utilisent des pr駱rocesseurs.

    eqn produira g駭駻alement un r駸ultat catastrophique sur des p駻iph駻iques du genre t駘騁ype, qui malheureusement repr駸entent 99% des visualtions de pages de manuel. Par exemple XAllocColor.3x contient des formules avec des exposants. A cause de la nature de ces terminaux, l'exposant sera sur la m麥e ligne que la base. «N puissance deux» s'affichera "N2".

    Il vaut mieux 騅iter 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 signal(7) : 

    gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \
/tmp/xmana01760 2> /dev/null
    gtbl qui s'騁rangle sur sa propre sortie ou si xman devrait 黎re un peu plus gentil et ne pas utiliser gtbl deux fois... De toute fa輟n, si vous voulez un tableau, formatez-le vous-m麥e 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 m騁hode mais elle permettra d'avoir votre tableau dans tous les cas.

    Je n'ai jamais vu une page de manuel n馗essitant le pr駱rocesseur pic mais je n'aimerais pas 軋. Comme vous pouvez le voir plus haut, xman ne l'utilise pas et groff ferait s?ement la danse de Saint-Guy en voyant les donn馥s en entr馥.

  • (-) inutilisable sur les syst鑪es ne disposant pas de groff.
  • verison format馥 non compact馥 uniquement :
    • (+) utilisable m麥e sur des syst鑪es d駱ourvus de groff ;
    • (-) l'utilisateur ne peut pas g駭駻er un fichier dvi ou PostScript ;
    • (-) g稍his de l'espace disque sur les syst鑪es sachant g駻er aussi les pages compress馥s.
  • version format馥 et compact馥 seulement :
    • (+) utilisables m麥e sur des syst鑪es d駱ourvus de groff ;
    • (-) l'utilisateur ne peut pas g駭駻er de fichier dvi ou PostScript ;
    • (-) quel format de compactage utiliser ? .Z ? .z ? .gz ? Tous ?.
  • code source et la version format馥 non compact馥 :
    • (+) accessible m麥e sur les syst鑪es ne disposant pas de groff ;
    • (-) taille de la distribution plus grande ;
    • (-) certains syst鑪es peuvent n馗essiter des pages de manuels formatt馥s et compact馥s ;
    • (-) informations redondantes sur les syst鑪es 駲uip駸 de groff.

    • A mon avis, la meilleure solution est de distribuer uniquement le code source. L'argument selon lequel la documentation ne pourra pas 黎re accessible sur les syst鑪es 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 distribu駸 avec les pages de manuels format馥s. Si un administrateur a besoin que les pages de manuel soient ne le pense !

    Les macros tmac.an offrent les possibilit駸 suivantes :

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

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

    Les guillemets sont n馗essaires pour placer des espaces dans un argument.

    Vous 馗rirez alors : 
    .I /usr/include/stdio.h
    et 
    .B #include <stdio.h>

    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 黎re lu

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

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

    groff trouve des erreurs lors du formatage ? C'est agr饌ble 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 XFree86 3.1 contient la version 3.1.6 de xman qui d馗ompacte 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 ?

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

    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 "GROff Guess", et cet outil fait bien ce qu'il dit (en anglais, guess = deviner...) : il tente de deviner la commande n馗essaire pour formater un document groff en fonction de son contenu. S'il 騁ait parfait, nous n'aurions #!/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 apr鑚 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

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

    12. Comment faire fonctionner les programmes apropos et whatis ?

    Supposons que vous recherchiez les compilateurs install駸 sur votre syst鑪e et comment les invoquer (nous consid駻ons le cas

    apropos et whatis sont utilis馥s pour obtenir une r駱onse rapide sur les pages de manuels qui contiennent des informations sur un certain sujet. Les deux fran軋is poss鐡e des r鑒les typographiques tr鑚 diff駻entes de l'anglais : n'esp駻ez pas pouvoir les respecter avec les outils de formatage du manuel. Consultez la documentation de groff si vous d駸irez lui faire prendre en compte les motifs de c駸ure de la langue de Moli鑽e, mais en ayant conscience que ce ne sera sans doute pas possible sur tous les syst鑪es sur lesquels votre documentation est susceptible d'黎re exploit馥.

    Vous pouvez utiliser les caract鑽es accentu駸, pourvu qu'ils soient saisis selon la norme ISO-8859-1 (standard sous Linux). Les pages devront alors 黎re format馥s avec l'option -Tlatin1 . Mais il faudra que toute la cha?e de visualisation soit capable de g駻er les caract鑽es ISO sur 8 bits, ce qui est

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

    T駘駱hone : ++49 7151 909516

    Sauf mention contraire, les documents Linux HOWTO portent le copyright de leurs auteurs respectifs. Ils peuvent