NAME

oodist - create perl distributions with OODoc

SYNOPSIS

 cd <src>
 oodist [OPTIONS]
   OPTION:                 DEFAULT:
   --pod  or --nopod         produce pod: yes
   --dist or --nodist        produce distribution: yes
   --html or --nohtml        produce html: yes if templates
   --raw  or --noraw         produce package with raw files: yes

  OPTIONS general:
   --distdir  | -d <dir>     makefile:DISTDIR || $ENV{OODOC_DISTDIR} || <src>
   --extends  | -x <path>    empty
   --project  | -p <string>  makefile:DISTNAME
   --rawdir   | -r <dir>     makefile:RAWDIR || $ENV{OODOC_RAWDIR} || <src>
   --workdir  | -w <dir>     /tmp/<DISTVNAME>
   --verbose  | -v           true when specified

  OPTIONS for POD:
   --email    | -e <email>   makefile:EMAIL
   --firstyear| -y <year>    makefile:FIRST_YEAR
   --license  | -l <string>  makefile:LICENSE || $ENV{OODOC_LICENSE} || 'artistic'
   --pmhead   | -h <file>    'PM.HEAD'  || constructed
   --podtail  | -t <file>    'POD.TAIL' || constructed
   --website  | -u <url>     makefile:WEBSITE

  OPTIONS for HTML:
   --html-templates <dir>    makefile:HTML_TEMPLATES || 'html'
   --html-output <dir>       makefile:HTML_OUTPUT    || 'public_html'
   --html-docroot <url>      makefile:HTML_DOCROOT   || '/'

DESCRIPTION

The oodist script is currently only usable on UNIX in combination with Makefile.PL. It is a smart wrapper around the OODoc module, to avoid start work to produce real POD for modules which use OODoc's POD extensions. HTML is not (yet) supported.

Configuring

All OPTIONS can be specified on the command-line, but you do not want to specify them explicitly each time you produce a new distribution for your product. The options come in two kinds: those which are environment independent and those which are. The first group can be set via the Makefile.PL, the second can be set using environment variables as well.

Example: add to the end of your Makefile.PL

 sub MY::postamble { <<'__POSTAMBLE' }
 FIRST_YEAR   = 2001
 WEBSITE      = http://perl.overmeer.net/oodoc
 EMAIL        = oodoc@overmeer.net
 __POSTAMBLE

Main options

The process is controlled by four main options. All options are by default on.

. --pod or --nopod

Produce pod files in the working directory and in the distribution.

. --dist or --nodist

Create a distribution, containing all files from the MANIFEST plus produced files.

. --html or --nohtml

Create html manual pages. The --html-templates options must point to an existing directory (defaults to the html/ sub-directory).

. --raw or --noraw

Create a package which contains the files which are needed to produce the distribution: the pm files still including the oodoc markup.

General options

The other OPTIONS in detail

. --distdir | -d <dir>

The location where the final file to be distributed is placed. By default in the source directory.

. --extends | -x <path>

A colon seperated list of directories which contains "raw oodoc" pm and pod files which are (in some cases) used to provide data for base-classes of this module.

. --rawdir | --r <dir>

The location where a raw version of the distribution is made. The normal distribution contains expanded POD and stripped PM files. For that reason, you can not use it a backup for your files. If you have co-workers on the module, you may wish to give them the originals.

. --verbose | --v

Shows what happens during the process.

. --workdir | -w <dir>

The processing will take place in a seperate directory: the stripped pm's and produced pod files will end-up there.

Options to produce POD

. --email | -e <email>

The email address which can be used to contact the authors. Used in the automatic podtail.

. --firstyear| -y <year>

The first year that a release for this software was made. Used in the automatic podtail.

. --license | -l ['gpl'|'artistic'|filename]

The lisense option is a special case: it can contain either the strings gpl or artistic, or a filename which is used to read the actual license text from. The default is artistic

. --pmhead | -h <file>

Each of the stripped pm files will have content of the file added at the top. Each line will get a comment '# ' marker before it. If not specified, a short notice will be produced automatically. Implicitly, if a file PM.HEAD exists, that will be used.

. --podtail | -t <file>

Normally, a trailing text is automatically produced, based on all kinds of facts. However, you can specify your own file. If exists, the content is read from a file named POD.TAIL, and no construction is attempted.

. --website | -u <url>

Where the HTML documentation related to this module is publicly visible.

Options to produce HTML

. --html-docroot <url>

This (usually relative) URL is prepended to all absolute links in the HTML output.

. --html-output <dir>

The directory where the produced HTML pages are written to.

. --html-templates <dir>

The directory which contains the templates for HTML pages which are used to construct the html version of the manual-pages.