Egyszerű régi dokumentáció

A sima régi dokumentáció ( eng.  Plain old documentation , rövidítve pod ; jelentése közel áll az eredeti orosz kifejezéshez -- " Good Old Documentation " ) egy egyszerű jelölőnyelv , amelyet a Perl programozási nyelv dokumentálására használnak .

Eszköz

A Pod-ot egyszerű és letisztult nyelvnek tervezték, minimális hasznos szintaxissal. Szándékosan kizárja a betűtípusok, képek, színek vagy táblázatok leírására szolgáló mechanizmusokat. Bár a Pod nem olyan kifejező, mint az olyan nyelvek, mint az XML vagy a LaTeX , a szerzők szándékosan feláldozták a kifejezőkészséget az egyszerűség és a kényelem érdekében [1] . A pod fejlesztés fő céljai a következők:

Ezt a formátumot a perlpod kézikönyve írja le , néhány pod fordító pedig a pod2man , pod2html és pod2text kézikönyvben . Bár a perlpod kézikönyv szerzői rámutatnak, hogy a pod képességei valószínűleg nem elegendőek ahhoz, hogy könyveket írjanak rá [2] , valójában vannak olyan könyvek, amelyeket a pod kiterjesztett változatában írtak. Ez a kibővített verzió tartalmazza a táblázat formázását és a lábjegyzeteket, és az O'Reilly & Associates több Perlről szóló könyvet is felhasznált (leghíresebbek a Perl programozás [1] Larry Walltól, Tom Christiansentől és John Orvanttól). A pod egy másik kiterjesztett változata, a mod, Mark Jason Dominus en:Higher-Order Perl könyvében szerepelt.

A szoftver beépített POD-dokumentációjának használata

A programba épített formázott POD dokumentációt a mellékelt megjelenítő segédprogrammal olvashatja el:

% perldoc program_a_poddal % perldoc perlpod

Ezenkívül a POD-dokumentáció nagyon könnyen olvasható, ha egy modul forráskódját nézzük.

A POD formátumú leírás a perl segédprogrammal weblappá konvertálható:

%pod2html --outfile = program.html program_with_pod

A dokumentáció egyszerű szöveges formátumba konvertálásához a következőket használhatja:

pod2text fájlnév.pm > fájlnév.txt


Mintakód

A fájl végéhez hozzáadott POD dokumentáció:

#!/usr/local/bin/perl szia (); sub hello { print "Hello, world!\n" ; } __END__ # Üres karakterlánc szükséges =head1 NÉV # Program vagy modul neve =head1 ÖSSZEFOGLALÁS # Egy sor a modul vagy program működését írja le =head1 LEÍRÁS # Dokumentációs tömb =head1 AUTHOR # Ki vagy te =head1 BUGS # Mi történt rosszul =head1 LÁSD MÉG # további információ

Jegyzetek

  1. ↑ 1 2 Larry Wall, Tom Christiansen, John Orvant. Perl programozás = Programozás Perl. - "Symbol-Plus", 2010. - S. 686-703. — ISBN 5-93286-020-0 .
  2. ↑ "A Pod formátum nem feltétlenül elegendő egy könyv megírásához" . Letöltve: 2009. július 8. Az eredetiből archiválva : 2009. július 10..