Plain Old Documentation

Wikipedia
Loikkaa: valikkoon, hakuun
Tämä artikkeli kertoo dokumentointityökalusta. P.O.D. on myös yhdysvaltalainen yhtye.

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

Tarkoitus[muokkaa | muokkaa wikitekstiä]

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ö[muokkaa | muokkaa wikitekstiä]

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

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

  • 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.