9. Conseils, trucs et astuces

Contenu de cette section

9.1 Peaufinez votre page de manuel

Voici quelques conseils pour améliorer la lisibilité, la validité des informations fournies et la facilité de formatage de votre documentation :

9.2 Comment obtenir une sortie pur ascii sans ces fichus caractères de contrôle ?

Jetez un coup d'oeil à col(1) ; il s'agit d'un filtre qui peut éliminer ces séquences de surimpression. Au cas où vous seriez trop paresseux pour réfléchir vous-même au problème, voici la commande magique : 

$ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt
Les options -t et -e indique à groff de faire appel aux préprocesseurs tbl et eqn. C'est inutile pour les pages de manuel ne nécessitant aucun pré-traitement, mais cela ne gêne pas, si ce n'est par la petite charge supplémentaire induite. En revanche, ne pas utiliser -t lorsque ce serait nécessaire est une très mauvaise chose : le tableau sera extrêmement mal formaté. Vous pourrez même trouver (deviner serait un terme plus exact) la commande nécessaire pour traiter tel ou tel document 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...) : il tente de deviner la commande nécessaire pour formater un document groff en fonction de son contenu. S'il était parfait, nous n'aurions jamais plus besoin d'options. Mais il arrive qu'il détermine un mauvais jeu de macros ; nous ne l'avons par contre jamais vu se tromper sur les préprocesseurs à employer.

Voici un petit script perl réalisé par l'auteur de ce document, qui peut supprimer les en-têtes et les pieds de page, ce qui permet de gagner quelques feuilles de papier lorsque l'on imprime de longues et complexes pages de manuel. Sauvez-le dans un fichier nommé strip-header 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 après 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.3 Comment obtenir une sortie PostScript de haute qualité ?

C'est très simple : 

$  groff -t -e -mandoc -Tps manpage.1 > manpage.ps
Imprimez manpage.ps avec votre imprimante PostScript préférée. Consultez la section précédente pour obtenir des explications sur les options.

9.4 Comment faire fonctionner les commandes apropos et whatis ?

Supposons que vous recherchiez quels sont les compilateurs installés sur votre système, et comment les invoquer( nous considérons le cas courant, ou tout le manuel est en langue anglaise). Pour répondre à cette question (fréquemment posée), il faut faire : 

$ apropos compiler
f77 (1) - Fortran 77 compiler
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
Les commandes apropos et whatis sont destinées à obtenir rapidement le nom de la page de manuel traitant de tel ou tel sujet. Tous deux font appel à un certain nombre de fichiers nommés "whatis", que l'on peut trouver dans chaque répertoire de base du manuel. Comme nous l'avons dit auparavant, cette base de données whatis contient une entrée d'une ligne pour chaque page de manuel présente dans l'arborescence correspondante. En fait, cette ligne est exactement celle de la section NAME (pour être précis, tout est réduit à une seule ligne et le tiret est supprimé, la section étant placée entre parenthèses). Les fichiers constituant cette base de données sont créés par le programme makewhatis(8). Il en existe plusieurs versions, par conséquent nous ne pouvons que vous renvoyer à leur propre documentation pour leur utilisation. Afin que cet outil fonctionne correctement, il est nécessaire que vous, le rédacteur des pages de manuel, vous conformiez au format de la section NAME décrit plus haut dans ce document.

La différence entre apropos et whatis est le mode de recherche et l'affichage obtenu : apropos (qui est équivalent à man -k) recherche la chaîne passée en argument à n'importe quel endroit de la ligne, alors que whatis (équivalent à man -f) recherche un nom de commande complet, uniquement sur la partie située avant le tiret. Par conséquent, "whatis cc" indiquera s'il existe une page de manuel pour cc, mais ne dira rien à propos de gcc.

9.5 La langue française

C'est bien sûr à vous de décider si vous allez rédiger votre manuel en français, en anglais ou dans ces deux langues. Le français possède des règles typographiques très différentes de l'anglais : n'espérez pas pouvoir les respecter avec les outils de formatage du manuel. Consultez la documentation de groff si vous désirez lui faire prendre en compte les motifs de césure de la langue de Molière, mais en ayant conscience que ce ne sera sans doute pas possible sur tous les systèmes sur lesquels votre documentation est susceptible d'être exploitée.

Vous pouvez utiliser les caractères accentués, pourvu qu'ils soient saisis selon la norme ISO-8859-1 (standard sous Linux). Les pages devront alors être formatées avec l'option -Tlatin1 . Mais il faudra que toute la chaîne de visualisation soit capable de gérer les caractères ISO sur 8 bits, ce qui est rarement le cas sans une configuration particulière des utilitaires "more" ou "less" généralement employés.

Vous voilà prévenu !

Chapitre suivant, Chapitre Précédent

Table des matières de ce chapitre, Table des matières générale

Début du document, Début de ce chapitre