Motivation

Motivation Install Example Tricks

While I just love my own BiteMarks mark-up language, it is hardly a standard and it is maintained only by me, whenever I feel like it. And I am a lazy soul.

So for those who want something more standard, and better documented, I offer these notes on use Perl's wonderful POD (Plain Old Documentation) system. POD is a mega-lightweight mark-up language. Any PERL installation comes with translators from POD to:

• html
• latex
• text

POD is very well documented all over the place; e.g. at PerlDoc. Every PERL distribution comes with hundreds of worked examples of POD (on my machine, it can be found at c:/cygwin/lib/perl5/5.6.1/Pods).

Install

Motivation Install Example Tricks

Download mypod.zip and unpack it all into the same directory.

Write some file in POD syntax, e.g. ab3.pl. Then call the script as follows:

bash mypod ab3

This will generated ab3.html.

Example

Motivation Install Example Tricks

ab3.pl: sample input (using POD to document a Prolog program).

ab3.html: sample output.

Tricks

Motivation Install Example Tricks

The mypod shell script implements some nice tricks.

Pod2Html fails if the file is in DOS format, not UNIX. So we need to do the right new line conversions.

dos2unix() {
   cat $1 | perl -e \
    'while($l=<>){$l 
             =~ s/\015\012$/\012/;print($l);}'             
}

Also, its good practice to run the PERL podchecker utility to looks for common POD errors, before running POD.

for i in $*
do
        if podchecker $i.$thing 
	then
          dos2unix $i.$thing > mypod$$.$thing
          pod2html -back $back         \
                    -css $style        \
                    -title $i          \
                    mypod$$.$thing > $i.html
	  rm mypod$$.$thing
       fi 
done