Well, I use POD for my documentation efforts, and I like it because of the speed in which I can type it, and the easy way of generating other formats from the source file.

I made a small script that hacks the output of pod2html into seperate pages with a navigation bar on the side as show in the above link. Script follows (you might need to adapt it a bit if you want to use it): 

#!/usr/bin/perl -w
use strict;
use Pod::Html;
use File::Basename;
use vars qw/$TMPFILE/;


$TMPFILE='split-temp.html';

die <<"USAGE" unless @ARGV == 2;
usage: $0 cssfile podfile
USAGE

die "$!" unless -f $ARGV[1];

pod2html(
     -noindex,
     $ARGV[1],
     -outfile=>$TMPFILE);

my ($basename) = fileparse($ARGV[1],qw(.pod .pl .pm));

print "$ARGV[1] => $basename\n";

unless (-d $basename) {
    mkdir $basename or die "error creating $basename: $!";
}

open ORIG,"<",$TMPFILE or die "Cannot open $TMPFILE for reading: $!";
my $orig = join('',<ORIG>);
close ORIG;

$orig =~ s/<\/PRE>\n<PRE>/\n/isg;

my @orig = map { "$_\n" } split(/\n/,$orig);


# build the index

warn "Building index data\n";

my %anchor2page;
my @titles;
my @subtitles;
my $i = 0;
for(@orig) {
#    print $_;

    if (/<H1><A[^>]+>(.+?)<\/A>/) {
    $i++;
    $titles[$i] = $1;
    $subtitles[$i] = [];
    }
    if (/<H2><A NAME=\"([^\"]+)\">(.+?)<\/A><\/H2>/) {
    push @{$subtitles[$i]},[$1,$2];
    }
    if (/<A NAME=\"([^\"]+)\">(.+?)<\/A>/) {
    $anchor2page{$1} = "$basename$i.shtml?<!--#echo var=\"QUERY_STRING
+\" -->#$1";
    }
    s/<A HREF=\"(http\:\/\/[^\"]+)\">/<A HREF=\"$1\" TARGET=_top>/ig;
}



warn "Building pages\n";
# loop over file again and make pages

my $template = '';

my $csslink = qq(
<!--#if expr="\$QUERY_STRING != 'nocss'" -->
<link type="text/css" href="$ARGV[0]" rel="stylesheet">
<!--#endif -->
);


#get first part;


while (@orig) {
    local $_ = shift @orig;
    $_ .= $csslink if /<\/HEAD>/i;
    $template .= $_;
    last if /<BODY>/;
}

$template .= qq{
<table border=0 width=100%>
<tr>
<th width=80% align=left><a href="/ssp/" title="Web programming" class
+="home">\\X/</a> Web programming</th>
<!--#include virtual="/navi.shtml"-->
</table>
};


while(@orig) {
    local $_ = shift @orig;
    last if /<HR>/;
}

$i = 1;
my $reallylast = 0;
FILE:
while (1){
    warn "Building page $basename/$basename$i.shtml\n";
    open NEWFILE,">","$basename/$basename$i.shtml" or die "Error creat
+ing $basename/$basename$i.shtml: $!"; 
    print NEWFILE $template;
    my $filedata = '';
    local $_;
    my $title;
  SECTION:
    while ($_ = shift @orig) {
    s/<A HREF=\"\#([^\"]+)\">/<A HREF=\"$anchor2page{$1}\">/g;
    last SECTION if /<HR>/;
    $reallylast = 1,last SECTION if /<\/BODY>/;
    $title = $_,next if /<H1>/;
    $filedata .= $_;
    }
    
    my $navbar = "<H3>";
    $navbar .= "<A HREF=\"$basename".($i-1).".shtml?<!--#echo var=\"QU
+ERY_STRING\" -->\">&lt;&lt; Prev section</A> " if $i > 1;
    $navbar .= "<A HREF=\"$basename".($i+1).".shtml?<!--#echo var=\"QU
+ERY_STRING\" -->\">Next section &gt;&gt;</A>" unless $reallylast;
    $navbar .= "</H3>";



    my $index = "<div class=leftnav><table class=leftnav cellspacing=0
+ border=0 ><tr><th colspan=3 class=leftnav align=left>Index</th></tr>
+";
    
    for my $tnum (1 .. $#titles) {
    my $class = 'CLASS="leftnav"';
    my $mainbul = 'bullet.gif';
    if ($tnum == $i) {
        $class = 'CLASS="highlight"';
        $mainbul = 'bullet2.gif';
    }
    $index .= "<tr><td valign=top $class><img src=\"$mainbul\" alt=\">
+\"  width=8 height=16 border=0></td><td valign=top colspan=2 $class><
+A HREF=\"$basename$tnum.shtml?<!--#echo var=\"QUERY_STRING\" -->\">$t
+itles[$tnum]</A></td></tr>\n";
    if ($i == $tnum && $subtitles[$tnum]->[0]) {
        $class = 'CLASS="highlight2"';
        for my $subtitle (@{$subtitles[$tnum]}) {
            $index .= "<TR><TD $class><img src=\"nix.gif\" alt=\" \" w
+idth=1 height=1 border=0></TD><TD VALIGN=TOP $class><img src=\"bullet
+.gif\" alt=\">\" width=8 height=16  border=0></TD><TD VALIGN=TOP $cla
+ss><A HREF=\"$basename$i.shtml?<!--#echo var=\"QUERY_STRING\" -->#$su
+btitle->[0]\">$subtitle->[1]</A></TD></TR>\n";
        }
    }
    }
    $index .= qq(
<tr><td colspan=1 class="csslink"></td><td class="csslink" colspan=2>
<!--#if expr="\$QUERY_STRING" -->
<a class="csslink" href="<!--#echo var="SCRIPT_NAME" -->">[CSS ON]</a>
<!--#else -->
<a class="csslink" href="<!--#echo var="SCRIPT_NAME" -->?nocss">[CSS O
+FF]</a>
<!--#endif -->
</td></tr>
);


    $index .= "</table></div>";
    
    print NEWFILE qq(<table width=100% border=0><tr><td valign=top wid
+th=150 height=1>$index</td><td valign=top rowspan=2 class=content><di
+v class=rightcontent>$navbar$title$filedata$navbar</div>
</td></tr><tr><td height=80%></td></tr></table></BODY></HTML>);

    close NEWFILE;
    $i++;
    last FILE if $reallylast;
}

print "OK\n";
exit;

[download]
-- 
Joost       downtime n. The period during which a system
            is error-free and immune from user input.

[download]

In reply to Re: Creating Books and Manuals with Perl by Joost
in thread Creating Books and Manuals with Perl by skazat

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.