=encoding iso-8859-1 =head1 NOM perlpod - plain old documentation ("bonne vieille documentation") =head1 DESCRIPTION Un traducteur pod-vers-n'importe quoi lit un fichier pod paragraphe par paragraphe, et le traduit dans le format de sortie approprié. Il existe trois genres de paragraphes : L, L, et L. =head2 Paragraphe Mot pour Mot Un paragraphe mot pout mot (verbatim) est distingué par son indentation (c'est-à-dire qu'il commence par une espace ou une tabulation). Il devrait être reproduit exactement, avec les tabulations supposées être sur 8 colonnes. Il n'y a pas de séquences d'échappement spéciales pour le formatage, vous ne pouvez donc pas mettre en italique ni quoi que ce soit. Un \ veut dire \, et rien d'autre. =head2 Paragraphe de Commande Tous les paragraphes de commande commencent par "=", suivi par un identificateur, suivi par un texte arbitraire que la commande peut utilise de la façon qui lui plaît. Les commandes reconnues actuellement sont =head1 titre =head2 titre =item texte =over N =back =cut =pod =for X =begin X =end X =over 4 =item =pod =item =cut La directive "=pod" ne fait rien d'autre que dire au compilateur de suspendre son analyse du code jusqu'au prochain "=cut". C'est utile pour ajouter un nouveau paragraphe à la doc si vous mélanger beaucoup le code et le pod. =item =head1 =item =head2 Head1 et head2 produisent des titres de premier et de second niveau, avec le texte situé dans le même paragraphe que la directive "=headn" formant la description du titre. =item =over =item =back =item =item Item, over, et back ont besoin d'un peu plus d'explications : "=over" débute une section spécifiquement en vue de la création d'une liste utilisant des commandes "=item". Utilisez "=back" à la fin de votre liste pour la terminer. Vous voudrez probablement donner "4" comme nombre à "=over", car certains formateurs utiliseront ceci pour l'indentation. Ceci devrait probablement être une valeur par défaut. Notez aussi qu'il y a des règles de base dans l'usage de =item : ne les utilisez pas hors d'un bloc =over/=back, utilisez-en au moins un à l'intérieur d'un bloc =over/=back, vous n'êtes pas _obligé_ d'inclure le =back si la liste continue jusqu'à la fin du document, et, ceci étant peut-être le plus important, gardez les items cohérents : utilisez soit "=item *" pour tous, pour produire des puces, ou bien utilisez "=item 1.", "=item 2.", etc., pour produire des listes numérotées, ou bien utilisez "=item foo", "=item bar", etc., i.e., des choses qui n'ont rien à voir avec des puces ou des numéros. Si vous commencez avec des puces ou des numéros, gardez-les, car beaucoup de formateurs utiliseront le type du premier "=item" pour décider comment formater toute la liste. =item =for =item =begin =item =end For, begin, et end vous permettent d'inclure des sections qui ne sont pas interprétées comme du texte pod, mais passées directement à des formateurs particuliers. Un formateur qui peut utiliser ce format traitera la section, qui sera complètement ignorée sinon. La directive "=for" spécifie que la totalité du prochain paragraphe est dans le format indiqué par le premier mot après le "=for", comme ceci : =for html

This is a raw HTML paragraph

La paire de commandes "=begin" et "=end" fonctionne de façon très similaires à "=for", mais au lieu de n'accepter seulement qu'un seul paragraphe, tout le texte depuis le "=begin" jusqu'au paragraphe ayant un "=end" assorti est traité comme d'un format particulier. Voici des exemples de l'utilisation de ceci : =begin html
Figure 1.
=end html =begin text --------------- | foo | | bar | --------------- ^^^^ Figure 1. ^^^^ =end text Certains noms de format que les formateurs sont connus pour accepter actuellement incluent "roff", "man", "latex", "tex", "text", et "html" (certains formateurs traiteront certains de ceux-ci comme des synonymes). Et n'oubliez pas, en utilisant toute commande, que son effet dure jusqu'à la fin du B, pas de la ligne. D'où dans les exemples ci-dessus, les lignes vides que vous pouvez voir après chaque commande pour terminer son paragraphe. Des exemples de listes incluent : =over 4 =item * First item =item * Second item =back =over 4 =item Foo() Description of Foo function =item Bar() Description of Bar function =back =back =head2 Bloc de Texte Ordinaire Il sera plein, et peut-être même justifié. Certaines séquences internes sont reconnues à la fois ici et dans les commandes : I Texte en italique, utilise' pour l'accentuation ou les variables B Texte en gras, utilise' pour les options et les programmes S Le texte contient des espaces insecables C Code litteral L Un lien (reference croisee) vers nom L page de manuel L element dans la page de manuel L section dans une autre page de manuel L<"sec"> section dans cette page de manuel (les guillemets sont optionels) L idem la meme chose que ci-dessus mais seul 'texte' est utilise comme sortie. (Le Texte ne peut pas contenir les caracteres '|' ou '>') L L L L L F Utilise pour les noms de fichier X Une entree d'index Z<> Un caractere de largeur nulle E Un caractere nomme (tres similaire aux sequences d'echappement HTML) E Un < litteral E Un > litteral (Ceux-ci sont optionnels sauf dans d'autres sequences internes et quand ils sont precedes d'une lettre majuscule) E Caractere numero n (probablement en ASCII) E Une entite HTML non numerique, comme E =head2 Le Dessein C'est cela. Le dessein est la simplicité, pas la puissance. Je voulais que les paragraphes aient l'air de paragraphes (format de bloc), pour qu'ils ressortent visuellement, et pour que je puisse les faire passer facilement à travers fmt pour les reformater (c'est F7 dans ma version de B). Je voulais que le traducteur (et pas moi) s'inquiète de savoir si " ou ' est une apostrophe ou un accent grave dans le texte plein, et je voulais qu'il laisse les apostrophe tranquilles, nom d'une pipe, en mode mot pour mot, pour que je puisse l'aspirer dans un programme qui marche, le décaler de 4 espaces, et l'imprimer, euh, mot pour mot. Et probablement dans une fonte à chasse fixe. En particulier, vous pouvez laisser des choses comme ceci mot pour mot dans votre texte : Perl FILEHANDLE $variable function() manpage(3r) Sans doute quelques commandes ou séquences supplémentaires auront besoin d'être ajoutées en cours de route, mais je m'en suis étonnemment bien sorti avec juste celles-ci. Notez que je ne proclame pas du tout que ceci est suffisant pour produire un livre. J'essaye juste de faire une source commune à l'épreuve des idiots pour nroff, TeX, et les autres langages de marquage, tels qu'ils sont utilisés pour la documentation en ligne. Des traducteurs existent pour B (ceci est pour nroff(1) et troff(1)), B, B, B, et B. =head2 Incorporer du Pod dans les Modules Perl Vous pouvez inclure de la documentation pod dans vos scripts Perl. Commencez votre documentation par une commande "=head1" au début, et terminez-la par une commande "=cut". Perl ignorera le texte en pod. Voyez n'importe quel module de bibliothèque fourni comme exemple. Si vous allez mettre votre pod à la fin du fichier, et si vous utilisez un __END__ ou un __DATA__ comme marque de fin, assurez-vous de mettre une ligne vide à cet endroit avant la première directive pod. __END__ =head1 NAME modern - I am a modern module Si vous n'aviez pas eu cette ligne vide à cet endroit, alors les traducteurs ne l'auraient pas vu. =head2 Pièges Courants de Pod =over 4 =item * Les traducteurs Pod requièrent habituellement que les paragraphes soient séparés par des lignes complètement vides. Si vous avez une ligne apparemment vide contenant des espaces, Cela peut provoquer un formatage étrange. =item * Les traducteurs ajouteront généralement des mots autour d'un lien LEE, de façon que Cfoo(1)E> devienne "the I(1) manpage", par exemple (voir B pour des détails). Ainsi, vous ne devriez pas écrire de choses CfooE manpage>, si vous voulez que le document traduit se lise de façon sensée. Si vous nécessitez vraiment ou voulez le contrôle total du texte utilisé pour un lien dans la sortie, utilisez la forme LEshow this text|fooE à la place. =item * Le script F dans la distribution source de Perl procure un squelette de vérification pour les lignes qui ont l'air vide mais ne le sont pas B, mais il y a une place à prendre jusqu'à ce que quelqu'un écrive Pod::Checker. Le meilleur moyen de vérifier votre pod est de le faire passer à travers un ou plusieurs traducteurs et de relire le résultat, ou de l'imprimer et de relire cela. Certains des problèmes trouvés peuvent être des bugs dans le traducteur, que vous pourriez ou non désirer contourner. =back =head1 VOIR AUSSI L and L =head1 AUTEUR Larry Wall =head1 TRADUCTION =head2 Version Cette traduction française correspond à la version anglaise distribuée avec perl 5.005_02. Pour en savoir plus concernant ces traductions, consultez L. =head2 Traducteur Roland Trique (roland.trique@free.fr) =head2 Relecture Personne pour l'instant.