Home

Man page HOWTO - The Linux Documentation Project

1. 11 Comment avoir une belle page de manuel en PostScript 14 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 gt bash txt 11 Comment avoir une belle page de manuel en PostScript groff t e mandoc Tps manpage i gt manpage ps Imprimez la l aide de votre imprimante PostScript pr f r e ou d un interpr teur Voir la section pr c dente pour les options 12 Comment faire fonctionner les programmes apropos et whatis Supposons que vous recherchiez les compilateurs install s sur votre syst me et comment les invoquer nous consid rons le cas courant o tout le manuel est en langue anglaise Pour r pondre cette question fr quemment pos e il faut faire apropos compiler f77 1 Fortran 77 compiler gcc 1 GNU C and C compiler pc 1 Pascal compiler apropos et whatis sont utilis es pour obtenir une r ponse rapide sur les pages de manuels qui contiennent des informations sur un certain sujet Les deux programmes cherchent dans des fichiers nomm s whatis qui sont dans chaque r pertoire de base du manuel Comme je l ai d j dit les fichiers de la base de donn es whatis contiennent une entr e d une ligne pour chaque page de manuel dans l arborescence des r pertoires successifs En fait cette ligne est exactement celle de la section NAME
2. 6 Quels pr processeurs puis je utiliser groff est fourni avec au moins 3 pr processeurs tbl eqn et pic certains syst mes les nomment gtbl geqn et gpic Ils sont destin s traduire leurs macros et leurs donn es en code source troff standard tbl est un pr processeur de tableaux eqn en est un d quation et de math matiques et pic g re les images Consultez leurs pages de manuel pour d couvrir les fonctionalit s qu ils proposent Mais autant tre clair n crivez pas de pages de manuel qui utilisent des pr processeurs eqn produira g n ralement un r sultat catastrophique sur des p riph riques du genre t l type qui mal heureusement repr sentent 99 des visualtions de pages de manuel Par exemple XAllocColor 3x contient 7 Dois je distribuer les sources et ou la documentation d j format e 10 des formules avec des exposants A cause de la nature de ces terminaux l exposant sera sur la m me ligne que la base N puissance deuz 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 signal gtbl usr man man7 signal 7 geqn gtbl groff Tascii man tmp xmana01760 2 gt dev null qui coince sur toutes les sources utilisant gtbl car sa sortie est redirig e encore une fois vers gtbl Le r sultat donne une page de manuel sans
3. pour tre pr cis tout est r duit une seule ligne et le tiret est supprim la section tant plac e entre parenth ses Ces fichiers sont cr s l aide du programme makewhatis 8 Il en existe plusieurs versions donc r f rez vous la page de manuel du programme pour conna tre les options possibles Afin que makefile puisse extraire les sections NAME correctement il est important que vous le r dacteur du manuel respectiez le format de cette section d crit dans la partie 2 La diff rence entre apropos et whatis est ce qu ils recherchent et o apropos qui est l quivalent de man k cherche la cha ne de caract res qui lui est pass e 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 cons quence whatis dira s il y a un manuel de cc mais restera muet pour gcc 13 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 susc
4. sum nous d sirons promouvoir la diffusion de ces informations travers tous les canaux de commu nication possibles Cependant nous voulons conserver la propri t des HOWTO 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
5. t ne pas utiliser t alors qu il est n cessaire fera que les tableaux seront tr s mal format s Vous pourrez m me trouver deviner serait un terme plus exact la commande n cessaire pour traiter tel ou tel document groff pas uniquement des pages de manuel par le biais de grog grog usr man man7 signal 7 groff t man usr man man7 signal 7 En fait grog signifie GRO F Guess et cet outil fait bien ce qu il dit en anglais guess deviner il tente de deviner la commande n cessaire pour formater un document groff en fonction de son contenu S il tait parfait nous n aurions jamais plus besoin d options Mais s il arrive qu il d termine un mauvais jeu de macros je ne l ai par contre jamais vu se tromper sur les pr processeurs employer Voici un petit script Perl r alis par l auteur de ce document qui peut supprimer les en t tes et les pieds de page ce qui permet de gagner quelques longueurs de papier lorsque l on imprime de longues et complexes pages de manuel Sauvez le dans un fichier nomm strip header 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
6. tous les segments glurb et les trie par ordre betagonique decroissant afin que le gloupeur gloup i 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 7 proutre 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 3 A quoi ressemble une page de manuel format e 5 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
7. une seule langue et jeu de caract res pour toutes les pages de manuel peuvent omettre la sous cha ne lt locale gt et stocker toutes ces pages dans le r pertoire mandir Par exemple les machines quip es seulement de pages de manuel en anglais cod es en ASCII peuvent mettre les pages de manuel les r pertoires 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 xman info tkman et beaucoup d autres ne seront pas tous adapt s cette nouvelle structure 3 A quoi ressemble une page de manuel format e Laissez moi vous pr senter un exemple que j expliquerai plus tard En raison de la nature et du mode de r alisation de ce document nous ne pouvons pas reproduire les caract res accentu s ni les diff rents enrichissements du texte gras et italiques principalement consultez la section traitant des polices de caract res pour obtenir des d tails sur ces possibilit s 3 A quoi ressemble une page de manuel format e Voici comment se pr sente la page de manuel de notre programme hyphoth tique prout PROUT 1 Manuel utilisateur PROUT 1 NAME prout proutibule la bibliotheque plaf SYNOPSIS prout plaf l c fichier config fichier DESCRIPTION prout proutibule la bibliotheque plaf en mouglifiant la table des symboles Par defaut la commande recherche
8. usrl local lib groff par d faut Cependant si vous installez en util isant make prefix opt gnu les r f rences 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 r explique comment La plupart du temps les variables contiendront les chemins nom de fichiers options par d faut La section DIAGNOSTIQUES Elle doit donner une vue d ensemble des messages d erreurs les plus courants de votre programme et des ventuelles solutions ces probl mes Il n est pas n cessaire d expliquer les messages d erreurs du syst me de perror 3 ou des signaux fatals de psignal 3 qui peuvent appara tre pendant l ex cution de tout programme La section BOGUES Devrait id alement ne pas exister Si vous tes brave vous pouvez d crire ici les limitations les inconv nients les caract ristiques que certains pourraient prendre pour des d fauts Si vous n tes pas brave renommez la en section A FAIRE La section AUTEUR Il est appr ciable de l avoir quand il y a des erreurs grossi res dans la documentation ou dans le comportement du programme et que vous voulez envoyer un rapport de bogue La section VOIR AUSSI C est une liste de pages de manuel relatives l application cit es par ordre alphab tique Par conven tion c est la derni re section Vous tes l
9. votre tableau Je ne sais pas si c est un bogue ou une particularit de gtb1 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 fa on si vous voulez un tableau formatez le vous m me 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 thode mais elle permettra d avoir votre tableau dans tous les cas Je n ai jamais vu une page de manuel n cessitant le pr processeur pic mais je n aimerais pas a Comme vous pouvez le voir plus haut xman ne l utilise pas et groff ferait s rement la danse de Saint Guy en voyant les donn es en entr e 7 Dois je distribuer les sources et ou la documentation d j for mat e Voyons les avantages et les inconv nients de quelques possibilit s choisies 1 code source uniquement e distribution plus petite e inutilisable sur les syst mes ne disposant pas de groff 2 verison format e non compact e uniquement e utilisable m me sur des syst mes d pourvus de groff Putilisateur ne peut pas g n rer un fichier dvi ou PostScript g chis de l espace disque sur les syst mes sachant g rer aussi les pages compress es e e 3 version format e et compact e seulement e utilisables m me sur des syst mes d pourvus de groff 4 code source et la version forma
10. bluewww shuttle de schweikh home html Man page HOWTO Mars 1998 Adaptation fran aise par Alexandre Devaure adevaure mail dotcom fr 2 juin 1999 Ce HOWTO explique ce que vous devrez avoir en t te quand vous pr voyez d crire une documentation en ligne plus connue sous le nom de page de manuel que vous voulez rendre accessible via la commande man 1 Tout au long de ce HOWTO une entr e du manuel sera simplement appel e page de manuel quelque soit sa longueur r elle et sans intention sexiste Contents 1 Quelques vidences propos de la documentation 1 2 Comment acc de t on aux pages de manuel 1 3 A quoi ressemble une page de manuel format e 3 4 Comment documenter plusieurs choses dans une seule page de manuel 8 5 Quel ensemble de macros utiliser 9 6 Quels pr processeurs puis je utiliser 9 7 Dois je distribuer les sources et ou la documentation d j format e 10 8 Quelles sont les conventions pour les fontes 11 9 Comment dois je pr senter ma page de manuel 12 10 Comment puis je avoir un texte en pur ASCII sans tous ces fichus H de contr le 13 11 Comment avoir une belle page de manuel en PostScript 14 12 Comment faire fonctionner les programmes apropos et whatis 14 13 La langue fran aise 14 14 Les conditions de copie 15 1 Quelques vidences propos de la documentation Pourquoi crivons nous une documentation C est une question b te Parce que nous voulons que d autres personne
11. de macro tman an Voil la raison de ce nom bizarre tman an En plus de tman an il existe un autre ensemble de macro populaire tman doc 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 tman doc sont plus souples mais h las 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 es faisaient la t te devant les pages de manuels requ rant tman doc Donc faites vous une faveur utilisez mac an utiliser un autre ensemble de macros est consid r comme hasardeux tmac andoc est un pseudo ensemble de macros qui regarde le source et charge soit mac an ou tmac doc En fait tous les programmes de lecture du manuel devraient l utiliser mais jusqu pr sent peu le font aussi il vaut mieux assurer le coup en se cantonnant au bon vieux mac an Tout ce que je dirais partir de maintenant concernant les macros est valable seulement pour tmac an Si vous voulez quand m me utiliser les macros de tmac doc voici un pointeur vers leur documentation et un mode d emploi tr s d taill 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 alisation des pages de manuel BSD
12. eptible d tre exploit e 14 Les conditions de copie 15 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 Tlatinl 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 14 Les conditions de copie Copyright 1995 96 97 Jens Schwe kardt schweikh noc dfn de T l phone 49 7151 909516 Sauf mention contraire les documents Linux HOWTO portent le copyright de leurs auteurs respectifs Ils peuvent tre reproduits et distribu s en tout ou partie sur n importe quel support physique ou lectronique condition que cette notice soit incluse dans chaque copie La redistribution est autoris e et encourag e toutefois l auteur voudrait en tre pr venu Toutes les traductions travaux d riv s ou compilation de travaux incluant des documents Linux HOWTO doivent tre couverts par ce copyright C est dire que vous ne pouvez pas produire un travail d riv d un HOWTO et imposer des restrictions suppl mentaires sur sa distribution Des d rogations ces r gles peuvent tre accord es sous certaines conditions contactez le coordinateur des Linux HOWTO dont l adresse est donn e plus loin En r
13. gg re d utiliser une m thode similaire pour vos r alisations personnelles Depuis l av nement du Syst me de fichiers standard pour Linux FS STnd les choses se sont compliqu es Le FS STnd 1 2 stipule que des am nagements doivent tre faits dans la structure de usr man pour supporter des pages de manuel crites dans diff rentes ou mutiples langues Ceci est fait en introduisant un niveau de r pertoires suppl mentaire qui distingue les diff rentes langues Citant encore le FS Stnd 1 2 Le nommage des sous r pertoires correspondants aux langues de usr man est bas sur l appendice E du standard POSIX 1003 1 qui d crit la cha ne de caract res d authentification locale qui est la m thode la mieux accept e pour d crire un environement culturel La cha ne locale se pr sente sous la forme lt langage gt _ lt pays gt lt jeu de caracteres gt lt version gt Reportez vous au FS Stnd pour voir quelques cha nes localecourantes D apr s ces recommandations nous avons nos pages de manuel dans usr man lt locale gt man 1 9ino Les versions format es se trouveraient alors bien entendu dans usr man lt locale gt cat 1 9ino 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 syst mes qui n utilisent qu
14. ibres d en inventer d autres si elles n empietent pas sur celles d crites au dessus Nous avons volontairement d crit une version francis e de page de manuel puisque ce document est destin aux pays francophones N anmoins vous devez avoir conscience que si vous devez diffuser une application dans le monde entier il vous faudra fournir un manuel en langue anglaise ce qui est la version standard tradi tionnelle et que les noms officiels de ces sections sont en r alit dans l ordre NAME SYNOPSIS DESCRIPTION OPTIONS FILES ENVIRONMENT DIAGNOSTICS BUGS AUTHOR et SEE ALSO Donc comment g n rer cette page de manuel J attendais cette question voici le source 3 A quoi ressemble une page de manuel format e Formater ce fichier par la commande groff man Tlatini prout i si vous avez saisi des accents Iso 8859 1 groff man Tascii prout i cas general pAn 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 aB Sas 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
15. les pages de manuel pour qu elles soient affich es plus rapidement La troisi me alternative comporte un pi ge si vous tes concern par la portabilit vous devez savoir qu il existe des syst mes de fichiers qui ne supportent pas les liens symboliques En bref la Meilleure Chose TM est d utiliser le m canisme source de 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 r alisez le fichier bidule 1 contenant S0 mani truc i Il est important de sp cifier le r pertoire man1 aussi bien que le nom du fichier truc 1 car lors de l ex cution de groff celui ci aura comme r pertoire courant le r pertoire de base des pages de manuel et il interpr tera les arguments de S0 comme tant relatifs cet emplacement 5 Quel ensemble de macros utiliser Il y a de nombreux ensembles de macros tudi s sp cialement pour crire des pages de manuel Ils sont habituellement dans le r pertoire de macro de groff usr lib groff tmac Les noms de fichiers sont du genre tmac lt quelque chose gt o lt quelque chose gt est l argument de l option m de groff groff utilisera tmac lt quelque chose gt quand l option m lt quelque chose gt sera donn e Souvent l espace entre m et lt quelque chose gt est oubli on crira donc groff man pour formater des pages de manuel en utilisant l ensemble
16. 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 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 proutre RS Fichier de configuration propre a chaque utilisateur Voir BR prout 5 pour plus de details 4 Comment documenter plusieurs choses dans une seule page de manuel 8 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 so
17. ns de modifier la plupart des programmes makewhatis existants C est bien dommage La section SYNOPSYS est cens e donner un aper u sur les options du programme Pour les fonctions cette section fait la liste des fichiers inclure et son prototype pour que le programmeur connaisse le type et le nombre d arguments ainsi que le type de retour 3 A quoi ressemble une page de manuel format e 6 La section DESCRIPTION Elle explique en d tail pourquoi votre s quence de 0 et de 1 est la meilleure de toutes C est ici que vous talez tout votre savoir Gagnez l estime des autres programmeurs et des utilisateurs en faisant de cette section une source d information s re et d taill e Expliquez quoi servent les arguments le format de fichier les algorithmes qui effectuent le plus dur du travail La section OPTIONS Elle donne une description pour chaque option comment elle affecte le fonctionnement du programme Vous le saviez n est ce pas La section FICHIERS Elle indique les fichiers utilis s par le programme ou la fonction Par exemple les fichiers de configu ration les fichiers de d marrage les fichiers sur lesquels le programme agit Ce serait une bonne id e de donner les chemins absolus de ces fichiers et d avoir un processus d installation qui modifie la partie r pertoire selon les pr f rences de l utilisateur les manuels de groff ont comme pr fixe par d faut usr local donc ils r f rencent
18. ns num riques Attention aux ventuels conflits de noms avec des programmes fonctions ou fichiers d j existants Ce serait certainement une mauvaise id e d crire un autre diteur de texte et de le nommer ed sed pour super ed ou red pour Roger edition En vous assurant que le nom de votre programme est unique vous viterez que quelqu un ex cute votre programme et qu il lise la page de manuel d un autre ou vice verca Vous pouvez ventuellement vous aider de la base de donn es lsm qui recense beaucoup de programmes disponibles pour Linux Maintenant que nous savons quel nom donner notre fichier la prochaine d cision est de choisir le r pertoire dans lequel nous Pinstallerons quand l utilisateur lancera la commande make install Sous Linux toutes les pages de manuel sont dans des sous r pertoires partir d une racine m moris e dans la variable d environnement MANPATH Les outils de traitement de la documentation Putilisent de la m me mani re que le shell utilise la variable PATH pour trouver les ex cutables En fait MANPATH a le m me format que PATH toutes les deux sont une liste de r pertoires s par s par des mais MANPATH n autorise pas de champs vides ou des chemins relatifs seulement des chemins absolus Si MANPATH n existe pas ou si elle n est pas export e usr man est utilis e comme valeur par d faut Dans le but d acc lerer la recherche et pour garder les r pertoires de
19. nt pas supportees dans cette version SH BOGUES Le nom de cette commande aurait du etre choisi de maniere a mieux refleter sa fonction SH AUTEUR Marcel Dugenou lt dugenou renux freenix fr gt SH VOIR AUSSI BR gloup 1 BR plaf 1 BR prout 5 4 Comment documenter plusieurs choses dans une seule page de manuel De nombreux programmes grep egrep et fonctions printf fprintf sont document es dans une seule page de manuel Cependant ces pages seraient inutilisables si elles n taient accessibles que par un seul nom Nous ne pouvous nous attendre ce qu un utilisateur se souviennent que la page de manuel de egrep est en fait celle de grep Il est par cons quent indispensable que la page soit accessible sous diff rents noms Vous avez plusieurs possibilit s 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 m canisme de source de groff fournie par la macro S0 La premi re possibilit est une perte de place La deuxi me n est pas recommand e parce que les versions intelligentes du programme catman peuvent gagner beaucoup de temps en regardant le type du fichier et son 5 Quel ensemble de macros utiliser 9 contenu Les liens physiques r duiraient l efficacit de cet outil dont le but est de formater toutes
20. ore un certain temps e documentation locale propre ce syst me particulier Le nom du fichier source d une page de manuel le fichier d entr e du syst me de formatage est le nom de la commande d crite ou de la fonction du fichier etc suivi d un point et du num ro de section Si par exemple vous documentez le format du fichier passwd vous devez appeler le fichier source passwd 5 Nous avons ici un exemple d un fichier qui porte le m me nom qu une commande nous aurions tout aussi bien avoir une fonction de biblioth que appel e passwd L organisation en sections constitue la m thode habituelle pour r soudre ces ambigu t s la description de la commande se trouvera dans le fichier passwd 1 et notre hypoth tique fonction de biblioth que dans passwd 3 Quelquefois une lettre est ajout e au num ro de section comme par exemple rterm 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 peuvent exploiter cette particularit xman par exemple affichera xterm x et wish tk dans la liste des documents disponibles S il vous pla t n utilisez pas les sections n o et l selon le standard du syst me de fichiers File System Standard ces sections sont d conseill es utilisez plut t les sectio
21. rs 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 lt stdio h gt Les noms des macros qui sont habituellement en majuscules sont en gras B MAXINT Lors de l num ration d une liste de codes d erreurs ces codes sont en gras Cette liste fait g n ralement appel la macro 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 r f rence une autre page de manuel ou la page courante est en gras Si le num ro de la section du manuel est indiqu il s crit en roman sans espace BR man 7 Les acronymes sont plus l gants lorsqu ils apparaissent dans un corps plus petit Je recommande donc SM UNIX SM ASCII SM TAB SM NFS SM LALR 1 9 Comment dois je pr senter ma page de manuel Voil quelques conseils pour rendre votre documentation plus s re plus lisible et plus formatable e 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 e relisez vous corrigez toutes les ventuelles fautes de frappe ou d orthographe fa tes vous relire par un
22. s 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 e la documentation doit tre accessible Si elle est cach e un endroit non standard o les outils de recherche relatifs la documentation ne la trouveront pas comment peut elle remplir son r le e la documentation doit tre fiable et pr cise Il n y a rien de plus irritant qu un programme se comportant diff remment de ce qui est crit dans sa documentation Les utilisateurs vous maudiront vous enverront 2 Comment acc de t on aux pages de manuel 2 e 1 commandes utilisateurs pouvant tre ex cut es par tout le monde e 2 appels syst mes c est dire les fonctions fournies par le noyau e 3 fonctions des biblioth ques e 4 p riph riques c est dire les fichiers sp ciaux que l on trouve dans le r pertoire dev e 5 descriptions des formats de fichiers comme par exemple etc passud e 6 les jeux sans commentaire e 7 divers macros conventions particuli res e 8 outils d administration ex cutables uniquement par le super utilisateur e 9 un autre endroit sp cifique Linux destin la documentation des services offerts par le noyau e n nouvelle documentation qui pourra tre d plac e vers un endroit appropri e o ancienne documentation qui peut tre conserv e enc
23. t e non compact e e l utilisateur ne peut pas g n rer de fichier dvi ou PostScript e quel format de compactage utiliser Z z gz Tous e accessible m me sur les syst mes ne disposant pas de groff DES HN T taille de la distribution plus grande certains syst mes peuvent n cessiter des pages de manuels formatt es et compact es informations redondantes sur les syst mes quip s de groff 8 Quelles sont les conventions pour les fontes 11 A mon avis la meilleure solution est de distribuer uniquement le code source L argument selon lequel la documentation ne pourra pas tre accessible sur les syst mes sans 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 s avec les pages de manuels format es Si un administrateur a besoin que les pages de manuel soient accessibles il aura forc ment install groff 8 Quelles sont les conventions pour les fontes Avant tout n utilisez pas les op rateurs directs de fonte comme fB fP etc Employez des macros avec des arguments Cette m thode vous vitera une erreur classique oublier un changement de fonte la fin d un mot ce qui provoque la con
24. taille raisonable les r pertoires point s dans MANPATH aussi appel s r pertoires de base contiennent une multitude de sous r pertoires nomm s man lt s gt o lt s gt d signe le caract re correspondant la section pr sent plus haut Toutes les sections ne sont pas repr sent es il 3 A quoi ressemble une page de manuel format e 3 n y pas par exemple de raison de garder une entr e mano Vous pourrez y trouver galement des sous r pertoires appel s cat lt s gt dvi lt s gt et ps lt s gt qui contiennent toute la documentation format e pr te tre affich e ou imprim e nous reviendrons sur ce sujet plus loin Le seul fichier tre pr sent c t de ces sous r pertoires du r pertoire de base s appelle whatis Le but et la cr ation de ce fichier sera d crit dans la section 11 La m thode la plus s re pour installer au bon endroit une page de manuel de la section s est de mettre le fichier dans le r pertoire usr man man lt s gt Toutefois un bon Makefile devra autoriser l utilisateur de choisir un autre r pertoire de base disons par exemple par le biais d une variable d environnement que l on pourrait nommer MANDIR La plupart des distributions GNU peuvent tre configur es l aide de l option prefix nom option Les pages de manuels correspondantes seront alors install es partir du r pertoire de base mon option man Je vous su
25. tiers surtout si vous ne r digez pas le texte dans votre langue natale d ailleurs ce HOWTO n a pas t relu Y a t il un volontaire 10 Comment puis je avoir un texte en pur ASCII sans tous ces fichus H de contr le 13 e testez votre page de manuel est ce que groff trouve des erreurs lors du formatage C est agr able de trouver dans un commentaire la ligne de commande qu il faut taper pour le formatage Est ce que la commande man 1 affiche des erreurs ou des avertissements lorsqu on appelle man votre programme Est ce que la fa on dont man 1 utilise le syst me de formatage produit le r sultat escompt Est ce que cela fonctionne aussi bien avec xman 1x et tkman itk XFree86 3 1 contient la version 3 1 6 de xman qui d compacte les pages avec gzip c d lt 4s gt s zcat lt s gt s e 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 le Jetez un oeuil la commande co1 1 col peut enlever ces caract res d effacement Pour les impatients voici la commande groff t e mandoc Tascii manpage i col bx gt manpage txt Les options t et e disent groff d utiliser les pr processeurs tb1 et eqn C est inutile pour les pages de manuel ne n cessitant pas de pr processeur mais cela ne g ne pas si ce n est une surcharge du processeur D un autre c
26. tinuation 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 mac an offrent les possibilit s suivantes e B caract res gras e BI gras et italiques en alternance e BR gras et romain en alternance e I italiques e IB italiques et gras en alternance e IR italiques et romain en alternance e RB romain et gras en alternance e RI romain et italiques en alternance e SM taille r duite 9 10 du corps normal e SB gras taille r duite NON petit et gras en alternance X et Y en alternance signifie que les arguments impairs seront imprim s 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 cessaires pour placer des espaces dans un argument Voil donc pour ce qui est possible Voyons maintenant comment il faut utiliser ces possibilit s des parties ont t honteusement copi es 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 sp cifiques Linux d finit nos standards Pour les fonctions les arguments sont toujours en italiques m me dans la section SYNOPSYS alors que le reste est en gras Vous crirez donc BI mafonction int argc char argv 9 Comment dois je pr senter ma page de manuel 12 Les noms de fichie
27. traiter que le nouveau style de seg ments glurb Les bibliotheques GROBOL ne sont pas supportees dans cette version BOGUES Le nom de cette commande aurait du etre choisi de maniere a mieux refleter sa fonction AUTEUR Marcel Dugenou lt dugenou renux freenix fr gt VOIR AUSSI gloup 1 plaf 1 prout 5 Linux JANVIER 1996 1 Et voici les explications promises La section NAME C est la seule section requise Les pages de manuel sans une section NAME sont aussi utiles que des r frigerateurs au P le Nord Cette section a aussi un format standardis constitu d une liste de programmes ou noms de fonctions s par s par des virgules suivie d un tiret et d une courte description habituellement une ligne de la fonctionnalit que le programme fonction ou fichier est suppos dispenser A l aide de makewhatis 8 les sections NAME sont incluses dans les fichiers de la base de donn es de whatis makewhatis est la raison pour laquelle la section NAME doit exister et pourquoi elle doit adh rer au format que j ai d crit Dans le source groff elle doit ressembler SH NAME prout proutibule de la bibliotheque plaf Le est important ici le backslash sert a faire la diff rence entre le tiret et une marque de c sure qui peut appara tre l int rieur du nom de la commande ou dans la ligne de description Attention en l tat actuel des choses vous ne pouvez pas traduire NAME par NOM en fran ais moi

Man page HOWTO - The Linux Documentation Project

Contents

Download Pdf Manuals

Related Search

Related Contents