The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
OODoc-0.10
River stage zero No dependents
1 ++
/ OODoc::Format

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:

  • 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::Html

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

OVERLOADED

METHODS

Constructors

OODoc::Format->new(OPTIONS)

     Option    Defined in       Default   
 manifest                   C<undef>  
 project                    <required>
 version                    <required>
 workdir                    <required>

    . manifest OBJECT

    . project STRING

    . 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])

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->createInheritance(MANUAL)

    Create the text which represents the inheritance relationships of a certain package. More than one MANUAL can be defined for one package, and will each produce the same text. The returned string still has to be cleaned-up before inclusion.

$obj->createManual(OPTIONS)

     Option          Defined in       Default   
 append                           C<undef>  
 format_options                   []        
 manual                           <required>
 project                          <required>
 template                         C<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   Defined in       Default 
 process                   C<undef>
 source                    C<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                      Defined in       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    Defined in       Default   
 examples                   <required>
 manual                     <required>
 output                     <required>

    . examples ARRAY

    . manual MANUAL

    . output FILE

$obj->showOptionExpand(OPTIONS)

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

    . default OBJECT

    . manual OBJECT

    . option OBJECT

    . output FILE

$obj->showOptionTable(OPTIONS)

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

    . manual OBJECT

    . options ARRAY

    . output FILE

$obj->showOptionUse(OPTIONS)

     Option   Defined in       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                  Defined in       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                 Defined in  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                  Defined in       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      Defined in       Default   
 manual                       <required>
 output                       <required>
 subroutine                   <required>

    . manual OBJECT

    . output FILE

    . subroutine OBJECT

$obj->showSubroutineName(OPTIONS)

     Option      Defined in       Default   
 last                         0         
 manual                       <required>
 output                       <required>
 subroutine                   <required>

    . last BOOLEAN

    . manual OBJECT

    . output FILE

    . subroutine OBJECT

$obj->showSubroutineUse(OPTIONS)

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

    . manual OBJECT

    . output FILE

    . subroutine OBJECT

$obj->showSubroutines(OPTIONS)

     Option                  Defined in       Default              
 manual                                   <required>           
 output                                   <selected filehandle>
 show_described_options                   C<'EXPAND'>          
 show_described_subs                      C<'EXPAND'>          
 show_inherited_options                   C<'USE'>             
 show_inherited_subs                      C<'USE'>             
 show_option_table                        C<'ALL'>             
 show_subs_index                          C<'NO'>              
 subroutines                              C<[]>

    . manual MANUAL

    . output FILE

    . show_described_options 'NO'|'LIST'|'USE'|'EXPAND'

    . show_described_subs 'NO'|'NAMES'|'USE'|'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

Template::Magic

Support methods for implementations which are based on Template::Magic.

$obj->zoneGetParameters(ZONE|STRING)

    Takes a Template::Magic::Zone object to process the text after the tag. You may also specify a string, for instance a modified attribute list. The return is a list of key-value pairs with data.

    Example: of valid arguments

     <!--{examples expand NO list ALL}-->   # old style
 <!--{examples expand => NO, list => ALL}-->
 <!--{examples expand => NO,
         list => ALL}-->

Commonly used functions

$obj->filenameToPackage(FILENAME)

OODoc::Format->filenameToPackage(FILENAME)

$obj->mkdirhier(DIRECTORY)

OODoc::Format->mkdirhier(DIRECTORY)

Manual Repository

$obj->addManual(MANUAL)

$obj->mainManual(NAME)

$obj->manual(NAME)

$obj->manuals

$obj->manualsForPackage(NAME)

$obj->packageNames

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

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.