
=head1 NAME

OODoc::Text - text component as 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

The parsers (implemented in the L<OODoc::Parser|OODoc::Parser> classes) scan
the documentation as written down by the author of the module, and
build a tree of these OODoc::Text objects from it. Then, any formatter
(implemented by the L<OODoc::Format|OODoc::Format> classes) can take this tree of text
objects and convert it into manual pages.


=head1 OVERLOADED


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


=head1 METHODS


=head2 Constructors


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

=over 4

 Option       Defined in       Default   
 container                     <required>
 description                   C<''>     
 linenr                        <required>
 name                          undef     
 type                          <required>

. container OBJECT

=over 4

All text objects except chapters are contained in some other object.

=back

. description STRING

=over 4

The text which is contained in the body of this text item.  Often, this
is filled in later by L<openDescription()|OODoc::Text/"Collected">.

=back

. linenr INTEGER

. name STRING

=over 4

The name contains the main data about the text piece.

=back

. type STRING

=over 4

The type of this text element.  This is used for debugging only.

=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<container>([OBJECT])

=over 4

The text element which encapsulates 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<description>

=over 4

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

=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

$obj-E<gt>B<type>

=over 4

Returns the type name of this data object.

=back

=head2 Location


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

=over 4

Without a NAME, the manual of the text object is returned. With a NAME,
the manual with that name is returned, even when that does not have a
relation to the object: it calls L<OODoc::Object::manual()|OODoc::Object/"Manual Repository">.

=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

$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 Collected


$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

$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

=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<mkdirhier>(DIRECTORY)

OODoc::Text-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<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 text container specified for the $type object

Each text element is encapsulated by an other text element, except
chapters.  A value must be known for this C<container> option to
define the elements relative location.






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


