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



=head1 METHODS


$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<createIndexPages>(OPTIONS)

=over 4

 Option    Defined in  Default 
 manifest              C<undef>

. manifest MANIFEST

=back

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

=over 4

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

. 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

. manifest MANIFEST

. manual MANUAL

=over 4

The manual to be formatted.

=back

. workdir DIRECTORY

=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                 Defined in       Default   
 chapter                                 <required>
 manual                                  <required>
 output                                  <required>
 show_chapter_examples                   <true>    

. chapter CHAPTER

. manual MANUAL

. output FILE

. show_chapter_examples BOOLEAN

=back

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

=over 4

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

. examples ARRAY

. manual MANUAL

. output FILE

=back

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

=over 4

 Option   Defined in       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   Defined in       Default   
 manual                    <required>
 options                   <required>
 output                    <required>

. manual OBJECT

. options ARRAY

. output FILE

=back

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

=over 4

 Option   Defined in       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                  Defined in       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<showSubroutine>((@))

=over 4

 Option                  Defined in       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      Defined in       Default   
 manual                       <required>
 output                       <required>
 subroutine                   <required>

. manual OBJECT

. output FILE

. subroutine OBJECT

=back

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

=over 4

 Option      Defined in       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      Defined in       Default   
 manual                       <required>
 output                       <required>
 subroutine                   <required>

. manual OBJECT

. output FILE

. subroutine OBJECT

=back

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

=over 4

 Option                  Defined in       Default              
 manual                                   <required>           
 output                                   <selected filehandle>
 show_described_options                   'EXPAND'             
 show_described_subs                      '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_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 Initiation


OODoc::Format-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-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-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:> 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:> missing required chapter $name in $manual


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.

I<Warning:> unknown subroutine type $type for $name in $manual







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


