ne peuvent pas contenir les caractères '/' et '|' et les caractères '<' ou '>' doivent pouvoir s'associer. =over =item * CnomE> Lien vers une page de documentation Perl (par exemple CNet::PingE>). Notez que C ne devrait pas contenir d'espaces. Cette syntaxe est aussi utilisé occasionnellement pour faire référence aux pages de manuel UNIX comme dans Ccrontab(5)E>. =item * Cnom/"section"E> ou Cnom/sectionE> Lien vers une section particulière d'une autre page de documentation. Par exemple Cperlsyn/"Boucles for"E>. =item * C/"section"E> ou C/sectionE> ou C"section"E> Lien vers une section particulière de ce même document. Par exemple C/"Méthodes objets"E>. =back Une section débute par un titre ou un item. Par exemple, Cperlvar/$.E> ou Cperlvar/"$."E> seront tous deux liés à la section qui débute par C<=item $.> dans perlvar. Et Cperlsyn/Boucles forE> ou Cperlsyn/"Boucles for"E> sont tous deux liés à la section débutant par C<=head2 Boucle for>" dans perlsyn. Pour contrôler le texte affiché comme lien, vous pouvez utiliser Ctexte|...E> comme S =over =item * Ctexte|nomE> Lié ce texte à la page de documentation dont le nom est fourni. Par exemple CMessages d'erreurs de Perl|perldiagE>. =item * Ctexte|nom/"section"E> ou Ctexte|nom/sectionE> Lié ce texte à la section de la page de documentation dont le nom est fourni. Par exemple CInstructions SWITCH|perlsyn/"BLOCs de base et instruction switch"E>. =item * Ctexte|/"section"E> or Ctexte|/sectionE> ou Ctexte|"section"E> Lié ce texte à la section de ce même document. Par exemple Cles différents attributs|/"Données membres"E> =back Ou vous pouvez lier une page S =over =item * Cscheme:...E> Lien vers un URL absolu. Par exemple Chttp://www.perl.org/E>. Mais notez que, pour différentes raisons, il n'existe pas de syntaxe du genre Ctext|scheme:...E>. =back =item CentitéE> -- un caractère nommé X X<< EZ<><> >> X X Très similaire aux S<« entités »> HTML/XML C<&I;>. =over =item * CltE> -- un E littéral (plus petit que) =item * CgtE> -- un E littéral (plus grand que) =item * CverbarE> -- un | littéral | (Ire Iticale) =item * CsolE> -- un / littéral (barre oblique) =back Les quatre codes ci-dessus sont optionnels sauf s'ils sont utilisés à l'intérieur d'un autre de code de mise en forme, en particulier C...E> ou lorsqu'ils sont directement précédés d'une lettre majuscule. =over =item * ChtmlentitéE> Quelques entités HTML non numériques telle que CeacuteE>, qui signifie la même chose que C<é> en HTML -- c.-à-d. un e minuscule avec un accent aigu. =item * CnombreE> Le caractère ASCII/Latin-1/Unicode dont le code est le nombre. Le préfixe "0x" indique que I est en hexadécimal comme dans C0x201EE>. Le préfixe "0" indique que le nombre est en octal comme dans C075E>. Sinon, le I est considéré en décimal comme dans C181E>. Notez que les vieux traducteurs Pod peuvent ne pas reconnaitre l'octal et l'hexadécimal et que de nombreux traducteurs ne savent pas présenter correctement les caractères dont le code est supérieur à 255. (Certains traducteurs peuvent même choisir un compromis pour présenter les caractères Latin-1, en présentant un simple "e" à la place de CeacuteE>.) =back =item CnomfichierE> -- utilisé pour un nom de fichier X X<< FZ<><> >> X X Typiquement affiché en italique. S C.cshrcE> =item CtexteE> -- texte contenant des espaces non sécables X X<< SZ<><> >> X X Cela siginifie que les mots du I ne doivent pas être séparés sur plusieurs lignes. S S$x ? $y : $zE>>. =item Cnom de sujetE> -- une point d'entrée d'index X X<< XZ<><> >> X X Ce code est ignoré par la plupart des traducteurs mais certains peuvent l'utiliser pour construire un index. Il est toujours présenté comme la chaîne vide. S CURL absoluE> =item CE> -- un code de mise en forme nul (sans effet) X X<< ZZ<><> >> X X C'est rarement utilisé. C'est l'un des moyens pour empêcher l'inteprétation d'un code EE...E. Par exemple, à la place de "CltE3>" (pour "NE3"), vous pourriez écrire "CEE3>" (le code "ZEE" sépare le "N" et le "E" afin qu'ils ne soient pas considérés comme le début d'une (hypothétique) séquence "NE...E"). =begin comment This was formerly explained as a "zero-width character". But it in most parser models, it parses to nothing at all, as opposed to parsing as if it were a E or E, which are REAL zero-width characters. So "width" and "character" are exactly the wrong words. =end comment =back La plupart du temps, un simple couple inférieur/supérieur suffira pour délimiter le début et la fin de votre code de mise en forme. Mais il se peut que vous ayez besoin de placer un symbole supérieur (un signe S<« plus> grand S, '>') dans un code de mise en forme. C'est très courant lorsqu'on souhaite présenter un extrait de code avec une police différente du reste du texte. Comme d'habitude en Perl, il y a plusieurs moyens pour le faire. Le premier consiste tout simplement à utiliser l'entité S<« plus> grand S via le code de mise en forme S :> C<$a E=E $b> Ce qui S C<$a E=E $b>. Un moyen plus lisible et probablement plus "brut" est d'utiliser de délimiteurs qui n'imposent pas de codage spécial pour un simple ">". Les traducteurs Pod proposent cela en standard depuis perl 5.5.660 via les doubles délimiteurs ("<<" et ">>") qui peuvent être utilisés I>. Par S X C<< $a <=> $b >> En fait, vous pouvez utiliser le nombre d'inférieurs et de supérieurs que vous souhaitez tant qu'il y en a autant dans le délimiteur ouvrant que dans le délimiteur fermant et si vous vous assurez qu'un espace suit immédiatement le dernier S<< « < » >> du délimiteur ouvrant et qu'un autre espace précède immédiatement le premier S<< « > » >> du délimiteur fermant (ces espaces seront ignorés). Les exemples suivants fonctionneront donc S X C<<< $a <=> $b >>> C<<<< $a <=> $b >>>> Et ils signifient exactement la même chose S C<$a E=E $b> Prenons un autre S supposons que vous voulez présenter l'extrait de code suivant dans un style C<< CZ<><> >> (code)E: open(X, ">>thing.dat") || die $! $foo->bar(); Vous pourrez le faire comme S C<<< open(X, ">>thing.dat") || die $! >>> C<< $foo->bar(); >> qui est certainement plus facilement lisible que l'ancien S CEthing.dat") || die $!> C<$foo-Ebar();> Tout cela est actuellement accepté par pod2text (Pod::Text), pod2man (Pod::Man) et tout autre traducteur pod2xxx et Pod::Xxxx qui utilise Pod::Parser version 1.093 ou supérieure. =head2 L'objectif X L'objectif est la simplicité d'utilisation, pas la puissance expressive. Les paragraphes ont l'air de paragraphes (des blocs) pour qu'ils ressortent visuellement, et on peut les faire passer facilement à travers C pour les reformater (c'est F7 dans ma version de B ou Esc-Q dans ma version de B). Je voulais que le traducteur laisse les C<'>, les C<`> et les C<"> tranquilles en mode verbatim pour que je puisse copier/coller ces paragraphes dans un programme qui marche, les décaler de 4 espaces, et l'imprimer, euh, mot pour mot. Et probablement dans une fonte à chasse fixe. Le format Pod est certainement insuffisant pour rédiger un livre. Pod essaie juste d'être un format infaillible qui puisse servir de source pour nroff, HTML, TeX et autres langages de balises, lorsqu'ils sont utilisés pour de la documentation en ligne. Des traducteurs existent pour B, B, B (c'est pour nroff(1) et troff(1)), B et B. D'autres encore sont disponibles sur CPAN. =head2 Incorporer du Pod dans les modules Perl Vous pouvez inclure de la documentation Pod dans vos scripts et vos modules Perl. Commencez votre documentation par une ligne vide puis une commande S<« =head1 »> et terminez-la par une commande S<« =cut »> et une ligne vide. Perl ignorera le texte en Pod. Regardez n'importe lequel des modules fournis en standard pour vous servir d'exemple. Si vous souhaitez 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 avant votre première commande Pod. __END__ =head1 NAME Time::Local - efficiently compute time from local and GMT time Sans cette ligne vide avant C<=head1>, de nombreux traducteurs ne reconnaitront pas C<=head1> comme le début d'une section Pod. =head2 Conseils pour écrire en Pod =over =item * X X X La commande B permet de vérifier le respect de la syntaxe Pod. Par exemple, elle vérifie les lignes entièrement blanches dans les sections Pod ou les commandes et les codes de mise en forme inconnus. Vous pouvez aussi passer votre document au travers d'un ou plusieurs traducteurs Pod et vérifier le résultat (en l'imprimant si besoin est). Certains problèmes rencontrés peuvent être liés à des bogues des traducteurs. À vous de décider si vous voulez les contourner ou non. =item * Si vous êtes plus à votre aise en rédigeant du HTML que du Pod, vous pouvez rédiger votre documentation en HTML simple puis la convertir en Pod grâce au module expérimental L (disponible sur CPAN) et enfin vérifier le code obtenu. Le module expérimental L peut aussi être utile. =item * De nombreux traducteurs Pod ont absolument besoin d'une ligne blanche avant et après chaque commande Pod (commande =cut y compris). Quelque chose comme S<ça :> # - - - - - - - - - - - - =item $firecracker->boom() This noisily detonates the firecracker object. =cut sub boom { ... ...amènera ces traducteurs Pod à ignorer totalement la section Pod. À la place, préférez quelque chose comme S # - - - - - - - - - - - - =item $firecracker->boom() This noisily detonates the firecracker object. =cut sub boom { ... =item * Certains traducteurs Pod anciens ont absolument besoin de paragraphes (incluant les paragraphes de commande comme "=head2 Fonctions") séparés par des lignes I vides. Si vous avez des lignes apparament vides mais contenant en fait des espaces, elles ne seront pas reconnues comme séparateurs par ces traducteurs et provoqueront peut-être de mauvaises mises en forme. =item * Des traducteurs Pod anciens ajoutent quelques mots autour de certains liens LEE de telle manière que CFoo::BarE> deviendra par exemple "the Foo::Bar manpage". Vous ne pouvez donc pas écrire des choses telles que CbiduleE> si vous voulez que le résultat reste compréhensible. À la place, écrivez Cbidule|biduleE> ou C<< LEla documentation >> C<< bidule|biduleE >> pour contrôler l'apparence du lien. =item * Un texte qui dépasse la 70e colonne dans un bloc verbatim peut être arbitrairement coupé par certains traducteurs. =back =head1 VOIR AUSSI L, L, L, L, L, L, L. =head1 AUTEUR Larry Wall, Sean M. Burke =head1 TRADUCTION =head2 Version Cette traduction française correspond à la version anglaise distribuée avec perl 5.8.8. Pour en savoir plus concernant ces traductions, consultez L. =head2 Traducteur Traduction S Roland Trique >. Mise à S Paul Gaborit . =head2 Relecture Gérard Delafond =cut