NAME

OODoc::Format - base class for all OODoc formatters

INHERITANCE

OODoc::Format
  is an OODoc::Object

OODoc::Format is extended by
  OODoc::Format::Html
  OODoc::Format::Pod

SYNOPSIS

# Never instantiated directly.

DESCRIPTION

A formater produces manual pages in some way or an other which contain (parts of) the module documentation. Each formatter class is based on this OODoc::Format class, which should not be instantiated directly. By far most users will never explicitly create a formatter by themselves: it is created implicitly when OODoc::formatter() is called on a OODoc object.

Currently available formatters:

OODoc::Format::Pod

Simple formatter, which has the layout of the produced POD manual pages hard-coded in it's body. The only way to adapt the structure of the pages is by extending the class, and thereby overrule some of the methods which produce the text. Not much of a problem for experienced Object Oriented programmers.
OODoc::Format::Pod2

This formatter uses the same methods to generate the manual page as defined by OODoc::Format::Pod, but the general layout of the page can be configured using templates.

You have to install Bundle::Template::Magic to use this feature.
OODoc::Format::Pod3

The whole formatter, implemented as template in OODoc::Template, a very light weighted template system.

You have to install OODoc::Template to use this feature.
OODoc::Format::Html

Produce HTML by filling in templates. This module requires Bundle::Template::Magic and the ability to run cgi scripts.

Extends "DESCRIPTION" in OODoc::Object.

OVERLOADED

Extends "OVERLOADED" in OODoc::Object.

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

METHODS

Extends "METHODS" in OODoc::Object.

Constructors

Extends "Constructors" in OODoc::Object.

$class->new(%options)

Inherited, see "Constructors" in OODoc::Object

-Option  --Default
 format    <required>
 manifest  undef
 project   <required>
 version   <required>
 workdir   <required>

format => 'pod*'|'html*'|PACKAGE: Select the formatter to be used.
manifest => OBJECT
project => STRING: The short name of this project (module), set by OODoc::new(project).
version => STRING: Many manual pages will contain the version of the project. This can be any STRING, although blanks are not advised.
workdir => DIRECTORY: The DIRECTORY where the output will be placed. If it does not exist, it will be created for you.

Attributes

Extends "Attributes" in OODoc::Object.

$obj->format(): Code for the format.
$obj->manifest(): Returns the OODoc::Manifest object which maintains the names of created files.
$obj->project(): Returns the name of this project.
$obj->unique(): Inherited, see "Attributes" in OODoc::Object
$obj->version(): Returns the version string of this project. This version may contains any character, so should be handled with care.
$obj->workdir(): Returns the name of the work directory: the top location for all the output files.

Manual Repository

Extends "Manual Repository" in OODoc::Object.

$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

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

Takes the $text and cleans it up to be in the right format for the current output syntax. The cleaning up is parser dependent, and therefore the parser of the manual is addressed to do the work.

-Option     --Default
 create_link  <required>
 tag          undef

create_link => CODE: This CODE reference is used to create an absolute link to a text fragment. It is called with the manual and the object where is linked to (any OODoc::Text object). As third parameter, a string can be provided which should be displayed instead of the object name. Finally, all %options are passed as settings, by reference to a HASH.
tag => $word|\@words: Tag the produced block with this word, when possible. The HTML renderer will use this to add class="@tags" to the resulting block, for instance.

$obj->createManual(%options)

Format a manual into the selected format.

-Option  --Default
 append    undef
 manual    <required>
 project   <required>
 template  undef

append => STRING|CODE
manual => MANUAL: The manual to be formatted.
project => STRING: The name of this project, which will appear on many pages.
template => LOCATION: Some formatters support templates to descibe the output of the pages. The valid values for this option differs per formatter.

$obj->createOtherPages(%options)

Create other pages which come with the set of formatted manuals. What the contents of these pages is depends on the formatter. Some formatters simply ignore the functionality of this method as a whole: they do not support data-files which are not manuals.

-Option --Default
 process  undef
 source   undef

process => REGEXP: Selects files to be processed from the source directory. Other files are copied without modification. What happens with the selected files is formatter dependent.
source => DIRECTORY: The location of the DIRECTORY which contains files which are part of the produced set of documentation, but not copied per manual page but only once.

$obj->createPages(%options)

-Option          --Default
 append            undef
 manual_format     []
 manual_templates  undef
 other_templates   undef
 process_files     <formatter dependent>
 select            <all>

append => STRING|CODE: The value is passed on to createManual(append), but the behavior is formatter dependent.
manual_format => ARRAY: Options passed to createManual() when a manual page has to be produced. See the applicable formatter manual page for the possible flags and values.
manual_templates => DIRECTORY: Passed to createManual(template), and defines the location of the set of pages which has to be created for each manual page. Some formatters do not support templates and the valid values are formatter dependent.
other_templates => DIRECTORY: Other files which have to be copied passed to createOtherPages(source).
process_files => REGEXP: Selects the files which are to be processed for special markup information. Other files, like image files, will be simply copied. The value will be passed to createOtherPages(process).
select => CODE|REGEXP: Produce only the indicated manuals, which is useful in case of merging manuals from different distributions. When a REGEXP is provided, it will be checked against the manual name. The CODE reference will be called with a manual as only argument.

$obj->showChapter(%options)

You can pass all %options about formatting to this method. They will passed to the related methods. So: the list of options you can pass here is much longer: the combination of everything possible for all show* methods.

In the %options, $BLOCK can be chapter, section, subsection, and subsubsection.

-Option               --Default
 chapter                <required>
 manual                 <required>
 output                 <required>
 show_examples          'EXPAND'
 show_examples_$BLOCK   <show_examples>
 show_inherited         'REFER'
 show_inherited_$BLOCK  <show_inherited>

chapter => CHAPTER
manual => MANUAL
output => FILE
show_examples => 'NO'|'EXPAND'
show_examples_$BLOCK => 'NO'|'REFER'|'EXPAND'
show_inherited => 'NO'|'REFER'|'EXPAND': REFER means that inherited sections are simply listed as reference to the manual page which describes it.
show_inherited_$BLOCK => 'NO'|'REFER'|'EXPAND'

$obj->showExamples(%options)

-Option  --Default
 examples  <required>
 manual    <required>
 output    <required>

examples => ARRAY
manual => MANUAL
output => FILE

$obj->showOptionExpand(%options)

-Option --Default
 default  <required>
 manual   <required>
 option   <required>
 output   <required>

default => OBJECT
manual => OBJECT
option => OBJECT
output => FILE

$obj->showOptionTable(%options)

-Option --Default
 manual   <required>
 options  <required>
 output   <required>

manual => OBJECT
options => ARRAY
output => FILE

$obj->showOptionUse(%options)

-Option --Default
 default  <required>
 manual   <required>
 option   <required>
 output   <required>

default => OBJECT
manual => OBJECT
option => OBJECT
output => FILE

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

$obj->showOptions(%options)

The options shown are not the %options passed as argument, but the options which belong to the subroutine being displayed.

-Option                --Default
 manual                  <required>
 options                 <required>
 show_described_options  'EXPAND'
 show_inherited_options  'USE'

manual => OBJECT
options => ARRAY
show_described_options => 'NO'|'LIST'|'USE'|'EXPAND'
show_inherited_options => 'NO'|'LIST'|'USE'|'EXPAND'

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

$obj->showStructureExpanded(%options)

-Option       --Default
 show_examples  'EXPAND'

show_examples => 'NO'|'EXPAND'

$obj->showStructureRefer(%options)

$obj->showSubroutine(%options)

Show a single subroutine.

-Option                --Default
 last                    false
 manual                  <required>
 output                  <selected filehandle>
 show_described_options  'EXPAND'
 show_diagnostics        'NO'
 show_examples           'EXPAND'
 show_inherited_options  'USE'
 show_option_table       'ALL'
 show_sub_description    'DESCRIBED'
 show_subroutine         'EXPAND'
 subroutine              <required>

last => BOOLEAN
manual => $manual
output => FILE
show_described_options => 'NO'|'LIST'|'USE'|'EXPAND'
show_diagnostics => 'NO'|'EXPAND': Diagnostics (error and warning messages) are defined per subroutine, but are usually not listed with the subroutine. The POD formatter's default behavior, for instance, puts them all in a separate DIAGNOSTICS chapter per manual page.
show_examples => 'NO'|'EXPAND'
show_inherited_options => 'NO'|'LIST'|'USE'|'EXPAND'
show_option_table => 'NO'|'INHERITED'|'DESCRIBED'|'ALL'
show_sub_description => 'NO'|'DESCRIBED'|'REFER'|'ALL': Included the description of the use of the subroutines, which comes before the options are being explained. NO will cause the description to be ignored, DESCRIBED means that only text which was written in the manual-page at hand is included, REFER means that a reference to inherited documentation is made, and with ALL the inherited texts are expanded into this file as well.
show_subroutine => 'NO'|'NAMES'|'USE'|'EXPAND'
subroutine => OBJECT

$obj->showSubroutineDescription(%options)

-Option    --Default
 manual      <required>
 output      <required>
 subroutine  <required>

manual => OBJECT
output => FILE
subroutine => OBJECT

$obj->showSubroutineName(%options)

-Option    --Default
 last        0
 manual      <required>
 output      <required>
 subroutine  <required>

last => BOOLEAN
manual => OBJECT
output => FILE
subroutine => OBJECT

$obj->showSubroutineUse(%options)

-Option    --Default
 manual      <required>
 output      <required>
 subroutine  <required>

manual => OBJECT
output => FILE
subroutine => OBJECT

$obj->showSubroutines(%options)

-Option                --Default
 manual                  <required>
 output                  <selected filehandle>
 show_described_options  'EXPAND'
 show_described_subs     'EXPAND'
 show_diagnostics        'NO'
 show_examples           'EXPAND'
 show_inherited_options  'USE'
 show_inherited_subs     'USE'
 show_option_table       'ALL'
 show_subs_index         'NO'
 subroutines             []

manual => MANUAL
output => FILE
show_described_options => 'NO'|'LIST'|'USE'|'EXPAND'
show_described_subs => 'NO'|'NAMES'|'USE'|'EXPAND'
show_diagnostics => 'NO'|'EXPAND'
show_examples => 'NO'|'EXPAND'
show_inherited_options => 'NO'|'LIST'|'USE'|'EXPAND'
show_inherited_subs => 'NO'|'NAMES'|'USE'|'EXPAND'
show_option_table => 'NO'|'DESCRIBED'|'INHERITED'|'ALL'
show_subs_index => 'NO'|'NAMES'|'USE'
subroutines => ARRAY

DIAGNOSTICS

Error: formatter $name has compilation errors: $err: The formatter which is specified does not compile, so can not be used.
Error: formatter for $name 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: 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
Error: no formatter specified.
Error: no working directory specified for $name: The formatter has to know where the output can be written. This directory must be provided via new(workdir), but was not specified.

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)