Pod::Template 0.02 review

Pod::Template is a Perl module for building pod documentation from templates. SYNOPSIS ### As a module ### use Pod::Te

License: Perl Artistic License File size: 7K Developer: Jos Boumans

0

Pod::Template is a Perl module for building pod documentation from templates.

SYNOPSIS

### As a module ###
use Pod::Template;
my $parser = new Pod::Template;
$parser->parse( template => 'documentation.ptmpl' );

print $parser->as_string


### As a script ###
$ podtmpl -I dir1 -I dir2 documentation.ptmpl


### A simple module prepared to use Pod::Template ###
package My::Module;

=Template print_me
=head2 print_me( $string )

Prints out its argument.

=cut

sub print_me { print shift; return 1 }


### A simple pod file named Extra/Additional.pod ###
=pod
=Template return_vals

This subroutine returns 1 for success and undef for failure.

=cut


### A simple Pod::Template template ###
=Include My::Module
=Include Extra/Additional.pod as Extra

=pod

=head1 SYNOPSIS

use My::Module

My::Module::print_me('some text');

=head2 Functions

=Insert My::Module->print_me

=Insert Extra->return_vals

=cut

Writing documentation on a project maintained by several people which spans more than one module is a tricky matter. There are many things to consider:

Location
Should pod be inline (above every function), at the bottom of the module, or in a distinct file? The first is easier for the developers, but the latter two are better for the pod maintainers.

Order
What order should the documentation be in? Does it belong in the order in which the functions are written, or ordered by another principle, such as frequency of use or function type? Again, the first option is better for the developers, while the second two are better for the user.

References
How should a function in another file be mentioned? Should the documentation simply say 'see Other::Module', or should it include the relevant section? Duplication means that the documentation is more likely to be outdated, but it's bad for a user to have to read numerous documents to simply find out what an inherited method does.

Headers & Footers
What should be done with standard headers and footers? Should they be pasted in to every file, or can the main file be assumed to cover the entire project?

Pod::Template offers a solution to these problems: documentation is built up from templates.

Requirements:
Perl