[Ottawa-pm] Generating dead-tree docs with Pod::Manual

[Yanick Champoux]

	At the meeting of last week, Dave and I were talking of Rose::DB.  At 
some point he mentioned that the documentation is a wee bit hard to 
follow, to which I replied that Pod::Manual might be able to help.  As 
there were no keyboards close by at the time, we both took note to 
discuss this in further details later on.  Well, now seems like a good 
'later on' moment. :-)

	In a nutshell, Pod::Manual has been born off my desire to easily gather 
the POD of several modules into a nice print-friendly format.  The 
principal features I was aiming for were:

	- Page numbering, with an index at the beginning and section titles 
given in the pages' header/footer.

	- Possibility to tinker the gathered POD to make it more 
print-friendly.  For example, all PODs from Rose::DB have the same 
License section.  I don't really need to have it printed for every 
module -- only once in an appendix would suffice.

	- Purtiness.


	The earlier versions of Pod::Manual would do the POD to PDF 
transformation via LaTeX.  Which is not so bad if you already have TeX 
installed on your system. But if it's not already there, tackling such a 
behemoth might be a rather strong turn-off.  I've glanced for a time at 
FOP-like transformations, but... aah... didn't fell in love with the 
technology.  I, however, found Prince, a very nice docbook-to-pdf piece 
of software.  All that it needs to transform vanilla-flavored docbook 
into a pdf document is a regular CSS stylesheet.  Prince itself is not 
free software, but they do give out a trial version (that can be used 
for a long as you want if it's for personal/non-profit purposes) of the 
software that adds a little 'P' logo to the first page of your printouts.

	To give a relevant example, here's the script that I used to generate 
my Rose::DB manual:


#!/usr/bin/perl

use strict;
use warnings;

use Pod::Manual;

my $manual = Pod::Manual->new(
	title => 'Rose::DB::Object',
         pdf_generator => 'prince'   # or 'latex'
);

$manual->add_chapters( qw/ Rose::DB::Object::Tutorial
                            Rose::DB::Tutorial
                            Rose::DB::Object
                            Rose::DB::Object::Metadata
                            Rose::DB::Object::Manager
                            Rose::DB::SQLite
                          / );

my $pdf_file = 'rose-db-object_manual.pdf';
$manual->save_as_pdf( $pdf_file );

print "pdf document '$pdf_file' created\n";

__END__

	Sample output of the LaTeX and Prince transforms are at 
http://babyl.dyndns.org/misc/rose-db-object-latex.pdf
and
http://babyl.dyndns.org/misc/rose-db-object-prince.pdf


	Pod::Manual is still very rough and need a lot of work, buuuuut if you 
feel like a brave beta-tester, it can be found on CPAN 
(http://search.cpan.org/dist/Pod-Manual/) .  Or if you feel like an 
even-braver contributor, the code is on GitHub: 
http://github.com/yanick/pod-manual/tree/master. (the codebase is 
probably going to be Moosified soon)  :-)

Enjoy!
`/anick