Plain Old Documentation

Plain Old Documentation (POD) is een eenvoudige opmaaktaal die wordt gebruikt bij het documenteren van Perl-software.

POD is ontworpen om, met geringe inspanning, documentatie te schrijven zodat voorkomen wordt dat programmeurs ongedocumenteerde code afleveren.

Door middel van tags wordt in de source de documentatie gemarkeerd. De tags bestaan uit een is-gelijk teken (=) en gevolgd door een keyword als head1 of item.

De tag bepaalt de manier waarop de tekst door de POD tool wordt afgedrukt.

Voorbeeld

Hieronder staat een met POD gedocumenteerd Perlprogramma afgedrukt:

 #!/usr/local/bin/perl
 
 =head1 NAME
 PODvoorbeeld: Drukt de getallen 1 tot en met 10 af  
 =head1 SYNOPSIS
 perl PODvoorbeeld
 
 =head1 DESCRIPTION
 Dit voorbeeld programma is louter bedoeld om een demonstratie van POD
 te geven. Gebruik pod2text PODvoorbeeld om de documentatie in
 UNIX-manual style te genereren.
 =cut
 =over 2
 
 =item Werking:
 Dit programma heeft geen opties. En drukt "Klaar!" af als het gereed
 is met het afdrukken van de getallen 1 tot en met 10.
 =back
 =cut
 
 # Voeg hier code in
 
 =over 2
 =item Hoofdlus:
 Alle belangrijke logica bevindt zich in een lus die maar liefst 10 keer
 wordt aangeroepen.  
 =back
 =cut
 
 for ($i = 1; $i <= 10; $i++) {
 	print $i;
 }
 
 # Voeg hier nog meer code in
 
 =over 2
 =item Afsluiten:
 En het programma wordt afgesloten met "Klaar!".
 =back
 =cut
 
 print "Klaar!";

Met de opdracht pod2text PODvoorbeeld wordt de documentatie gegenereerd:

 NAME
     PODvoorbeeld: Drukt de getallen 1 tot en met 10 af
 
 SYNOPSIS
     perl PODvoorbeeld
 
 DESCRIPTION
     Dit voorbeeld programma is louter bedoeld om een demonstratie van POD te
     geven. Gebruik pod2text PODvoorbeeld om de documentatie in UNIX-manual
     style te genereren.
 
     Werking:
       Dit programma heeft geen opties. En drukt "Klaar!" af als het gereed
       is met het afdrukken van de getallen 1 tot en met 10.
 
     Hoofdlus:
       Alle belangrijke logica bevindt zich in een lus die maar liefst 10 keer
       wordt aangeroepen.
 
     Afsluiten:
       En het programma wordt afgesloten met "Klaar!".

Conclusie

Omdat bij POD de code en documentatie met elkaar verweven zijn, is het eenvoudig om de documentatie te schrijven en te onderhouden. Wordt in het geval van het bovenstaande voorbeeld de getallenreeks 1 tot en met 10 veranderd in 1 tot en met 11 dan kan gelijktijdig met de code ook de documentatie aangepast worden.

POD tools

Onderstaande tools worden meegeleverd met iedere Perl installatie.

• podchecker: controleert de syntaxis van de POD;
• pod2text: zet POD file om in tekst formaat (zie voorbeeld);
• pod2html: zet POD file om in html formaat, zodat het in een webbrowser te bekijken is;
• perldoc perlpod: geeft volledige POD manual weer.