=encoding utf8

=head1 NAME

OODoc::Format::Pod - Produce POD pages from the doc tree

=head1 INHERITANCE

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

 OODoc::Format::Pod is extended by
   OODoc::Format::Pod2
   OODoc::Format::Pod3

=head1 SYNOPSIS

  my $doc = OODoc->new(...);
  $doc->formatter('pod3')->createPages(
     append         => "extra text\n",
     manual_options => [
        show_examples => 'NO'
     ],
  );

=head1 DESCRIPTION

Create manual pages in the POD syntax.  POD is the standard document
description syntax for Perl.  POD can be translated to many different
operating system specific manual systems, like the Unix C<man> system.

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

=head1 OVERLOADED

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

=over 4

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

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|OODoc::Format/"METHODS">.

=head2 Constructors

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

=over 4

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

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

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

=over 2

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

=item manifest => OBJECT

=item project => STRING

=item version => STRING

=item workdir => DIRECTORY

=back

=back

=head2 Attributes

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

=over 4

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

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

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

Inherited, see L<OODoc::Format/"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 Manual Repository

Extends L<"Manual Repository" in OODoc::Format|OODoc::Format/"Manual Repository">.

=over 4

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

=back

=head2 Page generation

Extends L<"Page generation" in OODoc::Format|OODoc::Format/"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<createManual>(%options)

The C<%options> are a collection of all options available to C<show*()> methods.
Improves base, see L<OODoc::Format/"Page generation">

 -Option  --Defined in     --Default
  append                     ''
  manual    OODoc::Format    <required>
  project   OODoc::Format    <required>
  template  OODoc::Format    undef

=over 2

=item append => STRING|CODE

Used after each manual page has been formatting according to the
standard rules.  When a STRING is specified, it will be appended to
the manual page.  When a CODE reference is given, that function is
called with all the options that L<showChapter()|OODoc::Format/"Page generation"> usually gets.

Using C<append> is one of the alternatives to create the correct
Reference, Copyrights, etc chapters at the end of each manual
page.  See L</Configuring>.

=item manual => MANUAL

=item project => STRING

=item template => LOCATION

=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] )

Create the text for a link which refers to the C<$object>.  The link will be
shown somewhere in the C<$manual>.  The C<$text> will be displayed is stead
of the link path, when specified.

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

There is (AFAIK) no way to get the standard podlators code to remove
all markup from a string: to simplify a string.  On the other hand,
you are not allowed to put markup in a verbatim block, but we do have
that.  So: we have to clean the strings ourselves.

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

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

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

Z<>

=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)

The POD is produced in the specified C<$in> filename, but may contain some
garbage, especially a lot of superfluous blanks lines.  Because it is
quite complex to track double blank lines in the production process,
we make an extra pass over the POD to remove it afterwards.  Other
clean-up activities may be implemented later.

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

Z<>

 -Option--Default
  header  <required>
  output  <required>
  rows    <required>
  widths  undef

=over 2

=item header => ARRAY

=item output => FILE

=item rows => ARRAY-OF-ARRAYS

An array of arrays, each describing a row for the output.  The first row
is the header.

=item widths => ARRAY

=back

=back

=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

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

B<. Example: format options>

  use OODoc;
  my $doc = OODoc->new(...);
  $doc->processFiles(...);
  $doc->prepare;
  $doc->formatter(pod =>
     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/"Page generation">.

B<. Example: appending text to a page>

  use OODoc;
  my $doc = OODoc->new(...);
  $doc->processFiles(...);
  $doc->prepare;
  $doc->formatter('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.

B<. Example: remove chapter inheritance>

  $doc->formatter('MyPod', %format_options);

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

The C<MyPod> package is extending the standard POD generator, by overruling
the default behavior of C<chapterInheritance()> by producing nothing.

B<. Example: changing the chapter's output>

  $doc->formatter('MyPod', %format_options);

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

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

      $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;
 }

B<. Example: adding to a chapter's output>

  $doc->formatter('MyPod', %format_options);

  package MyPod;
  use parent 'OODoc::Format::Pod';
  use Log::Report 'panic';

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

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

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

=head3 Configuring with OODoc::Template

When using 'pod2' in stead of 'pod' when L<OODoc::formatter()|OODoc/"Actions"> is called,
the L<OODoc::Format::Pod2|OODoc::Format::Pod2> 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.

B<. Example: formatting with template>

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

B<. Example: format options within template>

The template van look like this:

  {chapter NAME}
  some extra text
  {chapter OVERLOADED}
  {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 DIAGNOSTICS

=over 4

=item Error: cannot link to a $package

Z<>

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

Z<>

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

Z<>

=item Fault: cannot write prelimary pod manual to $file: $!

Z<>

=item Error: illegal show option choice: $value

Z<>

=item Error: illegal value for show_option_table: $value

Z<>

=item Error: illegal value for show_sub_description: $value

Z<>

=item Error: illegal value for show_subroutine: $value

Z<>

=item Error: manual definition requires manual object

A call to L<addManual()|OODoc::Object/"Manual Repository"> 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 Repository"> or L<mainManual()|OODoc::Object/"Manual Repository">.

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

Z<>

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

Z<>

=back

=head1 SEE ALSO

This module is part of OODoc version 3.02,
built on August 15, 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.

