ARCHIV

Perl (70) - Plain Old Documentation

Perl nabízí vlastní systém tvorby dokumentace. Lze ji psát přímo do zdrojového kódu programů a snadno se exportuje do jiných formátů.

25.6.2008 08:00 | Jiří Václavík | Články autora | přečteno 15206×

Plain Old Documentation (POD) je jednoduchý značkovací jazyk, používaný jako dokumentace v jazyce Perl.

Specialitou formátu POD je, že se dokumentace píše do stejného souboru jako samotný zdrojový kód a může se s ním libovolně prolínat. (Nicméně není to podmínkou a lze vytvořit také samostatný .pod soubor.)

Nespornou výhodou plynoucí z této skutečnosti je, že můžeme generovat dokumentaci (například ve formě manuálových stránek) přímo ze skriptů.

Ve formátu POD je dnes zdokumentována řada aplikací v Perlu - zejména pak moduly v archivu CPAN.

Prohlížení POD

POD dokumentaci většinou neprohlížíme, ale konvertujeme na nějaký jiný formát dokumentace. Nicméně základním příkazem pro zobrazování POD dokumentace je příkaz perldoc, kterému se předává název POD stránky s dokumentací nebo přímo zdrojový soubor. Například pro zobrazení dokumentace k modulu Net::POP3 zadáme příkaz

Mezi nejzajímavější přepínače příkazu perldoc patří tyto.

Více informací lze nalézt v manuálové stránce perldoc(1).

Struktura

Pro modul zdokumentovaný v POD existuje jistá nezávazná konvence, která určuje jména možných oddílů. Samozřejmě lze podle potřeby volit jiné názvy. Vždy bychom však měli pojmenování pečlivě zvážit, neboť na něm do značné míry záleží srozumitelnost dokumentace.

Syntaxe

POD se do zdrojového kódu Perlu vnořuje pomocí speciálních klíčových slov. Před každým klíčovým slovem POD je znak =.

Pro studium jazyka POD je nejlepší cestou prohlížení zdrojových kódů zdokumentovaných modulů. My si zde představíme základní příkazy.

Začátek bloku dokumentace

POD lze začít jakýmkoliv POD příkazem. Protože někdy nemusíme chtít začít klasickým příkazem, ale pouze pokračovat v textu, existuje zde příkaz =pod, který nedělá nic. Je tedy užitečný právě k signalizaci začátku bloku dokumentace.

Konec bloku dokumentace

Uvedením =cut na samostatný řádek ukončíme blok dokumentace. Některé POD parsery vyžadují také prázdný řádek před =cut.

Titulky

Nadpisy se vytvářejí příkazem =headn, kde n je úroveň nadpisu. Titulky nejvyšší úrovně se píší velkými písmeny.

Styl písma

Pro změnu stylu textu zde jsou jednopísmenné příkazy, které se vztahují na text v lomených závorkách, jež za příkazem následují. Lze využít následující příkazy:

Pokud se někde ve formátovaném textu vyskytuje znak >, musíme zajistit, aby se nepletl se znakem, jež ukončuje formátování. Nejjednodušším řešením je jeho nahrazením escape sekvencí E<gt>.

Seznamy

Seznamy se uvádějí mezi příkazy =over a =back. Příkaz =over přijímá jako argument počet znaků, o které budou položky výčtu odsazeny. Jednotlivé položky výčtu jsou pak uvozeny příkazem =item.

Následuje krátký příklad seznamu, který zachycuje jeho možnosti.

=head2 Ukazka seznamu

=over 15

=item C<1. Polozka>

Popis 1. polozky

=item C<2. Polozka>

Popis 2. polozky. Pokud napiseme text, ktery zabira vice radku, muzeme videt, ze
budou automaticky odsazeny.

=item C<dalsi polozka>

Jiny pripad nastane, kdyz presahne maximalni velikost pro jmeno polozky

=back

Výsledek vypadá následovně

Ukázka seznamu

Specifické bloky

Jak uvidíme níže, POD lze konvertovat do jiných formátů dokumentace. POD nám umožňuje definovat bloky kódu pouze pro určitý formát.

Pomocí klíčových slov =begin formát a =end formát lze takový blok textu napsat. Například pokud budeme chtít uvést v dokumentaci nějaké schéma, pro HTML dokumentaci použijeme PNG obrázek, pro textovou dokumentaci semigrafiku atd.

=begin html

    <IMG SRC="schema.png">

=end html

=begin text

    +-------------+       +-------------+
    |             |       |             |
    |    NODE 1   |-------|    NODE 2   |
    |             |       |             |
    +-------------+       +-------------+

=end text

Koverze POD do jiných formátů

Je-li zdrojový kód zdokumentovaný pomocí POD, lze z něj kdykoliv generovat jiné formy dokumentace pomocí nástrojů pod2formát. Mezi takové příkazy patří například tyto:

Uložme do souboru priklad.pod náš poslední příklad a zkusme následující dva příkazy.

$ pod2text priklad.pod
$ pod2html priklad.pod

Příklad - dokumentace programu live

Ukažme si jen velice stručný příklad POD stránky. Takto by mohla vypadat dokumentace k programu live, který jsme vytvořili v předcházející šestidílné sérii.

=head1 NAME

live - online monitoring of soccer

=head1 SYNOPSIS

live [-o] [-l league] [pattern]

=head1 DESCRIPTION

live is based on Livescore perl module. live acquires data from Livescore and
displays informations about match in text format.

=head1 OPTIONS

=item B<    -o, --online>

        online transmission

=item B<    -l, --league> I<region>

        display only matches from selected region.

=item B<    -r, --refresh>

        time interval for refresh (default 60 sec.)

=item B<    -h, --help>

        display help message and exit

=head1 FILES

temporary files /tmp/livescore_*

=head1 SEE ALSO

Livescore(3pm)

=head1 AUTHOR

Jiri Vaclavik

=head1 COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software Foundation

=cut

Příkazem perlpod dostaneme následující výstup

Dokumentace k programu live

Verze pro tisk