
=head1 NAME

OODoc::Format::PodTemplate - Produce POD pages from the doc tree with a template


=head1 INHERITANCE

 OODoc::Format::PodTemplate
   is a OODoc::Format::Pod
   is a OODoc::Format
   is a OODoc::Object


=head1 SYNOPSIS

 my $doc = OODoc->new(...);
 $doc->createManual
   ( 'pod2'   # or 'OODoc::Format::PodTemplate'
   , format_options => [show_examples => 'NO']
   );


=head1 DESCRIPTION

Create manual pages in the POD syntax, using the Text::MagicTemplate subroutine 
template system.  It may be a bit simpler to configure the outcome
using the template, than using L<OODoc::Format::Pod|OODoc::Format::Pod>, however you
first need to install L<Bundle::Text::MagicTemplate>.



=head1 METHODS


OODoc::Format::PodTemplate-E<gt>B<createManual>(OPTIONS)

=over 4

 Option          Defined in       Default   
 append          OODoc::Format::Pod  ''        
 format_options  OODoc::Format    []        
 manifest        OODoc::Format    C<undef>  
 manual          OODoc::Format    <required>
 template                         <in code> 
 workdir         OODoc::Format    <required>

. append STRING|CODE

. format_options ARRAY

. manifest MANIFEST

. manual MANUAL

. template FILENAME

=over 4

The default template is included in the DATA segment of
L<OODoc::Format::PodTemplate|OODoc::Format::PodTemplate>.  You may start your own template
by copying it to a file.

=back

. workdir DIRECTORY

=back

$obj-E<gt>B<templateChapter>

=over 4

=back

=head2 Initiation


OODoc::Format::PodTemplate-E<gt>B<new>(OPTIONS)

=over 4

See L<OODoc::Text::Diagnostic/"METHODS">

=back

=head2 Inheritance


$obj-E<gt>B<extends>([OBJECT])

=over 4

See L<OODoc::Object/"Inheritance">

=back

=head2 Commonly used functions


$obj-E<gt>B<filenameToPackage>(FILENAME)

OODoc::Format::PodTemplate-E<gt>B<filenameToPackage>(FILENAME)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<mergeObjects>(OPTIONS)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<mkdirhier>(DIRECTORY)

OODoc::Format::PodTemplate-E<gt>B<mkdirhier>(DIRECTORY)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<unique>

=over 4

See L<OODoc::Text/"METHODS">

=back

=head2 Manual database

All manuals can be reached everywhere in the program: it is a global
collection.

$obj-E<gt>B<addManual>(MANUAL)

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<mainManual>(NAME)

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<manuals>

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<manualsForPackage>(NAME)

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<packageNames>

=over 4

See L<OODoc::Object/"Manual database">

=back



=head1 DIAGNOSTICS

I<Error:> chapter without name in template.

In your template file, a {chapter} statement is used, which is
erroneous, because it requires a chapter name.

I<Error:> manual definition requires manual object

A call to L<addManual()|OODoc::Object/"Manual database"> expects a new manual object (a L<OODoc::Manual|OODoc::Manual>),
however an incompatible thing was passed.  Usually, intended was a call
to L<manualsForPackage()|OODoc::Object/"Manual database"> or L<mainManual()|OODoc::Object/"Manual database">.

I<Warning:> no meaning for container $container in chapter block\n"


I<Warning:> order conflict "$take" before "$insert" in $file line $number

The order of the objects in a sub-class shall be the same as that of
the super class, otherwise the result of merging of the information
received from both classes is undertermined.


=head1 DETAILS


=head2 Configuring

Probably, the output which is produced by the POD formatter is only a
bit in the direction of your own ideas, but not quite what you like.
Therefore, there are a few ways to adapt the output.

=head3 Configuring with format options

OODoc::Format::PodTemplate subroutine createManual option format_options or L<OODoc::createManual(format_options)|OODoc/"Formatter">
can be used with a list of formatting options which are passed to
OODoc::Format::PodTemplate subroutine showChapter.  This will help you to produce pages which have
pre-planned changes in layout.

I<Example:> format options


 use OODoc;
 my $doc = OODoc->new(...);
 $doc->processFiles(...);
 $doc->prepare;
 $doc->createManual(pod =>
    format_options => [ show_subs_index     => 'NAMES'
                      , show_inherited_subs => 'NO'
                      , show_described_subs => 'USE'
                      , show_option_table   => 'NO'
                      ]
   );

=head3 Configuring by appending

By default, the last chapters are not filled in: the C<REFERENCES> and
C<COPYRIGHTS> chapters are very personal.  You can fill these in by
extending the POD generator, as described in the next section, or take
a very simple approach simply using L<createManual(append)|OODoc::Format::Pod/"METHODS">.

I<Example:> appending text to a page


 use OODoc;
 my $doc = OODoc->new(...);
 $doc->processFiles(...);
 $doc->prepare;
 $doc->createManual('pod', append => <<'TEXT');

 =head2 COPYRIGHTS
 ...
 TEXT

=head3 Configuring via extension

OODoc is an object oriented module, which means that you can extend the
functionality of a class by creating a new class.  This provides an
easy way to add, change or remove chapters from the produced manual
pages.

I<Example:> remove chapter inheritance


 $doc->createManual('MyPod', format_options => [...]);

 package MyPod;
 use base 'OODoc::Format::Pod';
 sub chapterInheritance(@) {shift};

The C<MyPod> package is extending the standard POD generator, by overruling
the default behavior of OODoc::Format::PodTemplate subroutine chapterInheritance by producing nothing.

I<Example:> changing the chapter's output


 $doc->createManual('MyPod', format_options => [...]);

 package MyPod;
 use base 'OODoc::Format::Pod';

 sub chapterCopyrights(@)
 {   my ($self, %args) = @_;
     my $manual = $args{manual} or confess;
     my $output = $args{output} or confess;

     $output->print("\n=head2 COPYRIGHTS\n");
     $output->print($manual->name =~ m/abc/ ? <<'FREE' : <<'COMMERICIAL');
This package can be used free of charge, as Perl itself.
FREE
This package will cost you money.  Register if you want to use it.
COMMERCIAL

     $self;
 }

I<Example:> adding to a chapter's output


 $doc->createManual('MyPod', format_options => [...]);

 package MyPod;
 use base 'OODoc::Format::Pod';

 sub chapterDiagnostics(@)
 {   my ($self, %args) = @_;
     $self->SUPER::Diagnostics(%args);

     my $output  = $args{output} or confess;
     my $manual  = $args{manual} or confess;
     my @extends = $manual->superClasses;

     $output->print(\nSee also the diagnostics is @extends.\n");
     $self;
 }

=head3 Configuring with Text::MagicTemplate

When using 'pod2' in stead of 'pod' when L<createManual()|"METHODS"> is called,
the L<OODoc::Format::PodTemplate|OODoc::Format::PodTemplate> will be used.   It's nearly a drop-in
replacement by its default behavior.  When you specify
your own template file, every thing can be made.

See the manual page of Text::MagicTemplate subroutine .  You have to install
Bundle::Text::MagicTemplate subroutine  to get it to work.

I<Example:> formatting with template


 use OODoc;
 my $doc = OODoc->new(...);
 $doc->processFiles(...);
 $doc->prepare;
 $doc->createManual(pod2, template => '/some/file',
    format_options => [ show_subs_index     => 'NAMES'
                      , show_option_table   => 'NO'
                      ]
    )

I<Example:> format options within template


The template van look like this:

 {chapter NAME}
 some extra text
 {chapter OVERLOAD}
 {chapter METHODS show_option_table NO}

The formatting options can be added, however the syntax is quite sensitive:
not quotes, comma's and exactly one blank between the strings.





=head1 REFERENCES

See the OODoc website at L<$website> for more details.

=head1 COPYRIGHTS

Module version $version.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2001-2002 by the authors. All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.


