Pod Introduktion

Skrivet av nocturnal 8 februari, 2010 - 09:37

Pod är en förkortning och betyder Plain Old Documentation. Det är ett format som funnits ganska länge men främst inom Perl världen. Inget har hindrat andra språk att utveckla egna implementationer av Pod så klart. Jag ska kanske gå in mer på språkets historia här senare men just nu ska jag förklara lite om hur Pod fungerar. Pod har mest används för Perl dokumentation och moduler eftersom man enkelt kan inkludera Perl kod och få Perl tolken att hoppa över de stycken med dokumentation när modulen ska användas. Jag ska endast gå igenom formateringsfunktionerna Pod erbjuder. För mer information om något av det ni hittar här kan ni läsa perlpod dokumentationen in perlpod som ska inkluderas med Perl paketet.

Pod formatet erbjuder tre grunder i formatering. Vanliga paragrafer, citerande paragrafer och speciella funktionsparagrafer.

Vanliga Paragrafer

Vanliga paragrafer är all vanlig text som delas upp i stycken. Allt som skrivs på en rad hamnar i en vanlig paragraf, när raden bryts så avslutas första paragrafen och den andra paragrafen börjar. Detta är den första paragrafen.

Detta är den andra paragrafen. Väldigt enkelt.

Citerande Paragrafer

Dessa paragrafer formateras annorlunda och är för citat eller programmeringskod. Allt som ska sticka ut ur texten och formateras med tabbar som till exempel i programmeringskod och andra exempel. Ett vanligt exempel förutom programmeringskod är data som skrivs ut i en terminal av ett program. Detta kan vara allt från flera hundra rader till en ensam rad. Citerande paragrafer används genom att placera ett eller flera mellanslag eller tabbar framför varje rad som ska ingå i den citerande paragrafen. Detta gäller även tomma rader, finns det tomma rader i texten som ska citeras så måste även dessa rader börjas med ett mellanslag eller en tab annars avslutas paragrafen och återupptas vid nästa rad igen.

Här är ett exempel på en enkel citerande paragraf. Allt jag gjort är att placera ett mellanslag framför texten, detta anser jag vara den enklaste metoden för att skapa en citerande paragraf.

Det här är en citerande paragraf, som ni ser kan det vara vilken text som helst.

Här ser ni ett stycke kod med tabformatering. Denna formatering syns bättre när den är citerad i en paragraf på det här viset.

 #!/ust/bin/perl -w
 
 use strict;
 
 if(1 > 0) {
	print("Hejsan!\n");
 }
 
 exit(0);

Som ni ser använder jag här mycket radbrytningar eftersom det är en sak jag gör när jag skriver kod för att få den att se mer organiserad och strukturerad ut. Notvera även hur jag inte har placerat ett mellanrum framför tabben på rad 6 eftersom det krävs antingen tab eller mellanrum för att räknas som en citerande paragraf. Den citerande paragrafens formatering för att tabbar syns bättre och hjälper till att hålla kod snygg och organiserad även i exempel så att den blir lättare att läsa och förstå.
Funktionsparagrafer

En funktionsparagraf används för specialbehandling av hela bitar text, inte bara stycken och paragrafer. Funktionsparagrafer initieras av ett kommando och avslutas av ett annat kommando. De kan alltså pågå flera hundra rader och stycken innan de avslutas. Detta är vad som används när man inkluderar Perl kod i Pod formatering. Nedan har ni en lista på olika funktioner ni kan använda.

Jag ska nu förklara dessa funktioner mer i detalj.
Rubriker

Syntaxet för de här funktionerna är =head1-4 text. Alltså =head1, =head2, =head3, =head4 med text efter som blir rubrikens text. Detta är texten som visas i rubriken och i menyn för sidan.

Alla =head1 till =head4 funktioner används för att indexera dokumentet och skapa huvudrubriker. Från =head1 till =head4 skapas h1 till h4 taggar när Pod dokumentet formateras till HTML. De olika nivåerna från 1 till 4 används även för att skapa underrubriker i stycken. Gör du till exempel en =head1 med lite text och sedan en =head2 så kommer =head2 texten indenteras mer i indexeringsmenyn för sidan. Rubrikerna kan innehålla formateringsfunktioner som beskrivs mer nedan.
Listor

Med =over, =item och =back kommandon kan man skapa listor. Listan börjar med =over och då kan =over ta ett icke obligatoriskt argument som är antalet ems listan indenteras från kanten. Efter =over kommandot så börjar listan med =item som är varje föremål i listan. Kommandot =item tar text som argument och detta är texten som visas på den nivån i listan. Listan avslutas med =over kommandot. Det kan se ut så här till exempel.

 =over 8
 
 =item Lista 1
 
 Denna texten kommer att indenteras.
 
 =item Lista 2
 
 Glöm ej radbrytningar mellan listans föremål, det behövs för de flesta pod parsers.
 
 =item Lista 3
 
 Texten under =item indenteras till 8 em.
 
 =back

Detta är en lista med 3 föremål som indenteras 8 ems. När den formateras ser den ut så här.

Lista 1
    Denna texten kommer att indenteras.
Lista 2
    Glöm ej radbrytningar mellan listans föremål, det behövs för de flesta pod parsers.
Lista 3
    Texten under =item indenteras till 8 em.

Inkludera Perl Kod i Pod Filer

Här tar vi upp funktionsparagrafer som =cut. Cut avslutar Pod formateringen och låter dig inkludera riktig Perl kod som Perl tolken kan tolka och exekvera. Funktionen =pod gör att Perl tolken börjar läsa Pod formatering igen. För att avsluta en paragraf med Pod formaterad text skriver ni en tom rad och =cut. När ni sedan inkluderat Perl kod eller annat så avslutas den paragrafen genom att börja Pod paragrafen igen med =pod funktionen.

Nedan ser ni ett exempel på hur man kan inkludera Perl kod i en Pod fil och på så vis lägga sin dokumentation i samma fil som sin Perl kod.

 =head1 Funktioner
 
 Här finns lite funktioner.
 
 =head2 funktion1()
 
 Denna funktionen gör otroligt mycket viktiga saker.
 
 =cut
 
 sub funktion1 {
 	my ($viktigt) = @_;
 
 	print($viktigt);
 
 	return(1);
 }
 
 =pod
 
 Såg ni hur viktig den var?

Detta visar utmärkt hur ni kan dokumentera era Perl program med Pod. Det kan även användas till PWiki så klart. :-)

Det finns mer att säga om =begin, =end och =for men det sparar vi till en annan gång då vi kan fylla på med text här.
Formaterings Koder

I vanliga paragrafer och i vissa funktionsparagrafer så kan formaterings koder användas.

"I" -- Kursiv text: Kursiv text kan användas för att utmärka text eller enstaka ord.
"B" -- Fet text: Text i fet stil kan användas för att utmärka text eller enstaka ord.
"C" -- Kod: Detta används för att visa en bit kod eller en viss funkton i en maskinskrivsfont.
"L" -- Länk: Länkar är oftast länkar till olika manualer eller Perl moduler. Det kan användas för att visa externa länkar genom att helt enkelt lägga en komplett länk med http: i namn. Enligt perldoc perlpod ska man inte kunna ha en beskrivande text för externa länkar men PWiki implementationen av Pod::Xhtml har stöd för detta genom att ni skriver L, ni ser detta användas mycket på den här sidan där jag länkar till perldoc.perl.org. Argumentet namn kan ej innehålla tecken som '/' och '|'. Tecken som '<' och '>' ska matchas. Ni kan länka till en Perl manual genom att skriva L till exempel. Notera att namn inte kan innehålla mellanrum. Detta syntax kan även användas som referens för UNIX manualer. Till exempel L. Det finns mer att säga om L<> men det sparar vi till en annan gång.
"E" -- Undanta speciella tecken: Denna funktionen används för att undanta speciella tecken som man vill visa i sitt dokument. Till exempel kan en |, vertikal linje visas med E. Ett <, mindre än tecken, visas med E. Ett >, större än tecken, visas med E. Ett /, solidus, tecken visas med E. De tecken som har nämnts hittills används mest i L<...> eftersom vissa tecken inte är tillåtna där.
Det går även att ange HTML koder som argument till E<...>. Som till exempel E för att skriva ut ett é tecken.
Ett annat användningsområde är att skriva ut tecken med den hexadecimala, oktala eller den decimala koden som argument. Till exempel skriver vi ut en slash med E<0x2f> där vi använder den hexadecimala koden.
"F" -- Filnamn: Visa filnamn, argumentet är filnamnet som till exempel F som visar /etc/ntpd.conf. Dessa visas oftast i kursiv textstil.
"S" -- Icke radbrytande text: Med den här funktionen visar du text som ej ska brytas vid slutet av raden. Till exempel vissa korta programmeringsexempel som du hellre vill flytta ner till nästa rad än att de bryts av radens slut. Ett exempel är S<$x ? $y : $z> som ser ut så här $x ? $y : $z.
"X" -- Rubriklänk: Allt ni gör i ert Pod dokument indexeras och när dokumentet sedan formateras och visas i HTML så ser ni en innehållsförteckning längst upp. Detta är länkar till alla de olika =headN rubrikerna. Med X<...> funktionen kan ni skapa en länk till en rubrik i ert dokument. Till exempel så skriver ni X för att länka till början av rubriken för Formaterings Koder och det ser ut så här Formaterings Koder.
"Z<>" -- Nollning: Jag visste inte riktigt hur jag skulle översätta den här men jag kan beskriva hur koden fungerar. I det här dokumentet har jag använt Z<> ganska mycket för att visa olika Pod formaterings koder. Den används för att bryta Pod parsningen vid behov. Till exempel när man ska visa en text som N<3 för att visa att N variabeln är mindre än 3. Då vill koden som läser in Pod dokumentet se N< som början på en formaterings kod och siffran 3 som dess argument. För att förhindra detta placerar man en Z<> mellan N och <. Så här ser det ut i källkoden för Pod dokumentet N<3. Eller ett annat exempel som används ofta i det här dokumentet EZ<> för att visa E koden ni kan se ovan.

Ni kan kombinera formateringskoder i varandra för att visa saker som $a <=> $b med hjälp av följande kod C<$a E=E $b>. I nyare Perl versioner kan ni även använda dubbla mindre än eller större än tecken, < och >, för att visa sådana tecken på ett mer läsbart sätt utan ett behov för att undanta tecken. Detta är dock lite överkurs och därför går jag inte in på det mer. Ni kan läsa mer om Pod i perlpod dokumentationen.

Syftet med Pod

Det ursprungliga syftet med Pod var inte att erbjuda en uppsjö av funktioner utan att kunna erbjuda en enkelhet med allt som krävs av ett dokumentationsformat. Det har ju fungerat bra för Perl sedan 80-talet så Larry måste gjort något rätt. Efter allt så ser ju paragrafer ut som paragrafer, så de står ut visuellt. Pod är inte nödvändigtvis nog för att skriva en bok men det duger som ett idiotsäkert alternativ för online dokumentation. Det har skapats flera olika Pod implementationer som omvandlar Pod dokument till andra formateringar, till exempel pod2text, pod2html och pod2man som omvandlar till nroff formatet. Detta är bara några av de mer klassiska. PWiki implementationen är baserad på Pod::Xhtml modulen som ni hittar på cpan.
Kontrollera Pod Syntax

Här har ni ett kort script som använder sig av Pod::Checker modulen för att kontrollera syntaxet i Pod filer. Ni hittar även detta script i tools katalogen som bör finnas i er PWiki distribution.

 #!/usr/bin/perl -w
 
 use strict;
 use Pod::Checker;
 
 my $podsyntax;
 
 $podsyntax = podchecker($ARGV[0], \*STDERR);
 
 exit(0);

Referenser

Det mesta av den här informationen är tagen ur mitt huvud men som referens har jag haft perlpod dokumentationen öppen i en annan terminal hela tiden så viss text är direkt översatt och vissa exempel är kopierade från perlpod dokumentet som är skrivet på engelska.

Bokmärk/Sök inlägget med:

Lägg till ny kommentar

Projekt