perlpod - plain old documentation (``bonne vieille documentation'')
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 : mot pour mot, de commande, et texte ordinaire.
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.
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
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.
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, 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.
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 <br> <p> This is a raw HTML paragraph </p>
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
<br>Figure 1.<IMG SRC="figure1.png"><br>
=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 paragraphe, 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
Il sera plein, et peut-être même justifié. Certaines séquences internes sont reconnues à la fois ici et dans les commandes :
I<texte> Texte en italique, utilise' pour l'accentuation ou les variables
B<texte> Texte en gras, utilise' pour les options et les programmes
S<texte> Le texte contient des espaces insecables
C<code> Code litteral
L<nom> Un lien (reference croisee) vers nom
L<nom> page de manuel
L<nom/ident> element dans la page de manuel
L<nom/"sec"> section dans une autre page de manuel
L<"sec"> section dans cette page de manuel
(les guillemets sont optionels)
L</"sec"> idem
la meme chose que ci-dessus mais seul 'texte' est utilise comme sortie.
(Le Texte ne peut pas contenir les caracteres '|' ou '>')
L<texte|nom>
L<texte|nom/ident>
L<texte|nom/"sec">
L<texte|"sec">
L<texte|/"sec">
F<file> Utilise pour les noms de fichier
X<index> Une entree d'index
Z<> Un caractere de largeur nulle
E<escape> Un caractere nomme (tres similaire aux sequences d'echappement HTML)
E<lt> Un < litteral
E<gt> Un > litteral
(Ceux-ci sont optionnels sauf dans d'autres sequences internes
et quand ils sont precedes d'une lettre majuscule)
E<n> Caractere numero n (probablement en ASCII)
E<html> Une entite HTML non numerique, comme
E<Agrave>
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 vi). 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 pod2man (ceci est pour nroff(1) et troff(1)),
pod2text, pod2html, pod2latex, et pod2fm.
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.
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.
Les traducteurs ajouteront généralement des mots autour d'un lien L<>, de façon que L<foo(1)> devienne ``the foo(1) manpage'', par exemple (voir
pod2man pour des détails). Ainsi, vous ne devriez pas écrire de choses the
L<foo> 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 L<show this text|foo> à la place.
Le script pod/checkpods.PL 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 seulement, 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.
pod2man and PODs: Documentation Incorporée
Larry Wall
Roland Trique (roncevaux@mail.dotcom.fr)