=head1 NAME

OODoc::Parser - base class for all OODoc parsers.

=head1 INHERITANCE

 OODoc::Parser
   is an OODoc::Object

 OODoc::Parser is extended by
   OODoc::Parser::Markov

=head1 SYNOPSIS

 # Never instantiated directly.

=head1 DESCRIPTION

A parser is used to process files which contain POD or contain code:
their filename extension is C<pod>, C<pm>, or C<pl> (actually, this
can be configured).

Currently distributed parsers:

=over 4

=item * L<OODoc::Parser::Markov|OODoc::Parser::Markov>

The Markov parser understands standard POD, but adds logical markup tags
and the C<M&lt;&gt;> links.

=back

=head1 OVERLOADED

=head1 METHODS

=head2 Constructors

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

=over 4

See L<OODoc::Object/"Constructors">

=back

=head2 Inheritance knowledge

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

=over 4

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

=back

=head2 Parsing a file

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

=over 4

Parse the specified input file into a code file and an object tree which
describes the pod.  Returned is a list of package objects which contain
the docs found in this file.

 Option--Default
 input   <required>
 output  <black hole>

. input => FILENAME

=over 4

The name of the input file.

=back

. output => FILENAME

=over 4

Where to write the produced code to.  If no filename is specified, the
platform dependend black hole is used (/dev/null on UNIX).

=back

=back

=head2 Formatting text pieces

After the manuals have been parsed into objects, the information can
be formatted in various ways, for instance into POD and HTML.  However,
the parsing is not yet complete: the structure has been decomposed 
with L<parse()|OODoc::Parser/"Parsing a file">, but the text blocks not yet.  This is because the
transformations which are needed are context dependent.  For each
text section L<cleanup()|OODoc::Parser/"Formatting text pieces"> is called for the final touch.

$obj-E<gt>B<cleanup>(FORMATTER, MANUAL, STRING)

=over 4

=back

=head2 Commonly used functions

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

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

=over 4

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

=back

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

OODoc::Parser-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:> The formatter type $class is not known for cleanup

Text blocks have to get the finishing touch in the final formatting
phase.  The parser has to fix the text block segments to create a
formatter dependent output.  Only a few formatters are predefined.

I<Warning:> Unknown option $name

You have used the option with $name, which is not defined with the
instantiation (the C<new> method) of this object.

I<Warning:> Unknown options @names

You have used more than one option which is not defined to instantiate
the object.

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

=head1 SEE ALSO

This module is part of OODoc distribution version 1.00,
built on June 14, 2007. Website: F<http://perl.overmeer.net/oodoc/>

=head1 LICENSE

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