
=head1 NAME

OODoc::Manual - one manual about a package


=head1 INHERITANCE

 OODoc::Manual
   is a OODoc::Object


=head1 SYNOPSIS

 my $doc    = OODoc->new(...);
 my $manual = OODoc::Manual->new(name => ..., source => ...);

 $doc->manual($manual);
 my @manual = $doc->manualsForPackage('Mail::Box');

 print $manual->name;
 print $manual->package;


=head1 DESCRIPTION

The C<OODoc::Manual> object contains information of a singel manual page.
More than one manual can be related to a single package.


=head1 OVERLOADED


overload: B<cmp>

=over 4

String comparison takes place between a manual name and another
manual name which may be a manual object or any other string or
stringifyable object.

I<Example:> 

 if($manual eq 'OODoc') ...
 if($man1 eq $man2) ...
 my @sorted = sort @manuals;    # implicit calls to cmp

=back

overload: B<stringification>

=over 4

Used in string context, a manual produces its name.

=back


=head1 METHODS


=head2 Constructors


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

=over 4

 Option        Defined in       Default   
 distribution                   <required>
 package                        <required>
 parser                         <required>
 pure_pod                       <false>   
 source                         <required>
 stripped                       undef     
 version                        <required>

. distribution STRING

. package STRING

=over 4

The name of the package which is described by this manual.

=back

. parser OBJECT

=over 4

The parser which produces this manual page.  This parameter is needed
to be able to low-level format the text blocks.

=back

. pure_pod BOOLEAN

=over 4

Some documentation is stored in files which look like a module,
but do not contain any code.  Their filenames usually end with C<.pod>.

=back

. source STRING

=over 4

The file where the manual was found in, or in some cases some other
string which explains where the data came from.

=back

. stripped STRING

=over 4

The file where the stripped code is written to.

=back

. version STRING

=back

=head2 Attributes


$obj-E<gt>B<distribution>

=over 4

Returns the distribution which includes this manual.

=back

$obj-E<gt>B<isPurePod>

=over 4

Returns whether this package has real code related to it.

=back

$obj-E<gt>B<package>

=over 4

Returns the package of the manual.

=back

$obj-E<gt>B<parser>

=over 4

Returns the parser which has produced this manual object.

=back

$obj-E<gt>B<source>

=over 4

Returns the source of this manual information.

=back

$obj-E<gt>B<stripped>

=over 4

The name of the produced stripped package file.

=back

$obj-E<gt>B<version>

=over 4

Returns the version of this manual information.

=back

=head2 Collected


$obj-E<gt>B<chapter>(NAME|OBJECT)

=over 4

When a NAME (a string) given, the chapter with that name is returned, or
C<undef> when it is not known.  With an OBJECT, that object is added to
the list of chapters.

=back

$obj-E<gt>B<chapters>([CHAPTERS])

=over 4

Returns the ordered list of chapter object for this manual.

=back

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

=over 4

All diagnostic messages of all chapters for this manual together.

 Option  Defined in  Default
 select              []     

. select ARRAY

=over 4

Select only the diagnostic message of the specified types (case
insensitive).  Without any type, all are selected.

=back

=back

$obj-E<gt>B<examples>

=over 4

All examples of all chapters within this manual together, especially
useful for counting.

I<Example:> 

 print scalar $manual->examples;

=back

$obj-E<gt>B<name>

=over 4

Returns the name of the manual, which is found in the NAME chapter.

=back

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

=over 4

Returns the subroutine with the specified NAME as object reference.  When
the manual is part of a package description which is spread over multiple
manuals, then these other manuals will be searched as well.

=back

$obj-E<gt>B<subroutines>

=over 4

All subroutines of all chapters within this manual together, especially
useful for counting.

I<Example:> 

 print scalar $manual->subroutines;

=back

=head2 Inheritance knowledge


$obj-E<gt>B<all>(METHOD, PARAMETERS)

=over 4

Call L<OODoc::Text::Structure::all()|OODoc::Text::Structure/"Collected"> on all chapters, passing the METHOD
and PARAMETERS.  In practice, this means that you can simply collect
kinds of information from various parts within the manual page.

I<Example:> 

 my @diags = $manual->all('diagnostics');

=back

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

=over 4

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

=back

$obj-E<gt>B<extraCode>

=over 4

Returns a list of manuals which contain extra code for this package.

=back

$obj-E<gt>B<inherited>(SUBROUTINE|OPTION)

=over 4

Returns whether the SUBROUTINE or OPTION was defined by this manual page,
or inherited from it.

=back

$obj-E<gt>B<ownSubroutines>

=over 4

Returns only the subroutines which are described in this manual page
itself.  L<subroutines()|OODoc::Manual/"Collected"> returns them all.

=back

$obj-E<gt>B<realizers>([PACKAGES])

=over 4

Returns a list of packages which can realize into this object
using Object::Realize::Later magic.  When PACKAGES (names or objects)
are specified, they are added first.

=back

$obj-E<gt>B<realizes>([PACKAGE])

=over 4

Returns the class into which this class can be realized.  This is
a trick of the Object::Realize::Later module.  The PACKAGE (name or
object) will be set first, if specified.

=back

$obj-E<gt>B<subClasses>([PACKAGES])

=over 4

Returns the names of all sub-classes (extensions) of this package.
When PACKAGES (names or objects) are specified, they are first added
to the list.

=back

$obj-E<gt>B<superClasses>([PACKAGES])

=over 4

Returns the super classes for this package.  PACKAGES (names or objects)
will be added to the list of superclasses first.

=back

=head2 Processing


$obj-E<gt>B<collectPackageRelations>

=over 4

=back

$obj-E<gt>B<expand>

=over 4

Add the information of lower level manuals into this one.

=back

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

=over 4

Merge two lists of structured text objects: "this" list and "super" list.
The "this" objects are defined on this level of inheritance, where the
"super" objects are from an inheritence level higher (super class).
The combined list is returned, where the inherited objects are
preferably included before the new ones.

Merging is a complicated task, because the order of both lists should be
kept as well as possible.

 Option     Defined in       Default                    
 container                   <required>                 
 equal                       C<sub {"$_[0]" eq "$_[1]"}>
 merge                       C<sub {$_[0]}>             
 super                       C<[]>                      
 this                        C<[]>                      

. container OBJECT

. equal CODE

=over 4

Define how can be determined that two objects are the same.  By default,
the stringification of both objects are compared.

=back

. merge CODE

=over 4

What to call if both lists contain the same object.  These two objects
will be passed as argument to the code reference.

=back

. super ARRAY

. this ARRAY

=back

$obj-E<gt>B<mostDetailedLocation>(OBJECT)

=over 4

The OBJECT (a text element) is lccated in some subsection, section or
chapter.  But the OBJECT may also be an extension to a piece of
documentation which is described in a super class with a location in
more detail.  The most detailed location for the description is returned.

=back

=head2 Tracing


$obj-E<gt>B<stats>

=over 4

Returns a string which displays some stats about the manual.

=back

=head2 Commonly used functions


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

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

=over 4

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

=back

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

OODoc::Manual-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

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

I<Error:> no distribution is specified for manual $name


I<Error:> no name in manual in $source

Each documentation part requires a chapter NAME which starts with
the manual name followed by a dash.  Apparently, this was not found
in the indicated file.

I<Error:> no source filename is specified for manual $name

You have to specify where you found the information for the manual.  This
does not need to be the name of an existing file, but usually it will be.

I<Error:> no version is specified for manual $name


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<Error:> package name is not specified

You try to instantiate a manual, but have not specified the name
of the package which is described in this manual, which is required.

I<Warning:> subroutine $name location conflict: $here and $there

Finding the optimal location to list a subroutine description is
a harsh job: information from various manual pages is being used.

It is not a problem to list the documentation of a certain method M
in module A in chapter "METHODS", section "General", subsection "X"
(which is abbreviated in the report as METHODS/General/X), and the
same method M in module A::B, which extends A, in chapter "METHODS"
without providing details about the section and subsection.  The in most
detail descripted location is used everywhere.

This warning means that the location of the method in this manual page
is not related to that of the same method in an other page.  For instance,
in the first page it is listed in chapter "METHODS", and in the second
in chapter "FUNCTIONS".

I<Error:> two chapters name $name in $filename line $ln1 and $ln2

The indicated file contains two chapters with the same name, which
is not permitted.  Join the contents of both parts.






=head1 REFERENCES

See the OODoc website at L<http://perl.overmeer.net/oodoc/> for more details.

=head1 COPYRIGHTS

Module version 0.09.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2003 by the author(s). All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.


