Plain Old Documentation

aus Wikipedia, der freien Enzyklopädie
Wechseln zu: Navigation, Suche

Plain Old Documentation (POD) ist eine vereinfachte Auszeichnungssprache, die 1994 von Larry Wall mit Perl 5 eingeführt wurde, um Dokumentation in den Quelltext von Perl-Programmen einzufügen.

Eigenschaften von POD[Bearbeiten]

POD ist eine einfache Sprache in mehrerer Hinsicht:

  • einfach zu schreiben (für den Autor)
  • leicht lesbarer Quellcode
  • leicht zu parsen
  • leicht in andere Sprachen und Formate umzuwandeln – etwa in UNIX-Manpages, LaTeX, troff oder HTML
  • einfach, Quellcode darin unterzubringen

Verbreitung[Bearbeiten]

POD ist die meistbenutzte Sprache, um Perlprogramme und -module zu dokumentieren, Perl selbst eingeschlossen, und ist auch Standard für die Dokumentation der Module im CPAN.

Beispiel-Dokument[Bearbeiten]

Der folgende Schnipsel enthält einige typische POD-Sprachelemente.

=pod

=head1 TITEL

podsample - A sample POD document

=head1 ZUSAMMENFASSUNG

    $here->isa(Piece::Of::Code);
    print <<"END";
    Dieser eingezogene Block wird nicht nach Formatierungsanweisungen
    durchsucht und Leerzeichen bleiben erhalten.
    END

=head1 BESCHREIBUNG

Hier steht normaler Text, Es folgen
B<fett>, I<kursiv>,
S<langer Text ohne Zeilenumbruch>,
C<$code> (formatierter Quellcode),
E<Sonderzeichenname>, F<Dateiname>,
L<Labeltext|Linkadresse>, X<Indexeintrag>.
Z<Zeichen ohne Breite>

=head2 Eine Liste

=over 4

=item * mit Blickfangpunkten.

=item * noch ein Punkt.

=back

=begin html

<img src="fig1.png" align="right" alt="Figure 1." />
<p>
    Hier ist etwas eingefüger HTML-Code. Dieser Block kann
    Bilder beinhalten, und alles was du sonst noch so mit
    HTML tun kannst. POD parser die kein HTML ausgeben werden
    dies vollständig ignorieren.
</p>

=end html

=head1 SIEHE AUCH

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

Werkzeuge[Bearbeiten]

Die folgenden Werkzeuge verarbeiten POD:

pod2html
erzeugt html aus POD
pod2latex
generiert LaTeX aus POD
pod2man
macht Manpages aus POD
pod2text
einfacher Text aus POD
pod2usage
druckt usage:-Zeile aus eingebettetem POD
pod2wiki
verwandelt POD in verschiedene Wikiformate, darunter auch mediawiki[1]
podchecker
Syntaxchecker für POD
podselect
druckt ausgewählte Abschnitte aus POD auf stdout
Weitere Werkzeuge wie Pod
:ProjectDocs können die Dokumentation ganzer Projekte automatisiert beispielsweise nach HTML wandeln

Ähnliche Werkzeuge[Bearbeiten]

Literatur[Bearbeiten]

  • Wall, Larry; Christiansen, Tom; Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 978-0-596-00027-1.

Einzelnachweise[Bearbeiten]

  1. Pod::Simple::Wiki auf CPAN.org

Weblinks[Bearbeiten]