pod2manfr - convertit les directives pod vers le format des pages de manuel
pod2manfr [ --section=manext ] [ --release=relpatch ] [ --center=string ] [ --date=string ] [ --fixed=font ] [ --official ] [ --lax ] inputfile
Cet utilitaire est l'adaptation française du programme pod2man. Il en récupère donc toutes les qualités mais aussi tous les défauts...
pod2manfr convertit les directives Pod (voir la page de manuel perlpod) contenues dans le fichier d'entrée en un source nroff compréhensible par nroff(1) ou troff(1) en utilisant
l'ensemble de macros commandes man(7).
En sus des conversions pod imposées, pod2manfr tient aussi compte de func(), func(n) et des références à des variables simples comme $foo ou @bar. Il n'est donc pas nécessaire d'utiliser de directives pod pour cela. Par contre, les
expressions compliquées comme $fred{'stuff'} en ont toujours besoin. pod2manfr fait aussi attention à pleins d'autres petites choses comme convertir correctement le tiret court
dans foo-bar, convertir un double tirets--comme ceux-ci-- en un vrai tiret
long, combiner ``les parenthèse'', ajouter un peu d'espace après des parenthèses comme dans func(), afficher correctement C++ et PI, rendre
les mots EN CAPITALES un petit peu plus petit dans troff(1) et
ajouter le caractère d'échapemment devant les backslashes (\).
Spécifie la chaîne utilisée dans l'en-tête. La valeur par défaut est ``Documentation Perl des Contributions Utilisateurs '' sauf si l'option --official est active. Dans ce cas la valeur par défaut est ``Guide de Références des Programmeurs Perl``.
Spécifie la chaîne apparaîssant dans la partie gauche du pied-de-page. Par défaut, c'est la date de modification du fichier d'entrée qui est utilisée.
La police de taille fixe a utiliser pour le code. Par défaut CW.
Change l'en-tête par défaut pour indiquer que cette page fait partie de la distribution Perl standard (si l'option --center n'est pas utilisée).
Spécifie la chaîne utilisée au centre du pied-de-page. Par défaut, c'est le numéro de la version courante de Perl.
Spécifie la section pour la macro .TH. La convention standard est 1 pour les commandes utilisateurs, 2 pour les
appels systèmes, 3 pour les fonctions, 4 pour les devices, 5 pour les formats de
fichiers, 6 pour les jeux, 7 pour les informations diverses et 8 pour les
commandes d'administration. Ça marche mieux si vous classez les pages de manuel Perl dans une
arborescence séparée comme /usr/local/perl/man/. Par défaut, la section 1 est utilisée à moins que le nom du fichier se termine par .pm auquel cas c'est la section 3 qui est utilisée.
Ne rien dire si les sections obligatoires ne sont pas là.
Voici un exemple du squelette d'une page de manuel correcte. Les titres
principaux sont spécifiés par la directive =head1 et, pour des raisons historiques, sont écrits en CAPITALES bien que ce ne soit pas absolument nécessaire. Les titres secondaires utilisent la directive =head2 et sont habituellement ecrits en mélangeant majuscules et minuscules.
Section obligatoire. Devrait être la liste de noms de programmes ou fonctions documentés dans cette page Pod. Le séparateur est la virgule. Exemple :
foo, bar - programmes pour faire quelque chose
Afin d'accepter les pages de manuels en anglais, pod2manfr accepte aussi NAME.
Un court résumé de l'utilisation de ces programmes ou fonctions (cette section pourrait devenir obligatoire).
Un long discours concernant le programme. C'est une bonne idée de le diviser en plusieurs sous-sections en utilisant la directive =head2. Par exemple :
=head2 Un exemple de sous-section
=head2 Encore un autre exemple de sous-section
Certains les séparent de la description.
Ce que le programme ou les fonctions renvoient normalement comme résultats.
Les exceptions, les codes de retour, les status de sortie et les valeurs de errno.
Quelques exemples d'utilisation du programme.
Les variables d'environnement utilisées part ce programme.
Tous les fichiers utilisés par le programme. Vous aurez certainement besoin de la directive F<>.
Autres pages du manuel à consulter comme man(1), man(7),
makewhatis(8) ou catman(8).
Commentaires divers.
Différentes choses nécessitant une attention particulière.
Tous les messages que le programme est susceptible d'afficher--et leur signification.
Ce qui ne marche pas ou pas très bien.
Les bogues que vous ne comptez pas corriger :-)
Qui a rédigé le document (ou AUTEURS quand ils sont plusieurs).
Les programmes dérivés d'autres sources ont parfois cette section. Vous pouvez aussi y inclure la liste des modifications.
pod2man program > program.1
pod2man some_module.pm > /usr/perl/man/man3/some_module.3
pod2man --section=7 note.pod > note.7
Les diagnostics suivants sont produits par pod2manfr. Les items marqués ``(W)'' ne sont pas fatals alors que les erreurs notées ``(F)'' arrêteront pod2manfr immédiatement avec un statut d'exécution non-nul.
(W) Si vous commencez une nouvelle option, vous devriez ne plus être en gras, en italique ou dans du code.
(F) Le fichier d'entrée n'est pas lisible. Le message d'erreur (du système) en indiquant la raison est affiché.
(W) Le titre NOM ne contient pas de tiret isolé. C'est important.
(F) Vous n'avez pas mis de titre NOM (ou NAME). C'est essentiel.
(F) La police spécifiée par l'option --fixed n'est pas une police roff valide.
(W) Les sections obligatoires sont NOM et DESCRIPTION plus SYNOPSIS si vous spécifiez un numéro de section commençant par 3. Pour l'instant seul l'absence de NOM (ou NAME) est fatale.
(W) Recontre d'une entité HTML inconnue (probablement pour des caractères 8-bit) via la dire4ctive E<>. En plus de amp, lt, gt et quot, les entités reconnues sont Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave,
agrave, Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute,
eacute, Ecirc, ecirc, Egrave, egrave, ETH, eth, Euml, euml, Iacute, iacute,
Icirc, icirc, Igrave, igrave, Iuml, iuml, Ntilde, ntilde, Oacute, oacute,
Ocirc, ocirc, Ograve, ograve, Oslash, oslash, Otilde, otilde, Ouml, ouml,
szlig, THORN, thorn, Uacute, uacute, Ucirc, ucirc, Ugrave, ugrave, Uuml,
uuml, Yacute, yacute, et yuml.
(W) Vous avez un =back sans le =over correspondant.
(W) Vous avez spécifié une directive pod qui ne fait pas partie de la liste des directives
connues: =head1, =head2, =item, =over, =back, ou
=cut.
Si vous voulez imprimer plusieurs pages du manuel de manière continue, vous voudrez probablement utiliser les registres C et D pour
obtenir une numérotation continue et une mise en pages paire/impaire sur certaines versions
de man(7). En utilisant le registre F vous obtiendrez aussi
une indexation expérimentale supplémentaire:
troff -man -rC1 -rD1 -rF1 perl.1 perldata.1 perlsyn.1 ...
L'indexation sortira sûrement des messages via .tm pour chaque page, section, sous-section, item et toutes les directives X<>.
Aucune pour l'instant.
Les directives =over et =back ne marchent pas très bien. Elles utilisent des positions absolues au lieu de décalages relatifs et ne s'imbriquent donc pas très bien.
Prototype original écrit par Larry Wall mais tellement remanié par Tom Christiansen que Larry ne le reconnaîtrait sûrement plus.
Traduction en adaptation française par P.Gaborit (Paul.Gaborit@enstimac.fr)