NAME

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

INHERITANCE

OODoc::Format::Pod
  is an OODoc::Format
  is an OODoc::Object

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

SYNOPSIS

my $doc = OODoc->new(...);
$doc->formatter('pod3')->createPages(
   append         => "extra text\n",
   manual_options => [
      show_examples => 'NO'
   ],
);

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.

Extends "DESCRIPTION" in OODoc::Format.

OVERLOADED

Extends "OVERLOADED" in OODoc::Format.

overload: '==' and '!=' (numeric comparison): Inherited, see "OVERLOADED" in OODoc::Object
overload: 'bool': Inherited, see "OVERLOADED" in OODoc::Object

METHODS

Extends "METHODS" in OODoc::Format.

Constructors

Extends "Constructors" in OODoc::Format.

$class->new(%options)

Inherited, see "Constructors" in OODoc::Object

-Option  --Defined in     --Default
 format    OODoc::Format    'pod'
 manifest  OODoc::Format    undef
 project   OODoc::Format    <required>
 version   OODoc::Format    <required>
 workdir   OODoc::Format    <required>

format => 'pod*'|'html*'|PACKAGE
manifest => OBJECT
project => STRING
version => STRING
workdir => DIRECTORY

Attributes

Extends "Attributes" in OODoc::Format.

$obj->format(): Inherited, see "Attributes" in OODoc::Format
$obj->manifest(): Inherited, see "Attributes" in OODoc::Format
$obj->project(): Inherited, see "Attributes" in OODoc::Format
$obj->unique(): Inherited, see "Attributes" in OODoc::Object
$obj->version(): Inherited, see "Attributes" in OODoc::Format
$obj->workdir(): Inherited, see "Attributes" in OODoc::Format

Manual Repository

Extends "Manual Repository" in OODoc::Format.

$obj->addManual($manual): Inherited, see "Manual Repository" in OODoc::Object
$obj->findManual($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->mainManual($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->manuals(): Inherited, see "Manual Repository" in OODoc::Object
$obj->manualsForPackage($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->packageNames(): Inherited, see "Manual Repository" in OODoc::Object
$obj->publicationIndex(): Inherited, see "Manual Repository" in OODoc::Object
$obj->publish(\%options): Inherited, see "Manual Repository" in OODoc::Object

Page generation

Extends "Page generation" in OODoc::Format.

$obj->cleanup($manual, $text, %options)

Inherited, see "Page generation" in OODoc::Format

$obj->createManual(%options)

The %options are a collection of all options available to show*() methods. Improves base, see "Page generation" in OODoc::Format

-Option  --Defined in     --Default
 append                     ''
 manual    OODoc::Format    <required>
 project   OODoc::Format    <required>
 template  OODoc::Format    undef

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

project => STRING

template => LOCATION

$obj->createOtherPages(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->createPages(%options)

Inherited, see "Page generation" in OODoc::Format

$any->link( $manual, $object, [$text, \%settings] )

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->removeMarkup(STRING)

There is (AFAIK) no way to get the standard podlators code to remove all markup from a string: to simplify a string. On the other hand, you are not allowed to put markup in a verbatim block, but we do have that. So: we have to clean the strings ourselves.

$obj->showChapter(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showChapterIndex($file, $chapter, $indent)

$obj->showExamples(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionExpand(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionTable(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionUse(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionalChapter($name, %options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptions(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showRequiredChapter($name, %options)

Inherited, see "Page generation" in OODoc::Format

$obj->showStructureExpanded(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showStructureRefer(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutine(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutineDescription(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutineName(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutineUse(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutines(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->simplifyPod($in, $out)

The POD is produced in the specified $in filename, but may contain some garbage, especially a lot of superfluous blanks lines. Because it is quite complex to track double blank lines in the production process, we make an extra pass over the POD to remove it afterwards. Other clean-up activities may be implemented later.

$obj->writeTable(%options)

-Option--Default
 header  <required>
 output  <required>
 rows    <required>
 widths  undef

header => ARRAY
output => FILE
rows => ARRAY-OF-ARRAYS: An array of arrays, each describing a row for the output. The first row is the header.
widths => ARRAY

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() or OODoc::formatter() 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->formatter(pod =>
   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->formatter('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->formatter('MyPod', %format_options);

package MyPod;
use parent '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->formatter('MyPod', %format_options);

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

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

     $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->formatter('MyPod', %format_options);

package MyPod;
use parent 'OODoc::Format::Pod';
use Log::Report 'panic';

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

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

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

Configuring with OODoc::Template

When using 'pod2' in stead of 'pod' when OODoc::formatter() 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.

. Example: formatting with template

use OODoc;
my $doc = OODoc->new(...);
$doc->processFiles(...);
$doc->prepare;
$doc->formatter(pod2 =>
   template          => '/some/file',
   manual_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.

DIAGNOSTICS

Error: cannot link to a $package
Fault: cannot read prelimary pod from $file: $!
Fault: cannot write final pod to $file: $!
Fault: cannot write prelimary pod manual to $file: $!
Error: illegal show option choice: $value
Error: illegal value for show_option_table: $value
Error: illegal value for show_sub_description: $value
Error: illegal value for show_subroutine: $value
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().
Error: missing required chapter $name in $manual
Fault: write to $file failed: $!

LICENSE

For contributors see file ChangeLog.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install OODoc, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OODoc

CPAN shell

perl -MCPAN -e shell
install OODoc

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

OVERLOADED

METHODS

Constructors

Attributes

Manual Repository

Page generation

DETAILS

Configuring

Configuring with format options

Configuring by appending

Configuring via extension

Configuring with OODoc::Template

DIAGNOSTICS

SEE ALSO

LICENSE

Module Install Instructions