NAME

Pod::Template - 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

DESCRIPTION

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.

Assume that you have a module and a template as outlined in the SYNOPOSIS. Running this template through Pod::Template will result in this documentation:

=pod

=head1 SYNOPSIS

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

=head2 Functions

=head2 print_me( $string )

Prints out its argument.

This subroutine returns 1 for success and undef for failure.

=cut

TEMPLATE RULES

Use =Include to specify which sources will be used:

=Include Some::Module

With the =Include directive, it is possible to specify an alternate name to use with =Insert statements:

=Include FileName as KnownName

If a file extension is not specified, =Include will look first for a .pm file, and then for a file without an extension. You may also specify the path (in which case the complete file name must be provided) to handle situations where there could be namespace collisions:

=Include Some::Module::File as SMFile
=Include Another/Module/File.pod as AMFile

The =Insert function works by including text from the named =Template directive until the first =cut or the next =Template directive. First specify the source, followed by ->, then the =Template directive name:

=Insert IncludedFile->marked_text

See the samples directory in the distribution for further examples on how to use Pod::Template.

METHODS

new( [lib => \@libs] )

Create a new instance of Pod::Template.

Optionally, you can provide the lib argument to change the library path that Pod::Template looks for files. This defaults to your @INC.

parse( template => $template_file );

Takes a template file and parses it, replacing all Insert directives with the requested pod where possible, and removing all Include directives.

Returns true on success and false on failure.

as_string

Returns the result of the parsed template as a string, ready to be printed.

GLOBAL VARIABLES

$Pod::Template::WARNINGS

If this variable is set to true, warnings will be issued when conflicting directives or possible mistakes are encountered. By default this variable is true.

$Pod::Template::DEBUG

Set this variable to true to issue debug information when Pod::Template is parsing your template file.

This is particularly useful if Pod::Template is generating output you are not expecting. The default value is false.

EXAMPLES

See the samples directory in the distribution for examples on how to use Pod::Template.

SEE ALSO

If this templating system is not extensive enough to suit your needs, you might consider using Mark Overmeer's OODoc.

AUTHOR

This module by Jos Boumans kane@cpan.org.

COPYRIGHT

This module is copyright (c) 2003 Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

cpanm Pod::Template

perl -MCPAN -e shell
install Pod::Template