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 <[email protected]>.

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 . Hakemisto sisältää monia moduuleita, joihin on kirjoitettu POD:ia.

Luokka:Perl Luokka:Merkintäkielet