Contentment::Generator::POD - A generator for Plain Old Documentation


  $source = <<'END_OF_POD';
  =head1 NAME

  Test - This is a test.


  This is a little test of L<Contentment::Gneerator::POD>.


  my $generator = Contentment::Generator::POD->new({
      properties => {
          foo => 1,
          bar => 2,
      source => $source,

  my $title       = $generator->get_property('title');
  my $description = $generator->get_property('description');



This is a generated specifically geared for use with Perl's POD, or Plain Old Documentation, format. This class inherits from Contentment::Generator::Plain.

$generator = Contentment::Generator::POD->new(\%args)

This constructs a POD generator. It takes the following arguments.

source (required)

This option specifies the source to use for the documentation. It may be specified in any of the forms that Contentment::Generator::Plain supports.

properties (optional, defaults to {})

This specifies any properties you want to give generator. This properties will be overridden by any properties specified within the file itself. Properties may be specified in the file itself in four different ways.

  1. You may specify the property with a =begin meta section:

      =begin meta
          foo => 1
          bar => 'A string.'
      =end meta

    The properties are specified using a hash-like syntax where the keys may be placed within quotes or not and the values may be placed in quotes or not. The parser for this is pretty simple, so try to stick to the simple stuff as the above.

  2. You may specify the property with a =for meta section:

      =for meta
        foo => 1
        bar => 'A string.'
      new_paragraph => 'NOT A PROPERTY!'

    This is exactly the same as the =begin meta section, but a =for meta section lasts until a new paragraph is started.

  3. You may specify a heading named "NAME" followed by a title and description:

      =head1 NAME
      Title - This is the description

    This will create a property named "title" with the value "Title" and a property named "description" with the value "This is the description".

    This is in following with the standard man-page convention that most POD files follow.

  4. If the first heading encountered is not named "NAME", then it will be used to set a property named "title" with the given heading. For example,

      =head1 This is the Title

    Would result in a property named "title" with the value "This is the Title" being stored.

If two or more methods are used to define the same property, the way the values clobber each other isn't well-defined.

$source = $self->source

This overrides the method provided by Contentment::Generator::PLain. In addition to reading the source, this method also parses properties out of the source.

$properties = $generator->properties

Returns the hash of properties for the generator. This will include any properties found in the source.


Contentment::Generator::Plain, Contentment::Generator::PerlScript, perlpod


Andrew Sterling Hanenkamp, <>


Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed and licensed under the same terms as Perl itself.