NAME

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

SYNOPSIS

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

  Test - This is a test.

  =head1 DESCRIPTION

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

  =cut
  END_OF_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');

  $generator->generate();

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
     =cut

   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!'
     =cut

   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
   
     =cut

   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
   
     =cut

   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.

SEE ALSO

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

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforege.net>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

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