=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     --Default
 container    <required>
 description  ''
 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.

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.

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.

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

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

Error: no text container specified for the $type object

=over 4

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.

=back

=head1 SEE ALSO

This module is part of OODoc distribution version 1.05,
built on January 26, 2009. Website: F<http://perl.overmeer.net/oodoc/>

=head1 LICENSE

Copyrights 2003-2009 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>