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
 
 &lt;img src="fig1.png" align="right" alt="Figure 1." /&gt;
 &lt;p&gt;
 Tässä on HTML:ää. Tässä lohkossa voi lisätä kuvia 
 include images, käyttää &lt;span style="color: green"&gt;
 tyylimäärittelyjä&lt;/span&gt;, tai tehdä mitä tahansa
 HTML:llä. POD-jäsentimet, jotka eivät tuota HTML:ää ohittavat
 tämän lohkon.
 &lt;/p&gt;
 
 =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
```


## Lähteet

## 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 http://search.cpan.org/src/NWCLARK/perl-5.8.6/pod/.
* Hakemisto http://search.cpan.org/src/NWCLARK/perl-5.8.6/lib/ sisältää monia moduuleita, joihin on kirjoitettu POD:ia.