Mark Overmeer > OODoc-1.06 > OODoc::Format

Download:
OODoc-1.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 1.06   Source   Latest Release: OODoc-2.00

NAME ^

OODoc::Format - base class for all OODoc formatters

INHERITANCE ^

 OODoc::Format
   is a 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::create() is called on a OODoc object.

Currently available formatters:

METHODS ^

Constructors

OODoc::Format->new(OPTIONS)
 -Option  --Default
  manifest  undef
  project   <required>
  version   <required>
  workdir   <required>
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.

Inheritance knowledge

$obj->extends([OBJECT])

See "Inheritance knowledge" in OODoc::Object

Attributes

$obj->manifest

Returns the OODoc::Manifest object which maintains the names of created files.

$obj->project

Returns the name of this project.

$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.

Page generation

$obj->cleanup(MANUAL, STRING)

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

$obj->createManual(OPTIONS)
 -Option        --Default
  append          undef
  format_options  []
  manual          <required>
  project         <required>
  template        undef
append => STRING|CODE
format_options => ARRAY

An ARRAY which contains a list of options which are the defaults for formatting a chapter.

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
  verbose  0
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.

verbose => INTEGER
$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.

 -Option                    --Default
  chapter                     <required>
  manual                      <required>
  output                      <required>
  show_inherited_chapters     'REFER'
  show_inherited_sections     'REFER'
  show_inherited_subsections  'REFER'
chapter => CHAPTER
manual => MANUAL
output => FILE
show_inherited_chapters => 'NO'|'REFER'|'EXPAND'
show_inherited_sections => 'NO'|'REFER'|'EXPAND'

REFER means that inherited sections are simply listed as reference to the manual page which describes it.

show_inherited_subsections => '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_chapter_examples  'EXPAND'
show_chapter_examples => 'NO'|'EXPAND'

The chapter examples are all examples which are not subroutine related: examples which come at the end of a chapter, section, or subsection.

$obj->showStructureRefer(OPTIONS)
$obj->showSubroutine((@))
 -Option                --Default
  last                    0
  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

Commonly used functions

$obj->filenameToPackage(FILENAME)

OODoc::Format->filenameToPackage(FILENAME)

See "Commonly used functions" in OODoc::Object

$obj->mkdirhier(DIRECTORY)

OODoc::Format->mkdirhier(DIRECTORY)

See "Commonly used functions" in OODoc::Object

Manual Repository

$obj->addManual(MANUAL)

See "Manual Repository" in OODoc::Object

$obj->mainManual(NAME)

See "Manual Repository" in OODoc::Object

$obj->manual(NAME)

See "Manual Repository" in OODoc::Object

$obj->manuals

See "Manual Repository" in OODoc::Object

$obj->manualsForPackage(NAME)

See "Manual Repository" in OODoc::Object

$obj->packageNames

See "Manual Repository" in OODoc::Object

DIAGNOSTICS ^

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

SEE ALSO ^

This module is part of OODoc distribution version 1.06, built on January 26, 2011. Website: http://perl.overmeer.net/oodoc/

LICENSE ^

Copyrights 2003-2011 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: