Plain Old Documentation
Van Wikipedia
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.
[bewerk] Voorbeeld
Hieronder staat een met POD gedocumenteerde Perl programma 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 bevind 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 word 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 bevind zich in een lus die maar liefst 10 keer
wordt aangeroepen.
Afsluiten:
En het programma word afgesloten met "Klaar!".
[bewerk] 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.
[bewerk] POD tools
Onderstaande tools worden meegeleverd met iedere Perl installatie.
- podchecker: controleert de syntax 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.
