LINUXSOFT.cz Přeskoč levou lištu

ARCHIV



   

> 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 14929×

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ů

28.11.2018 23:56 /František Kučera
Prosincový sraz spolku OpenAlt se koná ve středu 5.12.2018 od 16:00 na adrese Zikova 1903/4, Praha 6. Tentokrát navštívíme organizaci CESNET. Na programu jsou dvě přednášky: Distribuované úložiště Ceph (Michal Strnad) a Plně šifrovaný disk na moderním systému (Ondřej Caletka). Následně se přesuneme do některé z nedalekých restaurací, kde budeme pokračovat v diskusi.
Komentářů: 1

12.11.2018 21:28 /Redakce Linuxsoft.cz
22. listopadu 2018 se koná v Praze na Karlově náměstí již pátý ročník konference s tématem Datová centra pro business, která nabídne odpovědi na aktuální a často řešené otázky: Jaké jsou aktuální trendy v oblasti datových center a jak je optimálně využít pro vlastní prospěch? Jak si zajistit odpovídající služby datových center? Podle jakých kritérií vybírat dodavatele služeb? Jak volit vhodné součásti infrastruktury při budování či rozšiřování vlastního datového centra? Jak efektivně datové centrum spravovat? Jak co nejlépe eliminovat možná rizika? apod. Příznivci LinuxSoftu mohou při registraci uplatnit kód LIN350, který jim přinese zvýhodněné vstupné s 50% slevou.
Přidat komentář

6.11.2018 2:04 /František Kučera
Říjnový pražský sraz spolku OpenAlt se koná v listopadu – již tento čtvrtek – 8. 11. 2018 od 18:00 v Radegastovně Perón (Stroupežnického 20, Praha 5). Tentokrát bez oficiální přednášky, ale zato s dobrým jídlem a pivem – volná diskuse na téma umění a technologie, IoT, CNC, svobodný software, hardware a další hračky.
Přidat komentář

4.10.2018 21:30 /Ondřej Čečák
LinuxDays 2018 již tento víkend, registrace je otevřená.
Přidat komentář

18.9.2018 23:30 /František Kučera
Zářijový pražský sraz spolku OpenAlt se koná již tento čtvrtek – 20. 9. 2018 od 18:00 v Radegastovně Perón (Stroupežnického 20, Praha 5). Tentokrát bez oficiální přednášky, ale zato s dobrým jídlem a pivem – volná diskuse na téma IoT, CNC, svobodný software, hardware a další hračky.
Přidat komentář

9.9.2018 14:15 /Redakce Linuxsoft.cz
20.9.2018 proběhne v pražském Kongresovém centru Vavruška konference Mobilní řešení pro business. Návštěvníci si vyslechnou mimo jiné přednášky na témata: Nejdůležitější aktuální trendy v oblasti mobilních technologií, správa a zabezpečení mobilních zařízení ve firmách, jak mobilně přistupovat k informačnímu systému firmy, kdy se vyplatí používat odolná mobilní zařízení nebo jak zabezpečit mobilní komunikaci.
Přidat komentář

12.8.2018 16:58 /František Kučera
Srpnový pražský sraz spolku OpenAlt se koná ve čtvrtek – 16. 8. 2018 od 19:00 v Kavárně Ideál (Sázavská 30, Praha), kde máme rezervovaný salonek. Tentokrát jsou tématem srazu databáze prezentaci svého projektu si pro nás připravil Standa Dzik. Dále bude prostor, abychom probrali nápady na využití IoT a sítě The Things Network, případně další témata.
Přidat komentář

16.7.2018 1:05 /František Kučera
Červencový pražský sraz spolku OpenAlt se koná již tento čtvrtek – 19. 7. 2018 od 18:00 v Kavárně Ideál (Sázavská 30, Praha), kde máme rezervovaný salonek. Tentokrát bude přednáška na téma: automatizační nástroj Ansible, kterou si připravil Martin Vicián.
Přidat komentář

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

> Poslední diskuze

31.7.2023 14:13 / Linda Graham
iPhone Services

30.11.2022 9:32 / Kyle McDermott
Hosting download unavailable

13.12.2018 10:57 / Jan Mareš
Re: zavináč

2.12.2018 23:56 / František Kučera
Sraz

5.10.2018 17:12 / Jakub Kuljovsky
Re: Jaký kurz a software by jste doporučili pro začínajcího kodéra?

Více ...

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