Plain Old Documentation

Uit Wikipedia, de vrije encyclopedie
Ga naar: navigatie, zoeken

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[bewerken]

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 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 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 bevindt zich in een lus die maar liefst 10 keer
      wordt aangeroepen.

    Afsluiten:
      En het programma wordt afgesloten met "Klaar!".

Conclusie[bewerken]

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[bewerken]

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.