=encoding utf8
=head1 NAME
OODoc - object oriented production of code related documentation
=head1 INHERITANCE
OODoc
is a OODoc::Object
=head1 SYNOPSIS
use OODoc;
my $doc = OODoc->new(distribution => 'My Name', version => '0.02');
$doc->processFiles(workdir => $dest);
$doc->prepare;
$doc->create('pod', workdir => $dest);
$doc->create('html', workdir => '/tmp/html');
or use the oodist script
=head1 DESCRIPTION
OODoc stands for "Object Oriented Documentation": to produce manual-pages
in HTML or the usual man-page UNIX format, describing Perl programs.
The OO part of the name refers to two things: this module simplifies
writing documentation for Object Oriented programs, and at the same time,
it is Object Oriented itself: easily extensible.
Before you read any further, decide:
=over 4
=item 1
to use your own modified version of the mkdist and mkdoc scripts, as provided
in the examples which come with this module, or
=item 2
use the oodist, which is less flexible but much simpler, and only requires
some additions to your Makefile.PL.
=back
OODoc has been used for small and for very large modules. It can also
be used to integrate manual-pages from many modules into one homogeneous
set.
The documentation syntax can be changed, by configuring the parser
or adding a new one. The L<OODoc::Parser::Markov|OODoc::Parser::Markov> parser understands POD
and has additional logical markup tags. See L<OODoc::Parser|OODoc::Parser> about what
each parser needs to support.
The output is produced by formatters. The current implementation contains
two POD formatters and one HTML formatter. See L<OODoc::Format|OODoc::Format>.
Do not forget to B<read> the L<DETAILS> section, later on this manual-page to
get started. Please contribute ideas. Have a look at the main website
of this project at L<http://perl.overmeer.net/oodoc/>. That is also an
example of the produced output.
Extends L<"DESCRIPTION" in OODoc::Object|OODoc::Object/"DESCRIPTION">.
=head1 OVERLOADED
Extends L<"OVERLOADED" in OODoc::Object|OODoc::Object/"OVERLOADED">.
=head1 METHODS
Extends L<"METHODS" in OODoc::Object|OODoc::Object/"METHODS">.
=head2 Constructors
Extends L<"Constructors" in OODoc::Object|OODoc::Object/"Constructors">.
=over 4
=item OODoc-E<gt>B<new>(%options)
-Option --Default
distribution <required>
project <distribution>
version <from version or VERSION file>
=over 2
=item distribution => STRING
The name of the package, as released on CPAN.
=item project => STRING
A short description of the distribution, as will be shown on many places
in the produced manual pages and code. You can use the main package name,
or something which is nicer to read.
=item version => STRING
The version number as automatically included in all packages after
each package statement and on many places in the documentation. By
default the current directory is searched for a file named C<version>
or C<VERSION> which contains a number.
=back
=back
=head2 Inheritance knowledge
Extends L<"Inheritance knowledge" in OODoc::Object|OODoc::Object/"Inheritance knowledge">.
=over 4
=item $obj-E<gt>B<extends>( [$object] )
Inherited, see L<OODoc::Object/"Inheritance knowledge">
=back
=head2 Attributes
=over 4
=item $obj-E<gt>B<distribution>()
Returns the nice name for the distribution.
=item $obj-E<gt>B<project>()
Returns the general project description, by default the distribution name.
=item $obj-E<gt>B<version>()
Returns the version string for the distribution.
=back
=head2 Parser
=over 4
=item $obj-E<gt>B<processFiles>(%options)
-Option --Default
distribution <from main OODoc object>
manifest <source/>'MANIFEST'
notice ''
parser OODoc::Parser::Markov
select qr/\.(pod|pm)$/
skip_links []
source '.'
version <from source directory or OODoc object>
workdir <required>
=over 2
=item distribution => NAME
Useful when more than one distribution is merged into one set of
documentation.
=item manifest => FILENAME
The manifest file lists all files which belong to this distribution: packages,
pods, tests, etc. before the new pod files are created.
=item notice => STRING
Include the string (which may consist of multiple lines) to each of the
pm files. This notice usually contains the copyright message.
=item parser => CLASS|OBJECT
The parser CLASS or OBJECT to be used to process the pages.
=item select => ARRAY|REGEX|CODE
The files which contain documentation to be processed. You can provide
a list of filenames as array reference, a REGEX which is used to select
names from the manifest file, or a CODE reference which is used to
select elements from the manifest (filename passed as first argument).
Is your pod real pod or should it also be passed through the parser?
=item skip_links => ARRAY|STRING|REGEXP
Passed to L<OODoc::Parser::new(skip_links)|OODoc::Parser/"Constructors">.
=item source => DIRECTORY
The location where the files are located. This is useful when you collect
the documentation of other distributions into the main one. Usually in
combination with an undefined value for C<workdir>.
=item version => STRING
The version of the distribution. If not specified, the C<source>
directory is scanned for a file named C<version> or C<VERSION>. The
content is used as version value. If these do not exist, then the
main OODoc object needs to provide the version.
To make C<Makefile.PL> option C<VERSION_FROM> to work with this
seperate version file, that line should contain C<$VERSION = >.
=item workdir => DIRECTORY
Specify the directory where the stripped pm-files and the pod files
will be written to. Probably the whole distribution is collected on
that spot.
If you do not want to create a distribution, you may
specify C<undef> (still: you have to specify the option). In this
case, only the documentation in the files is consumed, and no files
created.
=back
=item $obj-E<gt>B<selectFiles>($which, LIST)
Returns two array references: the first with files to process, and the second
with files which do not need to be processed. $which comes from
L<processFiles(select)|OODoc/"Parser"> and the LIST are files from a manifest.
=back
=head2 Preparation
=over 4
=item $obj-E<gt>B<getPackageRelations>()
Compile all files which contain packages, and then try to find-out
how they are related.
=item $obj-E<gt>B<prepare>(%options)
Add information to the documentation tree about inheritance relationships
of the packages. C<prepare> must be called between L<processFiles()|OODoc/"Parser">
and L<create()|OODoc/"Formatter">.
=back
=head2 Formatter
=over 4
=item $obj-E<gt>B<create>($name|$class|$object, %options)
Create a manual for the set of manuals read so far. The manuals are
produced by different formatters which produce one page at a time.
Returned is the formatter which is used: it may contain useful information
for you.
The first, optional argument specifies the type of pages to be produced.
This can be either a predefined $name (currently available are C<pod>
and C<html> representing L<OODoc::Format::Pod|OODoc::Format::Pod> and L<OODoc::Format::Html|OODoc::Format::Html>
respectively), the name of a $class which needs to be instantiated,
or an instantiated formatter.
-Option --Default
append undef
format_options []
manifest <workdir>/MANIFEST
manual_format []
manual_templates undef
other_templates undef
process_files <formatter dependent>
select undef
workdir <required>
=over 2
=item append => STRING|CODE
The value is passed on to L<OODoc::Format::createManual(append)|OODoc::Format/"Page generation">,
but the behavior is formatter dependent.
=item format_options => ARRAY
Formatter dependent initialization options. See the documentation of
the formatter which will be used for the possible values.
=item manifest => FILENAME|undef
The names of the produced files are appended to this file. When undef
is given, no file will be written for this.
=item manual_format => ARRAY
Options passed to L<OODoc::Format::createManual(format_options)|OODoc::Format/"Page generation"> when
a manual page has to be produced. See the applicable formatter
manual page for the possible flags and values.
=item manual_templates => DIRECTORY
Passed to L<OODoc::Format::createManual(template)|OODoc::Format/"Page generation">, and defines the
location of the set of pages which has to be created for each manual
page. Some formatters do not support templates and the valid values
are formatter dependent.
=item other_templates => DIRECTORY
Other files which have to be copied
passed to L<OODoc::Format::createOtherPages(source)|OODoc::Format/"Page generation">.
=item process_files => REGEXP
Selects the files which are to be processed for special markup information.
Other files, like image files, will be simply copied. The value will be
passed to L<OODoc::Format::createOtherPages(process)|OODoc::Format/"Page generation">.
=item select => CODE|REGEXP
Produce only the indicated manuals, which is useful in case of merging
manuals from different distributions. When a REGEXP is provided, it
will be checked against the manual name. The CODE reference will be
called with a manual as only argument.
=item workdir => DIRECTORY
The directory where the output is going to.
=back
=item $obj-E<gt>B<stats>()
Returns a string which contains some statistics about the whole parsed
document set.
=back
=head2 Commonly used functions
Extends L<"Commonly used functions" in OODoc::Object|OODoc::Object/"Commonly used functions">.
=over 4
=item $obj-E<gt>B<filenameToPackage>($filename)
=item OODoc-E<gt>B<filenameToPackage>($filename)
Inherited, see L<OODoc::Object/"Commonly used functions">
=item $obj-E<gt>B<mkdirhier>($directory)
=item OODoc-E<gt>B<mkdirhier>($directory)
Inherited, see L<OODoc::Object/"Commonly used functions">
=back
=head2 Manual Repository
Extends L<"Manual Repository" in OODoc::Object|OODoc::Object/"Manual Repository">.
=over 4
=item $obj-E<gt>B<addManual>($manual)
Inherited, see L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<mainManual>($name)
Inherited, see L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<manual>($name)
Inherited, see L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<manuals>()
Inherited, see L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<manualsForPackage>($name)
Inherited, see L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<packageNames>()
Inherited, see L<OODoc::Object/"Manual Repository">
=back
=head1 DETAILS
=head2 Why use OODoc in stead of POD
POD (Perl's standard Plain Old Document format) has a very simple
syntax. POD is very simple to learn, and the produced manual pages
look like normal Unix manual pages. However, when you start writing
larger programs, you start seeing the weaker sides of POD.
One of the main problems with POD is that is using a visual markup
style: you specify information by how it must be presented to the
viewer. This in contrast with logical markup where you specify the
information more abstract, and a visual representation is created by
translation. For instance in HTML defines a C<I > tag (visual markup
italic) and C<EM> (logical markup emphasis, which will usually show
as italic).
The main disadvantage of visual markup is lost information: the
formatter of the manual page can not help the author of the documentation
to produce more consistent manual pages. This is not a problem for small
distributions, but is much more needed when programs grow larger.
=head2 How OODoc works
Like with POD, you simply mix your documentation with your code. When
the module is distributed, this information is stripped from the files
by a I<parser>, and translated into an object tree. This tree is then
optimized: items combined, reorganized, etc, to collect all information
required to produce useable manual pages. Then, a I<formatter> is called
to generate the manual pages.
=head3 The parser
The parser reads the package files, and (by default) strip them from all
documentation. The stripped files are written to a temporary directory
which is used to create the module distribution.
It is possible to use more than one parser for your documentation. On
this moment, there is only one parser implemented: the Markov parser,
named after the author. But you can add your own parser, if you want to.
Within one distribution, different files can be parsed by different parsers.
The parser produces an object tree, which is a structured representation of
the documentation. The tree is parser independent, and organized by
manual page.
=head3 Collecting relations
The second phase of the manual page generation process figures out the
relations between the manual pages. It collects inheritance relations
and other organizational information which is to be used by the
manual page generators.
=head3 The formatter
The final phase can be called more than once: based on the same object
tree, documents can be produced in various formats. The initial
implementation produces POD and HTML.
=head2 Getting Started from scratch
To use OODoc, you need to create a scripts which helps you producing
the distribution of your module. The simpest script look like this:
use OODoc;
my $dist = '/tmp/abc';
my $doc = OODoc->new
( distribution => 'E-mail handling'
, version => '0.01'
);
$doc->processFiles(workdir => $dist); # parsing
$doc->prepare; # collecting
$doc->create('pod', workdir => $dist); # formatting to POD
The default parser will be used to process the files, see
L<OODoc::Parser::Markov|OODoc::Parser::Markov> for its syntax. The formatter is described
in L<OODoc::Format::Pod|OODoc::Format::Pod>. Once you have this working, you may decide
to add options to the calls to adapt the result more to your own taste.
=head2 Getting Started by Cloning
A much easier way to start, is to simply pick one of the examples
which are distributed with OODoc. They come in three sizes: for a
small module (mimetypes and orl), an average sized set-up (for OODoc
itself), and a huge one (mailbox, over 140 packages).
All examples are written by the same person, and therefore follow the
same set-up. Copy the files C<mkdoc>, C<mkdist> and C<MANIFEST.extra>
plus the directory C<html> to the top directory of your distribution.
Edit all the files, to contain the name of your module.
It expects a C<MANIFEST> file to be present, like standard for Perl
modules. That file lists your own code, pod and additional files
which need to be included in the release. OODoc will extend this
file with produced POD files.
The demo-scripts use a C<version> file, which contains something like
C<< $VERSION = 0.1 >>. This is not required: you can specify to
take a version from any file, in the traditional Perl way. However,
when you glue multiple modules together into one big HTML documentation
website (see the mailbox example), then this separate file simplifies
the production script.
To test the document production,
try (on UNIX/Linux) C<<pod2man xyz.pod | man -l - >>
To get a prepared distribution, use C<./mkdist 1>. This will first
produce all documentation, and then run C<make test> and C<make dist>.
It generates two distributions: the C<module-version.tar.gz> which
can be uploaded to CPAN, and the C<module-version-raw.tar.gz> which
is for yourself. The latter contains the whole setup which is used
to generate the distribution, so the unprocessed files!
=head1 DIAGNOSTICS
=over 4
=item Error: Cannot compile $parser class
The $parser class does not exist or produces compiler errors.
=item Error: Cannot read version from file $fn: $!
=item Error: Parser $parser could not be instantiated
Something went wrong while starting the parser object. Probably there is
an other error message which will tell you the exact cause.
=item Error: cannot copy distribution file $fn to $dest: $!
For some reason, a plain file from can not be copied from your source
tree to the location where the distribution is made.
=item Error: create requires a directory to write the manuals to
You have to give a value to C<workdir>, which will be used as top directory
for the produced output. It does not matter whether there is already some
stuff in that directory.
=item Error: formatter $name has compilation errors: $@
The formatter which is specified does not compile, so can not be used.
=item 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">.
=item Warning: no file $fn to include in the distribution
Probably your MANIFEST file lists this file which does not exist. The file
will be skipped for now, but may cause problems later on.
=item Error: no version specified for distribution "$name"
Version information will be added to all packages and all manual
pages. You need to specify a version and be sure that it changes
with each release, or create a file named C<version> or C<VERSION>
which contains that data.
=item Error: problems compiling $code for package $name: $@
Syntax error in your code, or a problem caused by stripping the file.
You can run your test-scripts before the files get stripped as long
as you do not use C<make test>, because that will try to produce
manual-pages as well...
=item Error: requires a directory to write the distribution to
You have to give a value to C<workdir>, which may be C<undef>. This
option is enforced to avoid the accidental omission of the parameter.
When processing the manifest file, some files must be copied directly
to a temporary directory. The packages are first stripped from
their pseudo doc, and then written to the same directory. That
directory will be the place where C<make dist> is run later.
=item Error: the destribution must be specified
=item Error: there is no version defined for the source files
Each manual will need a version number. There are various ways to
specify one. For instance, create a file named C<version> or C<VERSION>
in the top source directory of your distribution, or specify a version
as argument to L<OODoc::new()|OODoc/"METHODS"> or L<OODoc::processFiles()|OODoc/"Parser">.
=item Error: use regex, code reference or array for file selection
The L<processFiles(select)|OODoc/"Parser"> option is not understood. You may specify
an ARRAY, regular expression, or a code reference.
=back
=head1 SEE ALSO
This module is part of OODoc distribution version 2.01,
built on November 11, 2015. Website: F<http://perl.overmeer.net/oodoc/>
=head1 LICENSE
Copyrights 2003-2015 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>