Le format POD7.1 a été conçu par Larry Wall afin de faciliter la documentation des modules et programmes perl. Un de ses énormes avantages est qu'il peut être inséré à l'intérieur même du code perl, ce qui fournit une documentation automatique - et souvent plus à jour - des modules en particulier. Le but de ce langage est de fournir aux programmeurs un moyen simple d'écrire de la documentation.
Un ensemble de convertisseurs est disponible pour convertir ce format POD en d'autres formats : nroff avec pod2man pour l'affichage dans les terminaux, texte avec pod2txt pour la lecture simple, LATEX avec pod2tex pour obtenir une impression de qualité, HTML avec pod2html, etc. Le document au format POD lui-même ne nécessite pas d'éditeur particulier. Comme pour les programmes perl, un simple éditeur de texte suffit.
Le programme perldoc cherche dans les modules de perl celui qui correspond à l'argument qui a été passé, et en extrait la documentation.
La documentation du format est disponible, au format POD bien sûr, en exécutant la commande perldoc perlpod.
La syntaxe de POD est simple : elle consiste en trois types de paragraphes. Tous les paragraphes doivent être séparés par une ligne vide.
Le premier est un paragraphe indenté par au moins un espace ou une tabulation. Le texte de ce paragraphe sera alors reproduit tel-quel (verbatim).
Le second type est une commande. Une commande commence par un signe égal (=), suivi d'un identificateur, puis un texte pouvant être utilisé par l'identificateur. Le tableau 7.1 récapitule les différents identificateurs reconnus.
Lors de la construction d'une liste, il est demandé de rester cohérent dans l'utilisation du paramètre de l'identificateur =item. On utilise couramment =item * pour construire une liste avec de simples boutons, =item 1, =item 2, etc pour construire une liste numérotée, et enfin =item titi pour construire une énumération d'éléments.
Le premier élément de la liste est utilisé par la plupart des convertisseurs pour choisir le type de liste. Par exemple, une liste commençant par =item * sera convertie en HTML en liste non-ordonnée (<ul> <li> ... </ul>), et en LATEX également (environnement list), tandis qu'une liste commençant par =item toto sera convertie en HTML en liste de définitions (<dl> <dt> ... <dd> ... </dl>) et en LATEX en énumération (environnement enumerate).
Le paramètre de l'identificateur =over N est la taille de l'indentation utilisée. La valeur par défaut est de 4.
Le dernier type de paragraphe est un bloc de texte ordinaire, qui peut de plus contenir des commandes de mise en forme, résumées dans le tableau 7.2.
|
Il suffit à l'intérieur d'un programme perl de commencer la documentation par la commande =head1 texte, et de la terminer par la commande =cut. L'interpréteur ignorera le texte compris entre ces deux éléments.
Un exemple est beaucoup plus parlant. En voilà quelques lignes, tirées d'un programme existant :
=head1 NAME clean - clean your account... =head1 SYNOPSIS B<clean> [options] [directory] with options in: =over 4 [B<-a>] [B<--all>] [B<-c>] [B<--check-only>] [B<-d>] [B<--default>] [B<-e>] [B<--delete-empty-dir>] [B<-f>I<[filename]>] [B<--output>I<[=filename]>] [...] [B<-V>] [B<--version>] =back =head1 OPTIONS [...]
On voit ici apparaître diverses sections standard dans les pages de manuel UNIX : NAME, SYNOPSIS, OPTIONS, DESCRIPTION, NOTES, ENVIRONMENT, FILES, AUTHOR, BUGS.
De nombreux exemples sont disponibles également dans toute distribution de perl : la documentation est au format POD. Elle se trouve généralement dans le répertoire /usr/local/lib/perl5/pod/, ou /usr/lib/perl5/pod/.