Plain Old Documentation

Plain Old Documentation, yleensä lyhennetty POD, on yksinkertainen merkintäkieli, jota käytetään kirjoittamaan dokumentaatiota Perl-ohjelmointikielelle, Perl-ohjelmille ja Perl-moduuleille.

Tarkoitus

POD on suunniteltu olemaan yksinkertainen, puhdas kieli, joka sisältää tarpeelliset merkinnät. Siinä ei ole sisäänrakennettuja mekanismeja fonteille, kuville, väreille, eikä taulukoille; sen sijaan se yrittää olla tarpeeksi laaja ollakseen hyödyllinen. Tavoitteita ovat:

• Helppo jäsentää
• Helppo muuttaa toiselle kielelle, kuten HTML:lle tai TeX:lle
• Helppo lisätä esimerkkikoodia mukaan
• Helppo lukea sellaisenaan
• Helppo kirjoittaa, muuten kehittäjät eivät dokumentoi koodiaan

Käyttö

Lähes kaikki dokumentaatio Perl-maailmassa on tehty POD:lla. Itse Perl, kaikki julkiset Perl-moduulit, monet skriptit sekä monet artikkelit osoitteessa Perl.com on dokumentoitu POD:lla.

POD:ia harvoin luetaan raakana, kuitenkin se on suunniteltu olemaan luettavana ilman erillisiä ohjelmia. Sen sijaan sitä luetaan perldoc- ohjelmalla, muunnetaan Unixin manuaalisivuksi tai muutetaan HTML-muotoon.

Puhtailla POD-tiedostoilla on yleensä .pod-pääte, mutta POD:ia usein kirjoitetaan suoraan Perl-koodiin, joka käyttää .pl - ja .pm -päätteitä. (Perl-kääntäjä on suunniteltu niin, että se ei ota huomioon POD-dokumentaatiota)

Esimerkki

Esimerkkitiedosto POD:n käytöstä. Dokumentin voi katsoa perldoc-ohjelmalla tai muuttaa HTML-muotoon pod2html-ohjelmalla.

 $ pod2html esim.pod -o esim.html

Tekstiä suomennettu en-puolelta ja myös POD-esimerkki otettu sieltä. Pikaisen testin tuloksena perldoc ja pod2html eivät tunnistaneet U<alleviivattua>-merkintää.

Tiedosto: esim.pod

 =head1 TITLE
 
 podesimerkki - Esimerkki POD:n käytöstä
 
 =head1 SYNOPSIS
 
 $x = $foo→bar( @foobar );
 print "\$x=$x";
 
 =head1 DESCRIPTION
 
 Normaalia tekstiä. Tekstiä voi muotoilla muutaman
 yksinkertaisen komennon avulla. B<lihavoitua>, I<kursiivia>, 
 U<alleviivattua>, sekä C<$koodia>
 
 =head2 An Example List
 
 =over 4
 
 =item * Tässä on lista
 
 =item * Listan toinen kohta
 
 =back 4
 
 =begin html
 
 <img src="fig1.png" align="right" alt="Figure 1." />
 <p>
 Tässä on HTML:ää. Tässä lohkossa voi lisätä kuvia 
 include images, käyttää <span style="color: green">
 tyylimäärittelyjä</span>, tai tehdä mitä tahansa
 HTML:llä. POD-jäsentimet, jotka eivät tuota HTML:ää ohittavat
 tämän lohkon.
 </p>
 
 =end html
 
 =head1 SEE ALSO
 
 L<perlpod>, L<perldoc>, L<Pod::Parser>.
 
 =head1 COPYRIGHT
 
 Copyright 2005 J. Random Hacker <jrh@cpan.org>.
 
 Permission is granted to copy, distribute and/or modify this 
 document under the terms of the GNU Free Documentation 
 License, Version 1.2 or any later version published by the 
 Free Software Foundation; with no Invariant Sections, with 
 no Front-Cover Texts, and with no Back-Cover Texts.
 
 =cut

Aiheesta muualla

• perlpod - Dokumentaatiota POD:sta niille, jotka kirjoittavat sillä
• perlpodspec - Dokumentaatiota POD:sta niille, jotka tekevät jäsentimiä sille
• Perlin manuaalisivut ovat nähtävillä POD-muodossa osoitteessa [1].
• Hakemisto [2] sisältää monia moduuleita, joihin on kirjoitettu POD:ia.