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

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ů

8.5.2016 17:19 /Redakce Linuxsoft.cz
PR: Dne 26.5.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í, cloudové služby, infrastruktura cloudu, efektivní využití cloudu, možné nástrahy cloudů a jak se jim vyhnout
Přidat komentář

21.4.2016 8:01 /František Kučera
Spolek OpenAlt zve na 127. distribuovaný sraz příznivců svobodného softwaru a otevřených technologií (hardware, 3D tisk, SDR, DIY, makers…), který se bude konat ve čtvrtek 28. dubna od 18:00 v Radegastovně Perón (Stroupežnického 20, Praha 5).
Přidat komentář

2.3.2016 22:41 /Ondřej Čečák
Letošní ročník konference InstallFest již tento víkend!
Přidat komentář

14.2.2016 16:39 /Redakce Linuxsoft.cz
O víkendu 5. a 6. března 2016 proběhne na pražském Strahově 8. ročník tradiční konference InstallFest. Celkem za dva dny uvidíte ​30 přednášek​ a ​6 workshopů.
Přidat komentář

5.2.2016 17:38 /Petr Ježek
Utilitka z XFce "xfce4-power-manager" nejen umožňuje nastavení lhůty pro uspání či hybernaci, ale i zapínání a vypínání prezentačního módu pro nerušené sledování videí. Stačí ji nastavit v každém vybavenějším panelu a v jakémkoli nontiled WM/DE.
Přidat komentář

10.1.2016 11:32 /Pavel `Goldenfish' Kysilka
LinuxMarket změnil provozovatele. Nově jej provozuje Marek Pszczolka. Více info a detaily #1 a #2.
Přidat komentář

29.12.2015 11:38 /Ondřej Čečák
Ještě posledních pár dní můžete přidávat příspěvky nebo nápady na Install Fest 2016, který se bude konat 5. a 6. března 2016.
Přidat komentář

8.12.2015 11:36 /Petr Ježek
Logické se stává realitou. LibreOffice a Thunderbird se mají dle článku na Redditu stát protiváhou MS řešení (MS Office a Outlook).
Přidat komentář

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

> Poslední diskuze

10.6.2016 21:10 / pavel riha
FreeBSD 10.3 a virtualizace

8.6.2016 21:56 / Milan Gallas
Nevalidní prefix m

7.5.2016 14:58 / Teodor Komárek
Soubory

20.4.2016 0:07 / Jakub Cleing
Sázkový panel PHP FUSION

9.4.2016 9:43 / jiwopene@gmail.com
Re: problém s dpkg a nemožností instalovat

Více ...

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