
=head1 NAME

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


=head1 INHERITANCE

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

 OODoc::Format::Pod is extended by
   OODoc::Format::PodTemplate


=head1 SYNOPSIS

 my $doc = OODoc->new(...);
 $doc->createManual
   ( 'pod'
   , format_options => [show_examples => 'NO']
   , append         => "extra text\n"
   );


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



=head1 METHODS


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

=over 4

Produces the chapter which shows inheritance relationships.

 Option  Defined in       Default   
 manual                   <required>
 output                   <required>

. manual OBJECT

. output IO::File

=back

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

=over 4

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

. append STRING|CODE

=over 4

Text to be added at the end of each manual page.
See L<formatManual(append)|"METHODS"> for an explanation.

=back

. format_options ARRAY

. manifest MANIFEST

. manual MANUAL

. workdir DIRECTORY

=back

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

=over 4

The OPTIONS are a collection of all options available to show* methods.
They are completed with the defaults set by L<createManual(format_options)|OODoc::Format/"METHODS">.

 Option  Defined in       Default   
 append                   ''        
 manual                   <required>
 output                   <required>

. append STRING|CODE

=over 4

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 OODoc::Format::Pod subroutine showChapter 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>.

=back

. manual MANUAL

. output FILE

=back

$obj-E<gt>B<link>(MANUAL, OBJECT, [TEXT])

=over 4

Create the text for a link which refers to the OBJECT.  The link will be
shown somewhere in the MANUAL.  The TEXT will be displayed is stead
of the link path, when specified.

=back

$obj-E<gt>B<showChapterIndex>(FILE, CHAPTER, INDENT)

=over 4

=back

$obj-E<gt>B<writeTable>

=over 4

 Option  Defined in       Default   
 ARRAY                    <required>
 header                   <required>
 output                   <required>
 widths                   C<undef>  

. ARRAY -OF-ARRAYS

=over 4

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

=back

. header ARRAY

. output FILE

. widths ARRAY

=back

=head2 Initiation


OODoc::Format::Pod-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::Pod-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::Pod-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:> cannot write pod manual at $manfile: $!


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<Error:> no directory to put pod for $name in


I<Error:> no directory to put pod manual for $name in


I<Error:> no package name for pod production


I<Error:> no package name for pod production


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

L<createManual(format_options)|OODoc::Format/"METHODS"> or L<OODoc::createManual(format_options)|OODoc/"Formatter">
can be used with a list of formatting options which are passed to
OODoc::Format::Pod 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)|"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 L<chapterInheritance()|"METHODS"> 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.


