The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OODoc-0.10
River stage zero No dependents
1 ++
/ OODoc::Format::Pod

NAME

OODoc::Format::Pod - Produce POD pages from the doc tree

INHERITANCE

 OODoc::Format::Pod
   is a OODoc::Format
   is a OODoc::Object

 OODoc::Format::Pod is extended by
   OODoc::Format::Pod2

SYNOPSIS

 my $doc = OODoc->new(...);
 $doc->create
   ( 'pod'
   , format_options => [show_examples => 'NO']
   , append         => "extra text\n"
   );

DESCRIPTION

Create manual pages in the POD syntax. POD is the standard document description syntax for Perl. POD can be translated to many different operating system specific manual systems, like the Unix man system.

OVERLOADED

METHODS

Constructors

OODoc::Format::Pod->new(OPTIONS)

Inheritance knowledge

$obj->extends([OBJECT])

Attributes

$obj->manifest

$obj->project

$obj->version

$obj->workdir

Page generation

$obj->chapterInheritance(OPTIONS)

    Produces the chapter which shows inheritance relationships.

     Option  Defined in       Default   
 manual                   <required>
 output                   <required>

    . manual OBJECT

    . output IO::File

$obj->cleanup(MANUAL, STRING)

$obj->createInheritance(MANUAL)

$obj->createManual(OPTIONS)

     Option          Defined in       Default   
 append                           ''        
 format_options  L<OODoc::Format>  []        
 manual          L<OODoc::Format>  <required>
 project         L<OODoc::Format>  <required>
 template        L<OODoc::Format>  C<undef>

    . append STRING|CODE

    . format_options ARRAY

    . manual MANUAL

    . project STRING

    . template LOCATION

$obj->createOtherPages(OPTIONS)

$obj->formatManual(OPTIONS)

    The OPTIONS are a collection of all options available to show* methods. They are completed with the defaults set by createManual(format_options).

     Option  Defined in       Default   
 append                   ''        
 manual                   <required>
 output                   <required>

    . append STRING|CODE

      Used after each manual page has been formatting according to the standard rules. When a STRING is specified, it will be appended to the manual page. When a CODE reference is given, that function is called with all the options that showChapter() usually gets.

      Using append is one of the alternatives to create the correct Reference, Copyrights, etc chapters at the end of each manual page. See "Configuring".

    . manual MANUAL

    . output FILE

$obj->link(MANUAL, OBJECT, [TEXT])

    Create the text for a link which refers to the OBJECT. The link will be shown somewhere in the MANUAL. The TEXT will be displayed is stead of the link path, when specified.

$obj->showChapter(OPTIONS)

$obj->showChapterIndex(FILE, CHAPTER, INDENT)

$obj->showExamples(OPTIONS)

$obj->showOptionExpand(OPTIONS)

$obj->showOptionTable(OPTIONS)

$obj->showOptionUse(OPTIONS)

$obj->showOptionalChapter(NAME, OPTIONS)

$obj->showOptions(OPTIONS)

$obj->showRequiredChapter(NAME, OPTIONS)

$obj->showStructureExpanded(OPTIONS)

$obj->showStructureRefer(OPTIONS)

$obj->showSubroutine((@))

$obj->showSubroutineDescription(OPTIONS)

$obj->showSubroutineName(OPTIONS)

$obj->showSubroutineUse(OPTIONS)

$obj->showSubroutines(OPTIONS)

$obj->writeTable

     Option  Defined in       Default   
 ARRAY                    <required>
 header                   <required>
 output                   <required>
 widths                   C<undef>

    . ARRAY -OF-ARRAYS

      An array of arrays, each describing a row for the output. The first row is the header.

    . header ARRAY

    . output FILE

    . widths ARRAY

Template::Magic

$obj->zoneGetParameters(ZONE|STRING)

Commonly used functions

$obj->filenameToPackage(FILENAME)

OODoc::Format::Pod->filenameToPackage(FILENAME)

$obj->mkdirhier(DIRECTORY)

OODoc::Format::Pod->mkdirhier(DIRECTORY)

Manual Repository

$obj->addManual(MANUAL)

$obj->mainManual(NAME)

$obj->manual(NAME)

$obj->manuals

$obj->manualsForPackage(NAME)

$obj->packageNames

DIAGNOSTICS

Error: cannot write pod manual at $manfile: $!

Error: formatter does not know the version.

Error: formatter has no project name.

A formatter was created without a name specified for the project at hand. This should be passed with new(project).

Error: manual definition requires manual object

A call to addManual() expects a new manual object (a OODoc::Manual), however an incompatible thing was passed. Usually, intended was a call to manualsForPackage() or mainManual().

Warning: missing required chapter $name in $manual

Error: no directory to put pod manual for $name in

Error: no package name for pod production

Error: no package name for pod production

Error: no working directory specified.

The formatter has to know where the output can be written. This directory must be provided via new(workdir), but was not specified.

Warning: unknown subroutine type $type for $name in $manual

DETAILS

Configuring

Probably, the output which is produced by the POD formatter is only a bit in the direction of your own ideas, but not quite what you like. Therefore, there are a few ways to adapt the output.

Configuring with format options

createManual(format_options) or OODoc::create(format_options) can be used with a list of formatting options which are passed to showChapter(). This will help you to produce pages which have pre-planned changes in layout.

Example: format options

 use OODoc;
 my $doc = OODoc->new(...);
 $doc->processFiles(...);
 $doc->prepare;
 $doc->create(pod =>
    format_options => [ show_subs_index     => 'NAMES'
                      , show_inherited_subs => 'NO'
                      , show_described_subs => 'USE'
                      , show_option_table   => 'NO'
                      ]
   );

Configuring by appending

By default, the last chapters are not filled in: the REFERENCES and COPYRIGHTS chapters are very personal. You can fill these in by extending the POD generator, as described in the next section, or take a very simple approach simply using createManual(append).

Example: appending text to a page

 use OODoc;
 my $doc = OODoc->new(...);
 $doc->processFiles(...);
 $doc->prepare;
 $doc->create('pod', append => <<'TEXT');

 =head2 COPYRIGHTS
 ...
 TEXT

Configuring via extension

OODoc is an object oriented module, which means that you can extend the functionality of a class by creating a new class. This provides an easy way to add, change or remove chapters from the produced manual pages.

Example: remove chapter inheritance

 $doc->create('MyPod', format_options => [...]);

 package MyPod;
 use base 'OODoc::Format::Pod';
 sub chapterInheritance(@) {shift};

The MyPod package is extending the standard POD generator, by overruling the default behavior of chapterInheritance() by producing nothing.

Example: changing the chapter's output

 $doc->create('MyPod', format_options => [...]);

 package MyPod;
 use base 'OODoc::Format::Pod';

 sub chapterCopyrights(@)
 {   my ($self, %args) = @_;
     my $manual = $args{manual} or confess;
     my $output = $args{output} or confess;

     $output->print("\n=head2 COPYRIGHTS\n");
     $output->print($manual->name =~ m/abc/ ? <<'FREE' : <<'COMMERICIAL');
This package can be used free of charge, as Perl itself.
FREE
This package will cost you money.  Register if you want to use it.
COMMERCIAL

     $self;
 }

Example: adding to a chapter's output

 $doc->create('MyPod', format_options => [...]);

 package MyPod;
 use base 'OODoc::Format::Pod';

 sub chapterDiagnostics(@)
 {   my ($self, %args) = @_;
     $self->SUPER::Diagnostics(%args);

     my $output  = $args{output} or confess;
     my $manual  = $args{manual} or confess;
     my @extends = $manual->superClasses;

     $output->print(\nSee also the diagnostics is @extends.\n");
     $self;
 }

Configuring with Template::Magic

When using 'pod2' in stead of 'pod' when OODoc::create() is called, the OODoc::Format::Pod2 will be used. It's nearly a drop-in replacement by its default behavior. When you specify your own template file, every thing can be made.

See the manual page of Template::Magic. You have to install Bundle::Template::Magic to get it to work.

Example: formatting with template

 use OODoc;
 my $doc = OODoc->new(...);
 $doc->processFiles(...);
 $doc->prepare;
 $doc->create(pod2, template => '/some/file',
    format_options => [ show_subs_index     => 'NAMES'
                      , show_option_table   => 'NO'
                      ]
    )

Example: format options within template

The template van look like this:

 {chapter NAME}
 some extra text
 {chapter OVERLOADED}
 {chapter METHODS show_option_table NO}

The formatting options can be added, however the syntax is quite sensitive: not quotes, comma's and exactly one blank between the strings.

REFERENCES

See the OODoc website at http://perl.overmeer.net/oodoc/ for more details.

COPYRIGHTS

Module version 0.10. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.

Copyright (c) 2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.