=head1 NAME

OODoc::Format - base class for all OODoc formatters

=head1 INHERITANCE

 OODoc::Format
   is a OODoc::Object

 OODoc::Format is extended by
   OODoc::Format::Html
   OODoc::Format::Pod

=head1 SYNOPSIS

 # Never instantiated directly.

=head1 DESCRIPTION

A formater produces manual pages in some way or an other which contain
(parts of) the module documentation.  Each formatter class is based on
this OODoc::Format class, which should not be instantiated directly.
By far most users will never explicitly create a formatter by themselves:
it is created implicitly when L<OODoc::create()|OODoc/"Formatter"> is called on a L<OODoc|OODoc>
object.

Currently available formatters:

=over 4

=item * L<OODoc::Format::Pod|OODoc::Format::Pod>

Simple formatter, which has the layout of the produced POD manual pages
hard-coded in it's body.  The only way to adapt the structure of the
pages is by extending the class, and thereby overrule some of the
methods which produce the text.  Not much of a problem for experienced
Object Oriented programmers.

=item * L<OODoc::Format::Pod2|OODoc::Format::Pod2>

This formatter uses the same methods to generate the manual page as
defined by L<OODoc::Format::Pod|OODoc::Format::Pod>, but the general layout of the page
can be configured using templates.

You have to install L<Bundle::Template::Magic> to use this feature.

=item * L<OODoc::Format::Pod3|OODoc::Format::Pod3>

The whole formatter, implemented as template in L<OODoc::Template|OODoc::Template>, a
very light weighted template system.

You have to install L<OODoc::Template> to use this feature.

=item * L<OODoc::Format::Html|OODoc::Format::Html>

Produce HTML by filling in templates. This module requires
L<Bundle::Template::Magic> and the ability to run cgi scripts.

=back

=head1 OVERLOADED

=head1 METHODS

=head2 Constructors

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

=over 4

 Option  --Default
 manifest  undef
 project   <required>
 version   <required>
 workdir   <required>

. manifest => OBJECT

. project => STRING

=over 4

The short name of this project (module), set by L<OODoc::new(project)|OODoc/"METHODS">.

=back

. version => STRING

=over 4

Many manual pages will contain the version of the project.  This can
be any STRING, although blanks are not advised.

=back

. workdir => DIRECTORY

=over 4

The DIRECTORY where the output will be placed.  If it does not exist,
it will be created for you.

=back

=back

=head2 Inheritance knowledge

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

=over 4

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

=back

=head2 Attributes

$obj-E<gt>B<manifest>

=over 4

Returns the L<OODoc::Manifest|OODoc::Manifest> object which maintains the names
of created files.

=back

$obj-E<gt>B<project>

=over 4

Returns the name of this project.

=back

$obj-E<gt>B<version>

=over 4

Returns the version string of this project.  This version may
contains any character, so should be handled with care.

=back

$obj-E<gt>B<workdir>

=over 4

Returns the name of the work directory: the top location for all
the output files.

=back

=head2 Page generation

$obj-E<gt>B<cleanup>(MANUAL, STRING)

=over 4

Takes the STRING and cleans it up to be in the right format for the
current formatter.  The cleaning up is parser dependent, and therefore
the parser of the manual is addressed to do the work.

=back

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

=over 4

 Option        --Default
 append          undef
 format_options  []
 manual          <required>
 project         <required>
 template        undef

. append => STRING|CODE

. format_options => ARRAY

=over 4

An ARRAY which contains a list of options which are the defaults
for formatting a chapter.

=back

. manual => MANUAL

=over 4

The manual to be formatted.

=back

. project => STRING

=over 4

The name of this project, which will appear on many pages.

=back

. template => LOCATION

=over 4

Some formatters support templates to descibe the output of the pages.
The valid values for this option differs per formatter.

=back

=back

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

=over 4

Create other pages which come with the set of formatted manuals.  What
the contents of these pages is depends on the formatter.  Some formatters
simply ignore the functionality of this method as a whole: they do not
support data-files which are not manuals.

 Option --Default
 process  undef
 source   undef
 verbose  0

. process => REGEXP

=over 4

Selects files to be processed from the source directory.  Other files
are copied without modification.  What happens with the selected
files is formatter dependent.

=back

. source => DIRECTORY

=over 4

The location of the DIRECTORY which contains files which are part of
the produced set of documentation, but not copied per manual page
but only once.

=back

. verbose => INTEGER

=back

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

=over 4

You can pass all OPTIONS about formatting to this method.  They will passed
to the related methods.  So: the list of options you can pass here is much
longer: the combination of everything possible for all show* methods.

 Option                    --Default
 chapter                     <required>
 manual                      <required>
 output                      <required>
 show_inherited_chapters     'REFER'
 show_inherited_sections     'REFER'
 show_inherited_subsections  'REFER'

. chapter => CHAPTER

. manual => MANUAL

. output => FILE

. show_inherited_chapters => 'NO'|'REFER'|'EXPAND'

. show_inherited_sections => 'NO'|'REFER'|'EXPAND'

=over 4

REFER means that inherited sections are simply listed as reference
to the manual page which describes it.

=back

. show_inherited_subsections => 'NO'|'REFER'|'EXPAND'

=back

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

=over 4

 Option  --Default
 examples  <required>
 manual    <required>
 output    <required>

. examples => ARRAY

. manual => MANUAL

. output => FILE

=back

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

=over 4

 Option --Default
 default  <required>
 manual   <required>
 option   <required>
 output   <required>

. default => OBJECT

. manual => OBJECT

. option => OBJECT

. output => FILE

=back

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

=over 4

 Option --Default
 manual   <required>
 options  <required>
 output   <required>

. manual => OBJECT

. options => ARRAY

. output => FILE

=back

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

=over 4

 Option --Default
 default  <required>
 manual   <required>
 option   <required>
 output   <required>

. default => OBJECT

. manual => OBJECT

. option => OBJECT

. output => FILE

=back

$obj-E<gt>B<showOptionalChapter>(NAME, OPTIONS)

=over 4

=back

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

=over 4

The options shown are B<not> the OPTIONS passed as argument, but the
options which belong to the subroutine being displayed.

 Option                --Default
 manual                  <required>
 options                 <required>
 show_described_options  'EXPAND'
 show_inherited_options  'USE'

. manual => OBJECT

. options => ARRAY

. show_described_options => 'NO'|'LIST'|'USE'|'EXPAND'

. show_inherited_options => 'NO'|'LIST'|'USE'|'EXPAND'

=back

$obj-E<gt>B<showRequiredChapter>(NAME, OPTIONS)

=over 4

=back

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

=over 4

 Option               --Default
 show_chapter_examples  'EXPAND'

. show_chapter_examples => 'NO'|'EXPAND'

=over 4

The I<chapter examples> are all examples which are not subroutine
related: examples which come at the end of a chapter, section, or
subsection.

=back

=back

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

=over 4

=back

$obj-E<gt>B<showSubroutine>((@))

=over 4

 Option                --Default
 last                    0
 manual                  <required>
 output                  <selected filehandle>
 show_described_options  'EXPAND'
 show_diagnostics        'NO'
 show_examples           'EXPAND'
 show_inherited_options  'USE'
 show_option_table       'ALL'
 show_sub_description    'DESCRIBED'
 show_subroutine         'EXPAND'
 subroutine              <required>

. last => BOOLEAN

. manual => MANUAL

. output => FILE

. show_described_options => 'NO'|'LIST'|'USE'|'EXPAND'

. show_diagnostics => 'NO'|'EXPAND'

=over 4

Diagnostics (error and warning messages) are defined per subroutine,
but are usually not listed with the subroutine.  The POD formatter's
default behavior, for instance, puts them all in a separate DIAGNOSTICS
chapter per manual page.

=back

. show_examples => 'NO'|'EXPAND'

. show_inherited_options => 'NO'|'LIST'|'USE'|'EXPAND'

. show_option_table => 'NO'|'INHERITED'|'DESCRIBED'|'ALL'

. show_sub_description => 'NO'|'DESCRIBED'|'REFER'|'ALL'

=over 4

Included the description of the use of the subroutines, which
comes before the options are being explained.  C<NO> will cause
the description to be ignored, C<DESCRIBED> means that only
text which was written in the manual-page at hand is included,
C<REFER> means that a reference to inherited documentation is
made, and with C<ALL> the inherited texts are expanded into this
file as well.

=back

. show_subroutine => 'NO'|'NAMES'|'USE'|'EXPAND'

. subroutine => OBJECT

=back

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

=over 4

 Option    --Default
 manual      <required>
 output      <required>
 subroutine  <required>

. manual => OBJECT

. output => FILE

. subroutine => OBJECT

=back

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

=over 4

 Option    --Default
 last        0
 manual      <required>
 output      <required>
 subroutine  <required>

. last => BOOLEAN

. manual => OBJECT

. output => FILE

. subroutine => OBJECT

=back

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

=over 4

 Option    --Default
 manual      <required>
 output      <required>
 subroutine  <required>

. manual => OBJECT

. output => FILE

. subroutine => OBJECT

=back

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

=over 4

 Option                --Default
 manual                  <required>
 output                  <selected filehandle>
 show_described_options  'EXPAND'
 show_described_subs     'EXPAND'
 show_diagnostics        'NO'
 show_examples           'EXPAND'
 show_inherited_options  'USE'
 show_inherited_subs     'USE'
 show_option_table       'ALL'
 show_subs_index         'NO'
 subroutines             []

. manual => MANUAL

. output => FILE

. show_described_options => 'NO'|'LIST'|'USE'|'EXPAND'

. show_described_subs => 'NO'|'NAMES'|'USE'|'EXPAND'

. show_diagnostics => 'NO'|'EXPAND'

. show_examples => 'NO'|'EXPAND'

. show_inherited_options => 'NO'|'LIST'|'USE'|'EXPAND'

. show_inherited_subs => 'NO'|'NAMES'|'USE'|'EXPAND'

. show_option_table => 'NO'|'DESCRIBED'|'INHERITED'|'ALL'

. show_subs_index => 'NO'|'NAMES'|'USE'

. subroutines => ARRAY

=back

=head2 Commonly used functions

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

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

=over 4

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

=back

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

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

=over 4

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

=back

=head2 Manual Repository

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

=over 4

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

=back

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

=over 4

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

=back

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

=over 4

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

=back

$obj-E<gt>B<manuals>

=over 4

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

=back

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

=over 4

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

=back

$obj-E<gt>B<packageNames>

=over 4

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

=back

=head1 DIAGNOSTICS

Error: formatter does not know the version.

=over 4

=back

Error: formatter has no project name.

=over 4

A formatter was created without a name specified for the project at
hand.  This should be passed with L<new(project)|OODoc::Format/"METHODS">.

=back

Error: manual definition requires manual object

=over 4

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

=back

Warning: missing required chapter $name in $manual

=over 4

=back

Error: no working directory specified.

=over 4

The formatter has to know where the output can be written.  This
directory must be provided via L<new(workdir)|OODoc::Format/"METHODS">, but was not specified.

=back

Warning: unknown subroutine type $type for $name in $manual

=over 4

=back

=head1 SEE ALSO

This module is part of OODoc distribution version 1.03,
built on March 14, 2008. Website: F<http://perl.overmeer.net/oodoc/>

=head1 LICENSE

Copyrights 2003-2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>