.\" Automatically generated by Pod::Man 2.09 (Pod::Simple 3.04)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PERLPOD 1"
.TH PERLPOD 1 "2006-04-13" "DocFr" "User Contributed Perl Documentation"
.SH "NAME/NOM"
.IX Xref "POD plain old documentation bonne vieille documentation"
.IX Header "NAME/NOM"
perlpod \- Le format Pod (plain old documentation), la bonne vieille documentation
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Pod est un langage de balise, simple a\*` utiliser pour e\*'crire de la
documentation pour Perl lui\-me\*^me ainsi que pour les programmes Perl et
les modules Perl.
.PP
Des traducteurs existent pour convertir le Pod vers diffe\*'rents formats
comme le texte brut, le \s-1HTML\s0, les pages man et d'autres encore.
.PP
Le langage Pod reconnait a\*` la base trois sortes de paragraphes\ :
les paragraphes ordinaires, les
paragraphes de commande et les
paragraphes verbatim.
.Sh "Les paragraphes ordinaires"
.IX Xref "POD, paragraphes ordinaires"
.IX Subsection "Les paragraphes ordinaires"
La plupart des paragraphes d'une documentation sont des blocs de texte
ordinaires, comme celui\-ci. Il vous suffit de taper votre texte sans
aucune marque particulie\*`re et avec une ligne vide avant et
apre\*`s. Lorsqu'il sera formate\*', ce bloc subira une mise en forme
minimale comme un rede\*'coupage des lignes, problablement e\*'crites dans
une police a\*` espacement proportionnelle, qui seront sans doute
justifie\*'es.
.PP
Dans les paragraphes ordinaires, vous pouvez utiliser des codes de
mise en forme pour le \fBgras\fR, l'\fIitalique\fR, le style \f(CW\*(C`code\*(C'\fR, les
liens et autres. Ces codes sont explique\*'s dans la section
Codes de mise en forme, ci\-dessous.
.Sh "Les paragraphes verbatim"
.IX Xref "POD, paragraphes verbatim POD, paragraphes mot pour mot verbatim"
.IX Subsection "Les paragraphes verbatim"
Les paragraphes verbatim (mot pout mot) sont habituellement utilise\*'s
pour pre\*'senter des blocs de code ou d'autres bouts de texte qui ne
requie\*`rent aucune analyse, aucune mise en forme particulie\*`re et dont
les lignes ne doivent pas e\*^tre rede\*'coupe\*'es.
.PP
Un paragraphe verbatim se distingue par son premier caracte\*`re qui doit
e\*^tre un espace ou une tabulation. (Et habituellement, chacune de ses
lignes commence par des espaces ou des tabulations.) Il devrait e\*^tre
reproduit a\*` l'identique, en supposant que les tabulations sont
aligne\*'es sur 8 caracte\*`res. Il n'existe aucun code de mise en forme et,
par conse\*'quent, aucune possibilite\*' de faire de l'italique ou quoi que
ce soit d'autre. Un \e est \e et rien d'autre.
.Sh "Les paragraphes de commande"
.IX Xref "POD, commande"
.IX Subsection "Les paragraphes de commande"
Un paragraphe de commande est utilise\*' pour spe\*'cifier des traitements
spe\*'ciaux sur des parties du texte comme les titres ou les listes.
.PP
Tous les paragraphes de commande (qui ne font habituellement qu'une
seule ligne) commencent par le caracte\*`re X\ =\ X, suivi d'un
identificateur, suivi d'un texte arbitraire que la commande peut
utiliser de la fac\*,on qui lui plai\*^t.  Les commandes actuellement
reconnues sont
.PP
.Vb 10
\&  =pod
\&  =head1 titre
\&  =head2 titre
\&  =head3 titre
\&  =head4 titre
\&  =over niveauindentation
\&  =item texte
\&  =back
\&  =beagin format
\&  =end format
\&  =for format
\&  =encoding type
\&  =cut
.Ve
.PP
Voici en de\*'tail des explications pour chacune d'elles\ :
.ie n .IP """=head1 \f(CITexte du titre\f(CW""" 4
.el .IP "\f(CW=head1 \f(CITexte du titre\f(CW\fR" 4
.IX Xref "=head1 =head2 =head3 =head4 head1 head2 head3 head4"
.IX Item "=head1 Texte du titre"
.PD 0
.ie n .IP """=head2 \f(CITexte du titre\f(CW""" 4
.el .IP "\f(CW=head2 \f(CITexte du titre\f(CW\fR" 4
.IX Item "=head2 Texte du titre"
.ie n .IP """=head3 \f(CITexte du titre\f(CW""" 4
.el .IP "\f(CW=head3 \f(CITexte du titre\f(CW\fR" 4
.IX Item "=head3 Texte du titre"
.ie n .IP """=head4 \f(CITexte du titre\f(CW""" 4
.el .IP "\f(CW=head4 \f(CITexte du titre\f(CW\fR" 4
.IX Item "=head4 Texte du titre"
.PD
Les commandes head1 a\*` head4 produisent des titres et head1 est le
titre de plus haut niveau. Le texte qui suit la commande et qui
constitue le reste du paragraphe est le contenu du titre. Par
exemple\ :
.Sp
.Vb 1
\&  =head2 Attributs des objets
.Ve
.Sp
Le texte \*(L"Attributs des objets\*(R" est ici le titre. (Notez que les
niveaux head3 et head4 sont des ajouts re\*'cents qui ne seront pas
reconnus par de vieux traducteurs de Pod.) Le texte du titre peut
utiliser des codes de mise en forme comme dans\ :
.Sp
.Vb 1
\&  =head2 Valeurs possibles pour C<$/>
.Ve
.Sp
Ces codes sont explique\*'s dans la section Codes de mise en
forme, ci\-dessous.
.ie n .IP """=over \f(CIniveauindentation\f(CW""" 4
.el .IP "\f(CW=over \f(CIniveauindentation\f(CW\fR" 4
.IX Xref "=over =item =back over item back"
.IX Item "=over niveauindentation"
.PD 0
.ie n .IP """=item \f(CItexte...\f(CW""" 4
.el .IP "\f(CW=item \f(CItexte...\f(CW\fR" 4
.IX Item "=item texte..."
.ie n .IP """=back""" 4
.el .IP "\f(CW=back\fR" 4
.IX Item "=back"
.PD
Les commandes item, over, et back ont besoin d'un peu plus
d'explications\ : X\ =over\ X de\*'bute une section destine\*'e a\*` cre\*'er
une liste utilisant des commandes X\ =item\ X, ou pour indenter un ou
plusieurs paragraphes normaux.  Utilisez X\ =back\ X a\*` la fin de
votre liste ou de votre groupe de paragraphes. L'option
\&\fIniveauindentation\fR de X\ =over\ X indique le niveau d'indentation,
ge\*'ne\*'ralement mesure\*' en em (ou\*` un em est la largeur d'un M de la police
de base du document) ou en une unite\*' comparable. Si l'option
\&\fIniveauindentation\fR est omise, sa valeur par de\*'faut est quatre. (Et
certains traducteurs ignoreront cette valeur quelle qu'elle soit.) 
Dans le \fItexte\fR de \f(CW\*(C`=item texte...\*(C'\fR vous pouvez utiliser des
codes de mise en forme comme par exemple\ :
.Sp
.Vb 1
\&  =item Utilisation de C<$|> pour contro\*^ler l'usage des tampons
.Ve
.Sp
Ces codes sont explique\*'s dans la section Codes de mise en
forme, ci\-dessous.
.Sp
Notez aussi les quelques re\*`gles basiques suivantes pour bien utiliser
les sections X\ =over\ X ... X\ =back\ X\ :
.RS 4
.IP "\(bu" 4
N'utilisez pas X\ =item\ X en dehors d'une section X\ =over\ X
\&... X\ =back\ X.
.IP "\(bu" 4
La premie\*`re chose qui suit une commande X\ =over\ X devrait e\*^tre une
commande X\ =item\ X, sauf s'il n'y a vraiment aucun item dans cette
section X\ =over\ X ... X\ =back\ X.
.IP "\(bu" 4
N'utilisez pas de commande X\ =head\fIn\fR\ X dans une section X\ =over\ X ... X\ =back\ X.
.IP "\(bu" 4
Et, sans doute le plus important, utilisez des items cohe\*'rents entre
eux\ : soit ce sont tous des X\ =item\ *\ X pour produire une liste
a\*` puces\ ; soit ils sont tous de la forme X\ =item\ 1\ X, X\ =item\ 2\ X, etc. pour produire une liste nume\*'rote\*'e\ ; soit ils sont tous
de la forme X\ =item\ truc\ X, X\ =item\ bidule\ X, etc. pour produire
une liste de de\*'finitions.
.Sp
Si vous commencez par une puce ou par un nume\*'ro, continuez de me\*^me,
puisque les traducteurs se basent sur le premier X\ =item\ X pour
choisir le type de liste.
.RE
.RS 4
.RE
.ie n .IP """=cut""" 4
.el .IP "\f(CW=cut\fR" 4
.IX Xref "=cut cut"
.IX Item "=cut"
Pour terminer un bloc Pod, utilisez une ligne vide puis une ligne
commenc\*,ant par \f(CW\*(C`=cut\*(C'\fR puis encore une ligne vide. Ceci informe Perl
(et les traducteurs Pod) que c'est a\*` cet endroit que le code Perl
recommence. (La ligne vide avant le \f(CW\*(C`=cut\*(C'\fR n'est pas techniquement
indispensable mais beaucoup de vieux traducteurs Pod en ont besoin.)
.ie n .IP """=pod""" 4
.el .IP "\f(CW=pod\fR" 4
.IX Xref "=pod pod"
.IX Item "=pod"
La commande \f(CW\*(C`=pod\*(C'\fR en elle\-me\*^me ne sert pas a\*` grand chose si ce n'est
de signaler a\*` Perl (et aux traducteurs Pod) qu'une section Pod
commence a\*` cet endroit. Une section Pod peut commencer par
\&\fIn'importe\fR quel paragraphe de commande. Une commande \f(CW\*(C`=pod\*(C'\fR ne sert
donc qu'a\*` indiquer une section Pod qui de\*'bute directement par un
paragraphe ordinaire ou un paragraphe verbatim. Par exemple\ :
.Sp
.Vb 1
\&  =item trucs()
\&
\&  Cette fonction fait des trucs.
\&
\&  =cut
\&
\&  sub trucs {
\&    ...
\&  }
\&
\&  =pod
\&
\&  Souvenez\-vous de ve\*'rifier son S<re\*'sultat :>
\&
\&    trucs() || die "Ne peux pas faire des trucs !";
\&
\&  =cut
.Ve
.ie n .IP """=begin \f(CInomformat\f(CW""" 4
.el .IP "\f(CW=begin \f(CInomformat\f(CW\fR" 4
.IX Xref "=begin =end =for begin end for"
.IX Item "=begin nomformat"
.PD 0
.ie n .IP """=end \f(CInomformat\f(CW""" 4
.el .IP "\f(CW=end \f(CInomformat\f(CW\fR" 4
.IX Item "=end nomformat"
.ie n .IP """=for \f(CInomformat\f(CW \f(CItexte...\f(CW""" 4
.el .IP "\f(CW=for \f(CInomformat\f(CW \f(CItexte...\f(CW\fR" 4
.IX Item "=for nomformat texte..."
.PD
Les commandes for, begin et end vous permettent d'utiliser des
sections de texte/code/donne\*'e qui ne seront pas interpre\*'te\*'es comme du
Pod normal mais qui pourront e\*^tre utilise\*'es directement par des
traducteurs spe\*'cifiques ou qui pourront avoir un usage spe\*'cial. Seuls
les traducteurs qui savent comment utiliser le format spe\*'cifie\*'
utiliseront cette section.  Sinon elle sera comple\*`tement ignore\*'e.
.Sp
Une commande X=begin\ \fInomformat\fRX puis quelques paragraphes et
enfin une commande X=end\ \fInomformat\fRX signifie que les paragraphes
inclus sont re\*'serve\*'s aux traducteurs comprenant le format spe\*'cial
appele\*' \fInomformat\fR. Par exemple\ :
.Sp
.Vb 1
\&  =begin html
\&
\&  <hr> <img src="thang.png">
\&  <p>Ceci est un paragraphe HTML</p>
\&
\&  =end html
.Ve
.Sp
La commande X\ =for\ \fInomformat\fR\ \fItexte...\fR\ X indique que c'est
uniquement ce paragraphe (le \fItexte\fR qui est juste apre\*`s
\&\fInomformat\fR) qui est dans ce format spe\*'cial.
.Sp
.Vb 2
\&  =for html <hr> <img src="thang.png">
\&  <p>Ceci est un paragraphe HTML</p>
.Ve
.Sp
Les deux exemples ci-dessus produiront le me\*^me re\*'sultat.
.Sp
La diffe\*'rence est qu'avec X\ =for\ X, seul le paragraphe est concerne\*'
alors qu'entre le couple X\ =begin\ format\ X ... X\ =end\ format\ X,
vous pouvez placer autant de contenu que ne\*'cessaire. (Notez que les
lignes vides apre\*`s la commande =begin et avant la commande =end sont
requises.)
.Sp
Voici des exemples de l'utilisation de ceci\ :
.Sp
.Vb 1
\& =begin html
\&
\& <br>Figure 1.<IMG SRC="figure1.png"><br>
\&
\& =end html
\&
\& =begin text
\&
\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&   |  foo        |
\&   |        bar  |
\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&
\& ^^^^ Figure 1. ^^^^
\&
\& =end text
.Ve
.Sp
Parmi les noms de format actuellement connus pour e\*^tre reconnus par
les formateurs, on trouve X\ roff\ X, X\ man\ X, X\ latex\ X, X\ tex\ X, X\ text\ X et X\ html\ X. (Des traducteurs Pod peuvent en
conside\*'rer certains comme synonymes.)
.Sp
Le nom de format X\ comment\ X est pratique pour placer des notes
(juste pour vous) qui n'apparai\*^tront dans aucune version mise en forme
de la documentation Pod\ :
.Sp
.Vb 2
\&  =for comment
\&  S'assurer que toutes les options sont documente\*'es !
.Ve
.Sp
Quelques \fInomformat\fRs utilisent le pre\*'fixe \f(CW\*(C`:\*(C'\fR (comme par exemple
\&\f(CW\*(C`=for :nomformat\*(C'\fR ou \f(CW\*(C`=begin :nomformat\*(C'\fR ... \f(CW\*(C`=end :nomformat\*(C'\fR)
pour indiquer que le texte ne doit pas e\*^tre conside\*'re\*' comme brut mais
qu'il contient en fait du texte Pod (c.\-a\*`\-d. contenant e\*'ventuellement
des codes de mise en forme) qui n'est pas a\*` utiliser pour une mise
forme normale (c.\-a\*`\-d. qui n'est pas un paragraphe normal mais
pourrait e\*^tre utilise\*', par exemple, comme note de bas de page).
.ie n .IP """=encoding \f(CIcodage\f(CW""" 4
.el .IP "\f(CW=encoding \f(CIcodage\f(CW\fR" 4
.IX Xref "=encoding encoding codage"
.IX Item "=encoding codage"
Cette commande permet de de\*'clarer le codage utilise\*' dans le
document. La plupart des utilisateurs n'en ont pas besoin ; mais si
votre encodage n'est pas US-ASCII ou Latin\-1 alors indiquez-le aux
traducteurs Pod en plac\*,ant une commande \f(CW\*(C`=encoding \f(CIcodage\f(CW\*(C'\fR le plus
to\*^t possible dans le document. Comme \fIcodage\fR, utilisez l'un des noms
reconnus par le module \f(CW\*(C`Encode::Supported\*(C'\fR. Exemples\ :
.Sp
.Vb 1
\&  =encoding utf8
\&
\&  =encoding koi8\-r
\&
\&  =encoding ShiftJIS
\&
\&  =encoding big5
.Ve
.PP
N'oubliez pas, en utilisant une commande, que cette commande se
termine a\*` la fin de son \fIparagraphe\fR, pas a\*` la fin de sa ligne. D'ou\*`
dans les exemples ci\-dessus, les lignes vides que vous pouvez voir
apre\*`s chaque commande pour terminer son paragraphe.
.PP
Quelques exemples de listes\ :
.PP
.Vb 1
\& =over
\&
\& =item *
\&
\& Premier item
\&
\& =item *
\&
\& Second item
\&
\& =back
\&
\& =over 
\&
\& =item Foo()
\&
\& Description de la fonction Foo
\&
\& =item Bar()
\&
\& Description de la fonction Bar
\&
\& =back
.Ve
.Sh "Codes de mise en forme"
.IX Xref "POD, code de mise en forme code de mise en forme POD, se\*'quence interne se\*'quence interne"
.IX Subsection "Codes de mise en forme"
Dans les paragraphes ordinaires et dans certains paragraphes de
commande, plusieurs codes de mise en forme (appele\*'s aussi X\ se\*'quences internesX) peuvent e\*^tre utilise\*'s\ :
.ie n .IP """I<texte>"" \*(-- texte en italique" 4
.el .IP "\f(CWI<texte>\fR \*(-- texte en italique" 4
.IX Xref "I I<> POD, code de mise en forme, italique italique"
.IX Item "I<texte>  texte en italique"
Utilise\*' pour mettre en e\*'vidence (\f(CW\*(C`faites I<attention !>\*(C'\fR) et
pour les parame\*`tres (\f(CW\*(C`redo I<LABEL>\*(C'\fR).
.ie n .IP """B<texte>"" \*(-- texte en gras" 4
.el .IP "\f(CWB<texte>\fR \*(-- texte en gras" 4
.IX Item "B<texte>  texte en gras"

.IX Xref "B B<> POD, code de mise en forme, gras gras"
.Sp
Utilise\*' pour les options (\f(CW\*(C`l'option B<\-n> de perl\*(C'\fR), pour les
programmes (\f(CW\*(C`certains syste\*`mes proposent B<chfn> pour c\*,a\*(C'\fR),
pour mettre en e\*'vidence (\f(CW\*(C`faites B<attention !>\*(C'\fR) et autres
(\f(CW\*(C`cette proprie\*'te\*' s'appelle B<l'autovivification>\*(C'\fR).
.ie n .IP """C<code>"" \*(-- du code" 4
.el .IP "\f(CWC<code>\fR \*(-- du code" 4
.IX Xref "C C<> POD, code de mise en forme, code code"
.IX Item "C<code>  du code"
Pre\*'sente le code dans une police type machine a\*` e\*'crire ou donne une
indication que le texte est un programme (\f(CW\*(C`C<gmtime($^T)>\*(C'\fR)
ou quelque chose lie\*'e a\*` l'ordinateur (\f(CW\*(C`C<drwxr\-xr\-x>\*(C'\fR).
.ie n .IP """L<nom>"" \*(-- un hyperlien" 4
.el .IP "\f(CWL<nom>\fR \*(-- un hyperlien" 4
.IX Xref "L L<> POD, code de mise en forme, hyperlien hyperlien"
.IX Item "L<nom>  un hyperlien"
Il y a diffe\*'rentes syntaxes, pre\*'sente\*'es ci\-dessous. Dans ces syntaxes,
\&\f(CW\*(C`texte\*(C'\fR, \f(CW\*(C`nom\*(C'\fR et \f(CW\*(C`section\*(C'\fR ne peuvent pas contenir les caracte\*`res
\&'/' et '|' et les caracte\*`res '<' ou '>' doivent pouvoir s'associer.
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`L<nom>\*(C'\fR
.Sp
Lien vers une page de documentation Perl (par exemple
\&\f(CW\*(C`L<Net::Ping>\*(C'\fR).  Notez que \f(CW\*(C`nom\*(C'\fR ne devrait pas contenir
d'espaces. Cette syntaxe est aussi utilise\*' occasionnellement pour
faire re\*'fe\*'rence aux pages de manuel \s-1UNIX\s0 comme dans
\&\f(CW\*(C`L<crontab(5)>\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`L<nom/"section">\*(C'\fR ou \f(CW\*(C`L<nom/section>\*(C'\fR
.Sp
Lien vers une section particulie\*`re d'une autre page de
documentation. Par exemple \f(CW\*(C`L<perlsyn/"Boucles for">\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`L</"section">\*(C'\fR ou \f(CW\*(C`L</section>\*(C'\fR ou \f(CW\*(C`L<"section">\*(C'\fR
.Sp
Lien vers une section particulie\*`re de ce me\*^me document. Par exemple
\&\f(CW\*(C`L</"Me\*'thodes objets">\*(C'\fR.
.RE
.RS 4
.Sp
Une section de\*'bute par un titre ou un item. Par exemple,
\&\f(CW\*(C`L<perlvar/$.>\*(C'\fR ou \f(CW\*(C`L<perlvar/"$.">\*(C'\fR seront tous
deux lie\*'s a\*` la section qui de\*'bute par \f(CW\*(C`=item $.\*(C'\fR dans perlvar. Et
\&\f(CW\*(C`L<perlsyn/Boucles for>\*(C'\fR ou \f(CW\*(C`L<perlsyn/"Boucles
for">\*(C'\fR sont tous deux lie\*'s a\*` la section de\*'butant par \f(CW\*(C`=head2
Boucle for\*(C'\fR" dans perlsyn.
.Sp
Pour contro\*^ler le texte affiche\*' comme lien, vous pouvez utiliser
\&\f(CW\*(C`L<texte|...>\*(C'\fR comme dans\ :
.IP "\(bu" 4
\&\f(CW\*(C`L<texte|nom>\*(C'\fR
.Sp
Lie\*' ce texte a\*` la page de documentation dont le nom est fourni. Par
exemple \f(CW\*(C`L<Messages d'erreurs de Perl|perldiag>\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`L<texte|nom/"section">\*(C'\fR ou \f(CW\*(C`L<texte|nom/section>\*(C'\fR
.Sp
Lie\*' ce texte a\*` la section de la page de documentation dont le nom est
fourni. Par exemple \f(CW\*(C`L<Instructions SWITCH|perlsyn/"BLOCs de base
et instruction switch">\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`L<texte|/"section">\*(C'\fR or \f(CW\*(C`L<texte|/section>\*(C'\fR ou \f(CW\*(C`L<texte|"section">\*(C'\fR
.Sp
Lie\*' ce texte a\*` la section de ce me\*^me document. Par exemple \f(CW\*(C`L<les
diffe\*'rents attributs|/"Donne\*'es membres">\*(C'\fR
.RE
.RS 4
.Sp
Ou vous pouvez lier une page web\ :
.IP "\(bu" 4
\&\f(CW\*(C`L<scheme:...>\*(C'\fR
.Sp
Lien vers un \s-1URL\s0 absolu. Par exemple
\&\f(CW\*(C`L<http://www.perl.org/>\*(C'\fR. Mais notez que, pour diffe\*'rentes
raisons, il n'existe pas de syntaxe du genre
\&\f(CW\*(C`L<text|scheme:...>\*(C'\fR.
.RE
.RS 4
.RE
.ie n .IP """E<entite\*'>"" \*(-- un caracte\*`re nomme\*'" 4
.el .IP "\f(CWE<entite\*'>\fR \*(-- un caracte\*`re nomme\*'" 4
.IX Xref "E E<> POD, formatting code, entite\*' entite\*'"
.IX Item "E<entite'>  un caracte`re nomme'"
Tre\*`s similaire aux X\ entite\*'s\ X \s-1HTML/XML\s0 \f(CW\*(C`&\f(CIfoo\f(CW;\*(C'\fR.
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`E<lt>\*(C'\fR \*(-- un < litte\*'ral (plus petit que)
.IP "\(bu" 4
\&\f(CW\*(C`E<gt>\*(C'\fR \*(-- un  > litte\*'ral (plus grand que)
.IP "\(bu" 4
\&\f(CW\*(C`E<verbar>\*(C'\fR \*(-- un | litte\*'ral | (\fIbar\fRre \fIver\fRticale)
.IP "\(bu" 4
\&\f(CW\*(C`E<sol>\*(C'\fR \*(-- un / litte\*'ral (barre oblique)
.RE
.RS 4
.Sp
Les quatre codes ci-dessus sont optionnels sauf s'ils sont utilise\*'s a\*`
l'inte\*'rieur d'un autre de code de mise en forme, en particulier
\&\f(CW\*(C`L<...>\*(C'\fR ou lorsqu'ils sont directement pre\*'ce\*'de\*'s d'une lettre
majuscule.
.IP "\(bu" 4
\&\f(CW\*(C`E<htmlentite\*'>\*(C'\fR
.Sp
Quelques entite\*'s \s-1HTML\s0 non nume\*'riques telle que \f(CW\*(C`E<eacute>\*(C'\fR,
qui signifie la me\*^me chose que \f(CW\*(C`&eacute;\*(C'\fR en \s-1HTML\s0 \*(-- c.\-a\*`\-d. un e
minuscule avec un accent aigu.
.IP "\(bu" 4
\&\f(CW\*(C`E<nombre>\*(C'\fR
.Sp
Le caracte\*`re ASCII/Latin\-1/Unicode dont le code est le nombre. Le
pre\*'fixe \*(L"0x\*(R" indique que \fInombre\fR est en hexade\*'cimal comme dans
\&\f(CW\*(C`E<0x201E>\*(C'\fR. Le pre\*'fixe \*(L"0\*(R" indique que le nombre est en
octal comme dans \f(CW\*(C`E<075>\*(C'\fR. Sinon, le \fInombre\fR est conside\*'re\*'
en de\*'cimal comme dans \f(CW\*(C`E<181>\*(C'\fR.
.Sp
Notez que les vieux traducteurs Pod peuvent ne pas reconnaitre l'octal
et l'hexade\*'cimal et que de nombreux traducteurs ne savent pas
pre\*'senter correctement les caracte\*`res dont le code est supe\*'rieur a\*`
255. (Certains traducteurs peuvent me\*^me choisir un compromis pour
pre\*'senter les caracte\*`res Latin\-1, en pre\*'sentant un simple \*(L"e\*(R" a\*` la
place de \f(CW\*(C`E<eacute>\*(C'\fR.)
.RE
.RS 4
.RE
.ie n .IP """F<nomfichier>"" \*(-- utilise\*' pour un nom de fichier" 4
.el .IP "\f(CWF<nomfichier>\fR \*(-- utilise\*' pour un nom de fichier" 4
.IX Xref "F F<> POD, code de mise en forme, nom de fichier nom de fichier"
.IX Item "F<nomfichier>  utilise' pour un nom de fichier"
Typiquement affiche\*' en italique. Exemple\ : \f(CW\*(C`F<.cshrc>\*(C'\fR
.ie n .IP """S<texte>"" \*(-- texte contenant des espaces non se\*'cables" 4
.el .IP "\f(CWS<texte>\fR \*(-- texte contenant des espaces non se\*'cables" 4
.IX Xref "S S<> POD, code de mise en forme, espace inse\*'cable espaces inse\*'cable"
.IX Item "S<texte>  texte contenant des espaces non se'cables"
Cela siginifie que les mots du \fItexte\fR ne doivent pas e\*^tre se\*'pare\*'s
sur plusieurs lignes. Exemple\ : \f(CW\*(C`S<$x\ ?\ $y\ :\ $z>\*(C'\fR.
.ie n .IP """X<nom de sujet>"" \*(-- une point d'entre\*'e d'index" 4
.el .IP "\f(CWX<nom de sujet>\fR \*(-- une point d'entre\*'e d'index" 4
.IX Xref "X X<> POD, code de mise en forme, point d'entre\*'e d'index point d'entre\*'e d'index"
.IX Item "X<nom de sujet>  une point d'entre'e d'index"
Ce code est ignore\*' par la plupart des traducteurs mais certains
peuvent l'utiliser pour construire un index. Il est toujours pre\*'sente\*'
comme la chai\*^ne vide. Exemple\ : \f(CW\*(C`X<URL absolu>\*(C'\fR
.ie n .IP """Z<>"" \*(-- un code de mise en forme nul (sans effet)" 4
.el .IP "\f(CWZ<>\fR \*(-- un code de mise en forme nul (sans effet)" 4
.IX Xref "Z Z<> POD, code de mise en forme, nul nul"
.IX Item "Z<>  un code de mise en forme nul (sans effet)"
C'est rarement utilise\*'. C'est l'un des moyens pour empe\*^cher
l'intepre\*'tation d'un code E<...>. Par exemple, a\*` la place de
"\f(CW\*(C`NE<lt>3\*(C'\fR\*(L" (pour \*(R"N<3\*(L"), vous pourriez e\*'crire
\&\*(R"\f(CW\*(C`NZ<><3\*(C'\fR\*(L" (le code \*(R"Z<>\*(L" se\*'pare le \*(R"N\*(L" et le
\&\*(R"<\*(L" afin qu'ils ne soient pas conside\*'re\*'s comme le de\*'but d'une
(hypothe\*'tique) se\*'quence \*(R"N<...>").
.PP
La plupart du temps, un simple couple infe\*'rieur/supe\*'rieur suffira pour
de\*'limiter le de\*'but et la fin de votre code de mise en forme. Mais il
se peut que vous ayez besoin de placer un symbole supe\*'rieur (un signe
X\ plus grand que\ X, '>') dans un code de mise en forme. C'est
tre\*`s courant lorsqu'on souhaite pre\*'senter un extrait de code avec une
police diffe\*'rente du reste du texte. Comme d'habitude en Perl, il y a
plusieurs moyens pour le faire. Le premier consiste tout simplement a\*`
utiliser l'entite\*' X\ plus grand que\ X via le code de mise en
forme \f(CW\*(C`E\*(C'\fR\ :
.PP
.Vb 1
\&  C<$a E<lt>=E<gt> $b>
.Ve
.PP
Ce qui produira\ : \f(CW\*(C`$a <=> $b\*(C'\fR.
.PP
Un moyen plus lisible et probablement plus \*(L"brut\*(R" est d'utiliser de
de\*'limiteurs qui n'imposent pas de codage spe\*'cial pour un simple
\&\*(L">\*(R". Les traducteurs Pod proposent cela en standard depuis perl
5.5.660 via les doubles de\*'limiteurs (\*(L"<<\*(R" et \*(L">>\*(R") qui peuvent e\*^tre
utilise\*'s \fIsi et seulement si il y a un espace apre\*`s le de\*'limiteur
ouvrant et un espace avant le de\*'limiteur fermant\ !\fR. Par exemple\ :
.IX Xref "POD, formatting code, code de mise en forme avec de\*'limiteurs multiples"
.PP
.Vb 1
\&  C<< $a <=> $b >>
.Ve
.PP
En fait, vous pouvez utiliser le nombre d'infe\*'rieurs et de supe\*'rieurs
que vous souhaitez tant qu'il y en a autant dans le de\*'limiteur ouvrant
que dans le de\*'limiteur fermant et si vous vous assurez qu'un espace
suit imme\*'diatement le dernier X\ <\ X du de\*'limiteur ouvrant et
qu'un autre espace pre\*'ce\*`de imme\*'diatement le premier X\ >\ X du
de\*'limiteur fermant (ces espaces seront ignore\*'s). Les exemples suivants
fonctionneront donc aussi\ :
.IX Xref "POD, formatting code, code de mise en forme avec de\*'limiteurs multiples"
.PP
.Vb 2
\&  C<<< $a <=> $b >>>
\&  C<<<< $a <=> $b >>>>
.Ve
.PP
Et ils signifient exactement la me\*^me chose que\ :
.PP
.Vb 1
\&  C<$a E<lt>=E<gt> $b>
.Ve
.PP
Prenons un autre exemple\ : supposons que vous voulez pre\*'senter
l'extrait de code suivant dans un style \f(CW\*(C`C<>\*(C'\fR (code)\ :
.PP
.Vb 2
\&   open(X, ">>thing.dat") || die $!
\&   $foo\->bar();
.Ve
.PP
Vous pourrez le faire comme cela\ :
.PP
.Vb 2
\&   C<<< open(X, ">>thing.dat") || die $! >>>
\&   C<< $foo\->bar(); >>
.Ve
.PP
qui est certainement plus facilement lisible que l'ancien me\*'thode\ :
.PP
.Vb 2
\&   C<open(X, "E<gt>E<gt>thing.dat") || die $!>
\&   C<$foo\-E<gt>bar();>
.Ve
.PP
Tout cela est actuellement accepte\*' par pod2text (Pod::Text), pod2man
(Pod::Man) et tout autre traducteur pod2xxx et Pod::Xxxx qui utilise
Pod::Parser version 1.093 ou supe\*'rieure.
.Sh "L'objectif"
.IX Xref "POD, l'objectif"
.IX Subsection "L'objectif"
L'objectif est la simplicite\*' 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
a\*` travers \f(CW\*(C`fmt\*(C'\fR pour les reformater (c'est F7 dans ma version de
\&\fBvi\fR ou Esc-Q dans ma version de \fBemacs\fR). Je voulais que le
traducteur laisse les \f(CW\*(C`'\*(C'\fR, les \f(CW\*(C``\*(C'\fR et les \f(CW\*(C`"\*(C'\fR tranquilles en mode
verbatim pour que je puisse copier/coller ces paragraphes dans un
programme qui marche, les de\*'caler de 4 espaces, et l'imprimer, euh,
mot pour mot. Et probablement dans une fonte a\*` chasse fixe.
.PP
Le format Pod est certainement insuffisant pour re\*'diger un livre. Pod
essaie juste d'e\*^tre un format infaillible qui puisse servir de source
pour nroff, \s-1HTML\s0, TeX et autres langages de balises, lorsqu'ils sont
utilise\*'s pour de la documentation en ligne. Des traducteurs existent
pour \fBpod2text\fR, \fBpod2html\fR, \fBpod2man\fR (c'est pour \fInroff\fR\|(1) et
\&\fItroff\fR\|(1)), \fBpod2latex\fR et \fBpod2fm\fR. D'autres encore sont disponibles
sur \s-1CPAN\s0.
.Sh "Incorporer du Pod dans les modules Perl"
.IX Subsection "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 X\ =head1\ X et terminez-la par une commande X\ =cut\ X
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 a\*` 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 premie\*`re commande Pod.
.PP
.Vb 1
\&  _\|_END_\|_
\&
\&  =head1 NAME
\&
\&  Time::Local \- efficiently compute time from local and GMT time
.Ve
.PP
Sans cette ligne vide avant \f(CW\*(C`=head1\*(C'\fR, de nombreux traducteurs ne
reconnaitront pas \f(CW\*(C`=head1\*(C'\fR comme le de\*'but d'une section Pod.
.Sh "Conseils pour e\*'crire en Pod"
.IX Subsection "Conseils pour e'crire en Pod"
.IP "\(bu" 4

.IX Xref "podchecker POD, validation POD, ve\*'rificateur"
.Sp
La commande \fBpodchecker\fR permet de ve\*'rifier le respect de la syntaxe
Pod. Par exemple, elle ve\*'rifie les lignes entie\*`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 ve\*'rifier le re\*'sultat (en l'imprimant si
besoin est). Certains proble\*`mes rencontre\*'s peuvent e\*^tre lie\*'s a\*` des
bogues des traducteurs. A\*` vous de de\*'cider si vous voulez les
contourner ou non.
.IP "\(bu" 4
Si vous e\*^tes plus a\*` votre aise en re\*'digeant du \s-1HTML\s0 que du Pod, vous
pouvez re\*'diger votre documentation en \s-1HTML\s0 simple puis la convertir en
Pod gra\*^ce au module expe\*'rimental Pod::HTML2Pod
(disponible sur \s-1CPAN\s0) et enfin ve\*'rifier le code obtenu. Le module
expe\*'rimental Pod::PXML peut aussi e\*^tre utile.
.IP "\(bu" 4
De nombreux traducteurs Pod ont absolument besoin d'une ligne blanche
avant et apre\*`s chaque commande Pod (commande =cut y compris). Quelque
chose comme c\*,a\ :
.Sp
.Vb 2
\&  # \- \- \- \- \- \- \- \- \- \- \- \-
\&  =item $firecracker\->boom()
\&
\&  This noisily detonates the firecracker object.
\&  =cut
\&  sub boom {
\&  ...
.Ve
.Sp
\&...ame\*`nera ces traducteurs Pod a\*` ignorer totalement la section Pod.
.Sp
A\*` la place, pre\*'fe\*'rez quelque chose comme ceci\ :
.Sp
.Vb 1
\&  # \- \- \- \- \- \- \- \- \- \- \- \-
\&
\&  =item $firecracker\->boom()
\&
\&  This noisily detonates the firecracker object.
\&
\&  =cut
\&
\&  sub boom {
\&  ...
.Ve
.IP "\(bu" 4
Certains traducteurs Pod anciens ont absolument besoin de paragraphes
(incluant les paragraphes de commande comme \*(L"=head2 Fonctions\*(R")
se\*'pare\*'s par des lignes \fIcomple\*`tement\fR vides. Si vous avez des lignes
apparament vides mais contenant en fait des espaces, elles ne seront
pas reconnues comme se\*'parateurs par ces traducteurs et provoqueront
peut\-e\*^tre de mauvaises mises en forme.
.IP "\(bu" 4
Des traducteurs Pod anciens ajoutent quelques mots autour de certains
liens L<> de telle manie\*`re que \f(CW\*(C`L<Foo::Bar>\*(C'\fR
deviendra par exemple \*(L"the Foo::Bar manpage\*(R". Vous ne pouvez donc pas
e\*'crire des choses telles que \f(CW\*(C`la documentation L<bidule>\*(C'\fR si
vous voulez que le re\*'sultat reste compre\*'hensible. A\*` la place, e\*'crivez
\&\f(CW\*(C`la documentation L<bidule|bidule>\*(C'\fR ou \f(CW\*(C`L<la
documentation\*(C'\fR \f(CW\*(C`bidule|bidule>\*(C'\fR pour contro\*^ler l'apparence du lien.
.IP "\(bu" 4
Un texte qui de\*'passe la 70e colonne dans un bloc verbatim peut e\*^tre
arbitrairement coupe\*' par certains traducteurs.
.SH "VOIR AUSSI"
.IX Header "VOIR AUSSI"
perlpodspec, \*(L"\s-1POD:\s0 documentation inte\*'gre\*'e\*(R" in perlsyn,
perlnewmod, perldoc, pod2html, pod2man, podchecker.
.SH "AUTEUR"
.IX Header "AUTEUR"
Larry Wall, Sean M. Burke
.SH "TRADUCTION"
.IX Header "TRADUCTION"
.Sh "Version"
.IX Subsection "Version"
Cette traduction franc\*,aise correspond a\*` la version anglaise distribue\*'e avec
perl 5.8.8.  Pour en savoir plus concernant ces traductions, consultez
<http://perl.enstimac.fr/>.
.Sh "Traducteur"
.IX Subsection "Traducteur"
Traduction initiale\ : Roland Trique
<\fIroland.trique@free.fr\fR>. Mise a\*` jour\ : Paul Gaborit
<paul.gaborit at enstimac.fr>.
.Sh "Relecture"
.IX Subsection "Relecture"
Ge\*'rard Delafond