
=head1 NAME

OODoc::Text - base class for all data which was found in a manual


=head1 INHERITANCE

 OODoc::Text
   is a OODoc::Object

 OODoc::Text is extended by
   OODoc::Text::Default
   OODoc::Text::Diagnostic
   OODoc::Text::Example
   OODoc::Text::Option
   OODoc::Text::Structure
   OODoc::Text::Subroutine


=head1 SYNOPSIS

 # Cannot be instantiated itself


=head1 DESCRIPTION




=head1 METHODS


overload: B<'""' (stringification)>

=over 4

Returned is the name of the text object.

=back

overload: B<'==' and '!='>

=over 4

Numeric comparison is used to compare to objects whether they are
identical.  String comparison is overloaded to compare the names
of the objects.

=back

overload: B<'cmp' (string comparison)>

=over 4

Names are compared.

=back

$obj-E<gt>B<name>

=over 4

The name of this text element.  Stringification is overloaded to call
this name method.

I<Example:> 

 print $text->name;
 print $text;   # via overload

=back

=head2 Attributes


$obj-E<gt>B<description>

=over 4

Returns the description text for this object.  Nearly all objects
contains some kind of introductory description.

=back

$obj-E<gt>B<findDescriptionObject>

=over 4

From the current object, search in the extends until an object is found
which has a content for the description field.

=back

$obj-E<gt>B<openDescription>

=over 4

Returns a reference to the scalar which will contain the description for
this object.

I<Example:> 

 my $descr = $text->openDescription;
 $$descr  .= "add a line\n";

=back

$obj-E<gt>B<type>

=over 4

Returns the type name of this data object.

=back

$obj-E<gt>B<where>

=over 4

Returns the source of the text item: the filename name and the line
number of the start of it.

=back

=head2 Container


$obj-E<gt>B<container>

=over 4

The text element which encapsulaters the text element at hand.  This
defines the structure of the documentation.
Only for chapters, this value will be undefined.

=back

$obj-E<gt>B<manual>

=over 4

Returns the manual object which contains this text element.

=back

=head2 Examples


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

=over 4

Add a new example (a OODoc::Text::Example object) to the list already in
this object.  You can not look for a specific because they have no real
name (only a sequence number).

=back

$obj-E<gt>B<examples>

=over 4

Returns a list of all examples contained in this text element.

=back

=head2 Initiation


OODoc::Text-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::Text-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::Text-E<gt>B<mkdirhier>(DIRECTORY)

=over 4

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

=back

$obj-E<gt>B<unique>

=over 4

Returns a unique id for this text item.  This is the easiest way to
see whether two references to the same (overloaded) objects point to
the same thing. The ids are numeric.

I<Example:> 

 if($obj1->unique == $obj2->unique) {...}
 if($obj1 == $obj2) {...}   # same via overload

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


