NAME

Daizu::Plugin::PodArticle - a plugin for publishing Perl POD documentation on websites

DESCRIPTION

This plugin adds the ability for Daizu CMS to load content from POD files (or Perl code containing POD documentation). Once this module has parsed the file it provides Daizu with the content in XHTML format (as a DOM structure), and from then on it can be treated as a normal article.

With this module loaded it should be possible to publish Perl documentation simply by adding the files containing POD to the repository, marking them as being articles like any other, and giving them a svn:mime-type property with the value 'text/x-perl'.

CONFIGURATION

To turn on this plugin, include the following in your Daizu CMS configuration file:

    <plugin class="Daizu::Plugin::PodArticle" />

POD EXTENSIONS

This module understands the following non-standard POD features, which will be ignored by all other POD processeors:

Syntax highlighting

If you want an indented block of text to be syntax highlighted (showing colour-coding to make code samples or whatever easier to read), you can include a command like the following before the indented block:

    =for syntax-highlight perl

        my $foo = 'this perl code will be syntax colored.'

This requires the Daizu::Plugin::SyntaxHighlight plugin to be enabled too.

Each of these =for commands will only affect a single indented block (whichever one is found next). Blank lines in blocks won't break them up; the syntax highlighting will last up until the next thing which isn't indented (a command or a normal paragraph).

The fold

You can get the same effect as the special daizu:fold element gives in XHTML articles using the following markup:

    =for daizu-fold

This is not likely to be useful unless you're writing blog articles in POD, in which case the content above the fold will be shown in index pages (and possibly feeds, depending on how they're configured).

Page breaks

You can get the same effect as the special daizu:page element gives in XHTML articles using the following markup:

    =for daizu-page

Occurances of this will separate pages of content, allowing a long document to be split into multiple pages for web publication.

LINKS

TODO - describe the awful hackiness of the module-links.txt file, and whatever other incompatibilities might be a problem.

METHODS

Daizu::Plugin::PodArticle->register($cms, $whole_config, $plugin_config, $path)

Called by Daizu CMS when the plugin is registered. It registers the load_article() method as an article loader for the MIME type 'text/x-perl'.

The configuration is currently ignored.

$self->load_article($cms, $file)

Does the actual parsing of the POD content of $file (which should be a Daizu::File object), and returns the approriate content and metadata.

Never rejects a file, and therefore always returns true.

Daizu::Plugin::PodArticle::Parser

This class is the subclass of Pod::Parser used for parsing POD documents into XHTML DOM documents. It overrides the methods command(), textblock(), and verbatim().

COPYRIGHT

This software is copyright 2006 Geoff Richards <geoff@laxan.com>. For licensing information see this page:

http://www.daizucms.org/license/