Pod::Template - Building pod documentation from templates.
### 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:
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.
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.
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.
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
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.
samples
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.
lib
@INC
Takes a template file and parses it, replacing all Insert directives with the requested pod where possible, and removing all Include directives.
Insert
Include
Returns true on success and false on failure.
Returns the result of the parsed template as a string, ready to be printed.
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.
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.
See the samples directory in the distribution for examples on how to use Pod::Template.
If this templating system is not extensive enough to suit your needs, you might consider using Mark Overmeer's OODoc.
OODoc
This module by Jos Boumans kane@cpan.org.
kane@cpan.org
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.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install Pod::Template, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Template
CPAN shell
perl -MCPAN -e shell install Pod::Template
For more information on module installation, please visit the detailed CPAN module installation guide.