Plain Old Documentation

Wikipedia

Plain Old Documentation, yleensä lyhennetty POD, on yksinkertainen alustariippumaton dokumentointityökalu Perl-ohjelmointikielelle.

Sisällysluettelo

1 Tarkoitus
2 Käyttö
3 Esimerkki
4 Aiheesta muualla

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

[muokkaa] 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)

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