/ 
OODoc-1.03
River stage zero No dependents
/ OODoc

NAME

OODoc - object oriented production of code related documentation

INHERITANCE

OODoc
  is a OODoc::Object

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

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

  1. to use your own modified version of the mkdist and mkdoc scripts, as provided in the examples which come with this module, or

  2. use the oodist, which is less flexible but much simpler, and only requires some additions to your Makefile.PL.

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 OODoc::Parser::Markov parser understands POD and has additional logical markup tags. See 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 OODoc::Format.

Do not forget to read the DETAILS section, later on this manual-page to get started. Please contribute ideas. Have a look at the main website of this project at http://perl.overmeer.net/oodoc/. That is also an example of the produced output.

OVERLOADED

METHODS

Constructors

OODoc->new(OPTIONS)

    Option      --Default
distribution  <required>
project       <distribution>
verbose       0
version       <from version or VERSION file>

    . distribution => STRING

      The name of the package, as released on CPAN.

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

    . verbose => INTEGER

      Verbosity during the process. The higher the number, the more information will be presented (current useful maximum is 4).

    . 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 version or VERSION which contains a number.

Inheritance knowledge

$obj->extends([OBJECT])

Attributes

$obj->distribution

    Returns the nice name for the distribution.

$obj->project

    Returns the general project description, by default the distribution name.

$obj->version

    Returns the version string for the distribution.

Parser

$obj->processFiles(OPTIONS)

    Option      --Default
distribution  <from main OODoc object>
manifest      <source/>'MANIFEST'
notice        ''
parser        OODoc::Parser::Markov
select        qr/\.(pod|pm)$/
source        '.'
verbose       <from object>
version       <from source directory or OODoc object>
workdir       <required>

    . distribution => NAME

      Useful when more than one distribution is merged into one set of documentation.

    . manifest => FILENAME

      The manifest file lists all files which belong to this distribution: packages, pods, tests, etc. before the new pod files are created.

    . notice => STRING

      Include the string (which may consist of multiple lines) to each of the pm files. This notice usually contains the copyright message.

    . parser => CLASS|OBJECT

      The parser CLASS or OBJECT to be used to process the pages.

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

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

    . verbose => INTEGER

      Tell more about each stage of the processing. The higher the number, the more information you will get.

    . version => STRING

      The version of the distribution. If not specified, the source directory is scanned for a file named version or 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 Makefile.PL option VERSION_FROM to work with this seperate version file, that line should contain $VERSION = .

    . 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 undef (still: you have to specify the option). In this case, only the documentation in the files is consumed, and no files created.

$obj->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 processFiles(select) and the LIST are files from a manifest.

Preparation

$obj->getPackageRelations(VERBOSITY)

    Compile all files which contain packages, and then try to find-out how they are related.

$obj->prepare(OPTIONS)

    Add information to the documentation tree about inheritance relationships of the packages. prepare must be called between processFiles() and create().

    Option --Default
verbose  <from object>

    . verbose => INTEGER

Formatter

$obj->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 pod and html representing OODoc::Format::Pod and 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_template  undef
other_files      undef
process_files    <formatter dependent>
select           undef
verbose          0
workdir          <required>

    . append => STRING|CODE

    . format_options => ARRAY

      Formatter dependent initialization options. See the documentation of the formatter which will be used for the possible values.

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

    . manual_format => ARRAY

    . manual_template => LOCATION

      Passed to OODoc::Format::createManual(template), 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.

    . other_files => DIRECTORY

    . 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 OODoc::Format::createOtherPages(process).

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

    . verbose => INTEGER

      Debug level, the higher the number, the more details about the process you will have.

    . workdir => DIRECTORY

      The directory where the output is going to.

$obj->stats

    Returns a string which contains some statistics about the whole parsed document set.

Commonly used functions

$obj->filenameToPackage(FILENAME)

OODoc->filenameToPackage(FILENAME)

$obj->mkdirhier(DIRECTORY)

OODoc->mkdirhier(DIRECTORY)

Manual Repository

$obj->addManual(MANUAL)

$obj->mainManual(NAME)

$obj->manual(NAME)

$obj->manuals

$obj->manualsForPackage(NAME)

$obj->packageNames

DETAILS

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 I tag (visual markup italic) and 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.

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 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 formatter is called to generate the manual pages.

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.

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.

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.

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 OODoc::Parser::Markov for its syntax. The formatter is described in 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.

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 mkdoc, mkdist and MANIFEST.extra plus the directory html to the top directory of your distribution. Edit all the files, to contain the name of your module.

It expects a 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 version file, which contains something like $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, use ./mkdoc 1 (1 = verbose) The output can be found in the specified workdir. To see them: try (on UNIX/Linux) <pod2man xyz.pod | man -l - >

To get a prepared distribution, use ./mkdist 1. This will first produce all documentation, and then run make test and make dist. It generates two distributions: the module-version.tar.gz which can be uploaded to CPAN, and the 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!

DIAGNOSTICS

Error: Cannot compile $parser class

    The $parser class does not exist or produces compiler errors.

Error: Cannot read version from file $fn: $!

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.

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.

Error: formatter $name has compilation errors: $@

    The formatter which is specified does not compile, so can not be used.

Error: manual definition requires manual object

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.

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 version or VERSION which contains that data.

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 make test, because that will try to produce manual-pages as well...

Error: requires a directory to write the distribution to

    You have to give a value to workdir, which may be 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 make dist is run later.

Error: requires a directory to write the manuals to

    You have to give a value to 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.

Error: the destribution must be specified

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 version or VERSION in the top source directory of your distribution, or specify a version as argument to OODoc::new() or OODoc::processFiles().

Error: use regex, code reference or array for file selection

    The processFiles(select) option is not understood. You may specify an ARRAY, regular expression, or a code reference.

SEE ALSO

This module is part of OODoc distribution version 1.03, built on March 14, 2008. Website: http://perl.overmeer.net/oodoc/

LICENSE

Copyrights 2003-2008 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 http://www.perl.com/perl/misc/Artistic.html