LINUXSOFT.cz Přeskoč levou lištu
Uživatel: Heslo:  
   CZUKPL

> Perl (70) - Plain Old Documentation

Perl 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 10595×

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

$ perldoc Net::POP3

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

PřepínačVýznam
-mzobrazí se celý zdrojový kód modulu
-f funkcezobrazí se popis příslušné funkce podle perlfunc
-q klíčové_slovozobrazí se FAQ otázky, odpovídající zadanému klíčovému slovu

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.

OddílVýznamPopis
NAMEnázevjméno modulu a několikaslovný popis
SYNOPSIScharakteristikarychlá informace, jak program použít
DESCRIPTIONpopisrozsáhlejší pojednání o funkci programu
BUGS nebo CAVEATSchybyproblémy, jež modul zatím obsahuje
SEE ALSOpříbuzná témataodkazy na související manuálové stránky, WWW adresy apod.
AUTHORautorautoři programu a kontakty
HISTORYvývojpředchozí verze modulu
COPYRIGHT nebo LICENSElicencepodmínky užívání, vlastnická práva apod.

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:

ZápisVýznam
B<text>programy, přepínače (tučné)
C<text>zdrojový kód
I<text>zvýraznění, proměnné (kurzíva)
L<stránka>odkaz na jinou stránku
E<jméno znaku>escape znak
X<položka>buď ignorováno nebo pro vytváření indexů
F<jméno>zvýraznění názvu souboru
S<text>mezery v textu jsou nedělitelné
Z<>prázdný znak

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:

PříkazVýznam
pod2htmlvytváří HTML dokumentaci
pod2manvytváří dokumentaci ve formátu troff užívaného pro manuálové stránky
pod2textvytváří prostý text
pod2latexvytváří dokumentaci ve formátu LaTeX

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

pridej.cz

 

DISKUZE

Nejsou žádné diskuzní příspěvky u dané položky.



Příspívat do diskuze mohou pouze registrovaní uživatelé.
> Vyhledávání software
> Vyhledávání článků

5.3.2017 19:12 /Redakce Linuxsoft.cz
PR: 23. března proběhne v Praze konferenci na téma Cloud computing v praxi. Hlavními tématy jsou: Nejžhavější trendy v oblasti cloudu a cloudových řešení, Moderní cloudové služby, Infrastruktura současných cloudů, Efektivní využití cloudu, Nástrahy cloudových řešení a jak se jim vyhnout.
Přidat komentář

27.2.2017 22:12 /František Kučera
Pozvánka na 137. sraz OpenAlt – Praha: Tentokrát jsme si pro vás připravili neobvyklou akci. Ve středu 1.3. v 17:30 nás přivítá sdružení CZ.NIC ve svých prostorách v Milešovské ulici číslo 5 na Praze 3, kde si pro nás připravili krátkou prezentaci jejich činnosti. Následně navštívíme jejich datacentrum pod Žižkovskou věží. Provedou nás prostory, které jsou běžnému smrtelníkovi nedostupné!
Po ukončení prohlídky se všchni odebereme do hostince U vodoucha, Jagelonská 21, Praha 3 pochutnat si na některém z vybraných piv či dát si něco na zub. Rezervaci máme od 19:30, heslo je OpenAlt.
Ale pozor! Do prostor datového centra máme omezený přístup, dostane se tam pouze 10 lidí! Takže kdo přijde dříve, ten má přednost, a občanky s sebou! Kdo nebude chtít na prohlídku datového centra, může se pomalu přesunout do hostince U vodoucha a u nepřeberné nabídky piv počkat na ostatní.
Přidat komentář

18.1.2017 0:49 /František Kučera
Členové a příznivci spolku OpenAlt se pravidelně schází v Praze a Brně. Fotky z pražských srazů za uplynulý rok si můžete prohlédnout na stránkách spolku. Příští sraz se koná už 19. ledna – tentokrát je tématem ergonomie ovládání počítače – tzn. klávesnice, myši a další zařízení. Také budete mít příležitost si prohlédnout pražský hackerspace Brmlab.
Přidat komentář

8.1.2017 17:51 /František Kučera
Máš rád svobodný software a hardware nebo se o nich chceš něco dozvědět? Přijď na sraz spolku OpenAlt, který se bude konat ve čtvrtek 19. ledna od 18:30 v pražském hackerspacu Brmlab. Tentokrát je tématem srazu ergonomie ovládání počítače – tzn. klávesnice, myši a další zařízení. K vidění bude mechanická klávesnice dasKeyboard, trackball Logitech nebo grafický tablet (a velký touchpad) Wacom. Přineste i vy ukázat svoje zajímavé klávesnice a další HW. V 18:20 je sraz před budovou, v 18:30 jdeme společně dovnitř, je tedy dobré přijít včas. Podle zájmu se později přesuneme do nějaké restaurace v okolí.
Přidat komentář

1.12.2016 22:13 /František Kučera
Máš rád svobodný software a hardware nebo se o nich chceš něco dozvědět? Přijď na sraz spolku OpenAlt, který se bude konat ve čtvrtek 8. prosince od 18:00 v Radegastovně Perón (Stroupežnického 20, Praha 5). Sraz bude tentokrát tématický. Bude retro! K vidění budou přístroje jako Psion 5mx nebo Palm Z22. Ze svobodného hardwaru pak Openmoko nebo čtečka WikiReader. Přijďte se i vy pochlubit svými legendami, nebo alespoň na pivo. Moderní hardware má vstup samozřejmě také povolen.
Komentářů: 1

4.9.2016 20:13 /Pavel `Goldenfish' Kysilka
PR: Dne 22.9.2016 proběhne v Praze konference Cloud computing v praxi. Tématy bude např. nejnovější trendy v oblasti cloudu a cloudových řešení, provozování ERP v cloudu, o hostování různých typů softwaru, ale třeba i o zálohování dat nabízeném podnikům formou služby.
Přidat komentář

1.9.2016 11:27 /Honza Javorek
Česká konference o Pythonu, PyCon CZ, stále hledá přednášející skrz dobrovolné přihlášky. Máte-li zajímavé téma, neváhejte a zkuste jej přihlásit, uzávěrka je již 12. září. Konference letos přijímá i přednášky v češtině a nabízí pomoc s přípravou začínajícím speakerům. Řečníci mají navíc vstup zadarmo! Více na webu.
Přidat komentář

27.8.2016 8:55 /Delujek
Dnes po 4 letech komunitního vývoje vyšla diaspora 0.6.0.0
diaspora* je open-source, distribuovaná sociální síť s důrazem na soukromý
Více v oficiálním blog-postu
Přidat komentář

   Více ...   Přidat zprávičku

> Poslední diskuze

24.3.2017 11:54 / Hui
country cottages

16.3.2017 16:33 / BezvaDesign.cz
Re: Hledám grafika do teamu

9.3.2017 11:44 / Jaromir Obr
Re: chyba

18.1.2017 20:18 / martin horky
Spolupraca linuxu a microsoftu

17.1.2017 9:57 / Pavel Hrubeš
Re: Externí USB televizní karta

Více ...

ISSN 1801-3805 | Provozovatel: Pavel Kysilka, IČ: 72868490 (2003-2017) | mail at linuxsoft dot cz | Design: www.megadesign.cz | Textová verze