=encoding utf8

=head1 NAME

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

=head1 INHERITANCE

 OODoc::Format::Pod2
   is an OODoc::Format::Pod
   is an OODoc::Format
   is an OODoc::Object

 OODoc::Format::Pod2
   is an OODoc::Format::TemplateMagic

=head1 SYNOPSIS

  my $doc = OODoc->new(...);
  $doc->formatter('pod2')->createPages(
     manual_options => [ show_examples => 'NO' ],
  );

=head1 DESCRIPTION

Create manual pages in the POD syntax, using the Template::Magic
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::Template::Magic>.

Extends L<"DESCRIPTION" in OODoc::Format::TemplateMagic|OODoc::Format::TemplateMagic/"DESCRIPTION">.

Extends L<"DESCRIPTION" in OODoc::Format::Pod|OODoc::Format::Pod/"DESCRIPTION">.

=head1 OVERLOADED

Extends L<"OVERLOADED" in OODoc::Format::Pod|OODoc::Format::Pod/"OVERLOADED">.

=over 4

=item overload: B<'!='> (numeric different)

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'=='> (numeric equivalent)

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'bool'> 

Inherited, see L<OODoc::Object/"OVERLOADED">

=back

=head1 METHODS

Extends L<"METHODS" in OODoc::Format::TemplateMagic|OODoc::Format::TemplateMagic/"METHODS">.

Extends L<"METHODS" in OODoc::Format::Pod|OODoc::Format::Pod/"METHODS">.

=over 4

=item $obj-E<gt>B<zoneGetParameters>($zone|STRING)

Inherited, see L<OODoc::Format::TemplateMagic/"METHODS">

=back

=head2 Constructors

Extends L<"Constructors" in OODoc::Format::Pod|OODoc::Format::Pod/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Inherited, see L<OODoc::Object/"Constructors">

 -Option  --Defined in     --Default
  format    OODoc::Format    'pod2'
  index     OODoc::Format    <required>
  manifest  OODoc::Format    undef
  project   OODoc::Format    <required>
  version   OODoc::Format    <required>
  workdir   OODoc::Format    <required>

=over 2

=item format => 'pod*'|'html*'|PACKAGE

=item index => OODoc::Index

=item manifest => OBJECT

=item project => STRING

=item version => STRING

=item workdir => DIRECTORY

=back

=back

=head2 Attributes

Extends L<"Attributes" in OODoc::Format::Pod|OODoc::Format::Pod/"Attributes">.

=over 4

=item $obj-E<gt>B<format>()

Inherited, see L<OODoc::Format/"Attributes">

=item $obj-E<gt>B<index>()

Inherited, see L<OODoc::Format/"Attributes">

=item $obj-E<gt>B<manifest>()

Inherited, see L<OODoc::Format/"Attributes">

=item $obj-E<gt>B<manual>()

Inherited, see L<OODoc::Object/"Attributes">

=item $obj-E<gt>B<project>()

Inherited, see L<OODoc::Format/"Attributes">

=item $obj-E<gt>B<unique>()

Inherited, see L<OODoc::Object/"Attributes">

=item $obj-E<gt>B<version>()

Inherited, see L<OODoc::Format/"Attributes">

=item $obj-E<gt>B<workdir>()

Inherited, see L<OODoc::Format/"Attributes">

=back

=head2 Collected

Extends L<"Collected" in OODoc::Format::Pod|OODoc::Format::Pod/"Collected">.

=over 4

=item $obj-E<gt>B<publish>(\%options)

Inherited, see L<OODoc::Object/"Collected">

=back

=head2 Page generation

Extends L<"Page generation" in OODoc::Format::Pod|OODoc::Format::Pod/"Page generation">.

=over 4

=item $obj-E<gt>B<cleanup>($manual, $text, %options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<cleanupString>($manual, $string, %options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<createManual>(%options)

Inherited, see L<OODoc::Format::Pod/"Page generation">

 -Option  --Defined in        --Default
  append    OODoc::Format::Pod  ""
  manual    OODoc::Format       <required>
  project   OODoc::Format       <required>
  template                      <in code>

=over 2

=item append => STRING|CODE

=item manual => MANUAL

=item project => STRING

=item template => FILENAME

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

=back

=item $obj-E<gt>B<createOtherPages>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<createPages>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $any-E<gt>B<link>( $manual, $object, [$text, \%settings] )

Inherited, see L<OODoc::Format::Pod/"Page generation">

=item $obj-E<gt>B<removeMarkup>(STRING)

Inherited, see L<OODoc::Format::Pod/"Page generation">

=item $obj-E<gt>B<showChapter>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showChapterIndex>($file, $chapter, $indent)

Inherited, see L<OODoc::Format::Pod/"Page generation">

=item $obj-E<gt>B<showExamples>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showOptionExpand>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showOptionTable>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showOptionUse>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showOptionalChapter>($name, %options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showOptions>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showRequiredChapter>($name, %options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showStructureExpanded>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showStructureRefer>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showSubroutine>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showSubroutineDescription>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showSubroutineName>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showSubroutineUse>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<showSubroutines>(%options)

Inherited, see L<OODoc::Format/"Page generation">

=item $obj-E<gt>B<simplifyPod>($in, $out)

Inherited, see L<OODoc::Format::Pod/"Page generation">

=item $obj-E<gt>B<templateChapter>()

Z<>

=item $obj-E<gt>B<writeTable>(%options)

Inherited, see L<OODoc::Format::Pod/"Page generation">

=back

=head1 DETAILS

Extends L<"DETAILS" in OODoc::Format::Pod|OODoc::Format::Pod/"DETAILS">.

=head1 DIAGNOSTICS

=over 4

=item Error: cannot link to a $package

Cast by C<link()>

=item Fault: cannot read prelimary pod from $file: $!

Cast by C<simplifyPod()>

=item Fault: cannot write final pod to $file: $!

Cast by C<simplifyPod()>

=item Error: chapter without name in template

In your template file, a C<{chapter}> statement is used, which is
erroneous, because it requires a chapter name.
Cast by C<templateChapter()>

=item Error: illegal show option choice: $value

Cast by C<showOptions()>

=item Error: illegal value for show_option_table: $value

Cast by C<showSubroutine()>

=item Error: illegal value for show_sub_description: $value

Cast by C<showSubroutine()>

=item Error: illegal value for show_subroutine: $value

Cast by C<showSubroutine()>

=item Error: missing required chapter $name in $manual

Cast by C<showRequiredChapter()>

=item Warning: no meaning for container $tags in chapter block

Cast by C<templateChapter()>

=item Fault: write to $file failed: $!

Cast by C<simplifyPod()>

=back

=head1 SEE ALSO

This module is part of OODoc version 3.05,
built on December 22, 2025. Website: F<https://perl.overmeer.net/oodoc/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

