=head1 NAME
OODoc::Format::Pod - Produce POD pages from the doc tree
=head1 INHERITANCE
OODoc::Format::Pod
is an OODoc::Format
is an OODoc::Object
OODoc::Format::Pod is extended by
OODoc::Format::Pod2
=head1 SYNOPSIS
my
$doc
= OODoc->new(...);
$doc
->create
(
'pod'
,
format_options
=> [
show_examples
=>
'NO'
]
,
append
=>
"extra text\n"
);
=head1 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 C<man>
system
.
=head1 OVERLOADED
=head1 METHODS
=head2 Constructors
OODoc::Format::Pod-E<gt>B<new>(OPTIONS)
=over 4
See L<OODoc::Format/
"METHODS"
>
=back
=head2 Inheritance knowledge
$obj
-E<gt>B<
extends
>([OBJECT])
=over 4
See L<OODoc::Object/
"Inheritance knowledge"
>
=back
=head2 Attributes
$obj
-E<gt>B<manifest>
=over 4
See L<OODoc::Format/
"Attributes"
>
=back
$obj
-E<gt>B<project>
=over 4
See L<OODoc::Format/
"Attributes"
>
=back
$obj
-E<gt>B<version>
=over 4
See L<OODoc::Format/
"Attributes"
>
=back
$obj
-E<gt>B<workdir>
=over 4
See L<OODoc::Format/
"Attributes"
>
=back
=head2 Page generation
$obj
-E<gt>B<chapterInheritance>(OPTIONS)
=over 4
Produces the chapter which shows inheritance relationships.
Option--Defined in --Default
manual <required>
output <required>
. manual OBJECT
. output IO::File
=back
$obj
-E<gt>B<cleanup>(MANUAL, STRING)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<createInheritance>(MANUAL)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<createManual>(OPTIONS)
=over 4
Option --Defined in --Default
append
''
format_options OODoc::Format []
manual OODoc::Format <required>
project OODoc::Format <required>
template OODoc::Format
undef
. append STRING|CODE
=over 4
Text to be added at the end of
each
manual page.
See L<formatManual(append)|OODoc::Format::Pod/
"Page generation"
>
for
an explanation.
=back
. format_options ARRAY
. manual MANUAL
. project STRING
. template LOCATION
=back
$obj
-E<gt>B<createOtherPages>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<formatManual>(OPTIONS)
=over 4
The OPTIONS are a collection of all options available to show* methods.
They are completed
with
the defaults set by L<createManual(format_options)|OODoc::Format/
"Page generation"
>.
Option--Defined in --Default
append
''
manual <required>
output <required>
. append STRING|CODE
=over 4
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 L<showChapter()|OODoc::Format/
"Page generation"
> usually gets.
Using C<append> is one of the alternatives to create the correct
Reference, Copyrights, etc chapters at the end of
each
manual
page. See L</Configuring>.
=back
. manual MANUAL
. output FILE
=back
$obj
-E<gt>B<
link
>(MANUAL, OBJECT, [TEXT])
=over 4
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.
=back
$obj
-E<gt>B<removeMarkup>(STRING)
=over 4
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.
=back
$obj
-E<gt>B<showChapter>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showChapterIndex>(FILE, CHAPTER, INDENT)
=over 4
=back
$obj
-E<gt>B<showExamples>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showOptionExpand>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showOptionTable>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showOptionUse>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showOptionalChapter>(NAME, OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showOptions>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showRequiredChapter>(NAME, OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showStructureExpanded>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showStructureRefer>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showSubroutine>((@))
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showSubroutineDescription>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showSubroutineName>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showSubroutineUse>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<showSubroutines>(OPTIONS)
=over 4
See L<OODoc::Format/
"Page generation"
>
=back
$obj
-E<gt>B<writeTable>
=over 4
Option--Defined in --Default
ARRAY <required>
header <required>
output <required>
widths
undef
. ARRAY -OF-ARRAYS
=over 4
An array of arrays,
each
describing a row
for
the output. The first row
is the header.
=back
. header ARRAY
. output FILE
. widths ARRAY
=back
=head2 Template::Magic
$obj
-E<gt>B<zoneGetParameters>(ZONE|STRING)
=over 4
See L<OODoc::Format/
"Template::Magic"
>
=back
=head2 Commonly used functions
$obj
-E<gt>B<filenameToPackage>(FILENAME)
OODoc::Format::Pod-E<gt>B<filenameToPackage>(FILENAME)
=over 4
See L<OODoc::Object/
"Commonly used functions"
>
=back
$obj
-E<gt>B<mkdirhier>(DIRECTORY)
OODoc::Format::Pod-E<gt>B<mkdirhier>(DIRECTORY)
=over 4
See L<OODoc::Object/
"Commonly used functions"
>
=back
=head2 Manual Repository
$obj
-E<gt>B<addManual>(MANUAL)
=over 4
See L<OODoc::Object/
"Manual Repository"
>
=back
$obj
-E<gt>B<mainManual>(NAME)
=over 4
See L<OODoc::Object/
"Manual Repository"
>
=back
$obj
-E<gt>B<manual>(NAME)
=over 4
See L<OODoc::Object/
"Manual Repository"
>
=back
$obj
-E<gt>B<manuals>
=over 4
See L<OODoc::Object/
"Manual Repository"
>
=back
$obj
-E<gt>B<manualsForPackage>(NAME)
=over 4
See L<OODoc::Object/
"Manual Repository"
>
=back
$obj
-E<gt>B<packageNames>
=over 4
See L<OODoc::Object/
"Manual Repository"
>
=back
=head1 DIAGNOSTICS
I<Error:> cannot
write
pod manual at
$manfile
: $!
I<Error:> formatter does not know the version.
I<Error:> formatter
has
no
project name.
A formatter was created without a name specified
for
the project at
hand. This should be passed
with
L<new(project)|OODoc::Format/
"METHODS"
>.
I<Error:> manual definition requires manual object
A call to L<addManual()|OODoc::Object/
"Manual Repository"
> expects a new manual object (a L<OODoc::Manual|OODoc::Manual>),
however an incompatible thing was passed. Usually, intended was a call
to L<manualsForPackage()|OODoc::Object/
"Manual Repository"
> or L<mainManual()|OODoc::Object/
"Manual Repository"
>.
I<Warning:> missing required chapter
$name
in
$manual
I<Error:>
no
directory to put pod manual
for
$name
in
I<Error:>
no
package
name
for
pod production
I<Error:>
no
package
name
for
pod production
I<Error:>
no
working directory specified.
The formatter
has
to know where the output can be written. This
directory must be provided via L<new(workdir)|OODoc::Format/
"METHODS"
>, but was not specified.
I<Warning:> unknown subroutine type
$type
for
$name
in
$manual
=head1 DETAILS
=head2 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.
=head3 Configuring
with
format
options
L<createManual(format_options)|OODoc::Format/
"Page generation"
> or L<OODoc::create(format_options)|OODoc/
"Formatter"
>
can be used
with
a list of formatting options which are passed to
L<showChapter()|OODoc::Format/
"Page generation"
>. This will help you to produce pages which have
pre-planned changes in layout.
I<Example:>
format
options
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'
]
);
=head3 Configuring by appending
By
default
, the
last
chapters are not filled in: the C<REFERENCES> and
C<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 L<createManual(append)|OODoc::Format::Pod/
"Page generation"
>.
I<Example:> appending text to a page
my
$doc
= OODoc->new(...);
$doc
->processFiles(...);
$doc
->prepare;
$doc
->create(
'pod'
,
append
=> <<
'TEXT'
);
=head2 COPYRIGHTS
...
TEXT
=head3 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.
I<Example:> remove chapter inheritance
$doc
->create(
'MyPod'
,
format_options
=> [...]);
sub
chapterInheritance(@) {
shift
};
The C<MyPod>
package
is extending the standard POD generator, by overruling
the
default
behavior of L<chapterInheritance()|OODoc::Format::Pod/
"Page generation"
> by producing nothing.
I<Example:> changing the chapter's output
$doc
->create(
'MyPod'
,
format_options
=> [...]);
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
;
}
I<Example:> adding to a chapter's output
$doc
->create(
'MyPod'
,
format_options
=> [...]);
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
;
}
=head3 Configuring
with
Template::Magic
When using
'pod2'
in stead of
'pod'
when
L<OODoc::create()|OODoc/
"Formatter"
> is called,
the L<OODoc::Format::Pod2|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
C<Bundle::Template::Magic> to get it to work.
I<Example:> formatting
with
template
my
$doc
= OODoc->new(...);
$doc
->processFiles(...);
$doc
->prepare;
$doc
->create(pod2,
template
=>
'/some/file'
,
format_options
=> [
show_subs_index
=>
'NAMES'
,
show_option_table
=>
'NO'
]
)
I<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.
=head1 SEE ALSO
This module is part of OODoc distribution version 0.97,
=head1 LICENSE
Copyrights 2003-2006 by Mark Overmeer. For contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.