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.^[1]

Tämä artikkeli kertoo dokumentointityökalusta. P.O.D. on myös yhdysvaltalainen yhtye.

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 <[e-mail]>.
 
 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