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.04
River stage zero No dependents
/ OODoc::Format::Html

NAME

OODoc::Format::Html - Produce HTML pages from the doc tree

INHERITANCE

 OODoc::Format::Html
   is a OODoc::Format
   is a OODoc::Object

SYNOPSIS

 my $doc = OODoc->new(...);
 $doc->createManual
   ( 'html'   # or 'OODoc::Format::Html'
   , format_options => [show_examples => 'NO']
   );

DESCRIPTION

Create manual pages in the HTML syntax, using the Text::MagicTemplate subroutine template system. Producing HTML is more complicated than producing POD, because one manual page may be spread over multiple output files.

METHODS

$obj->cleanupString(MANUAL, OBJECT)

    The general cleanup() is too over eager: it turns all pieces of text into paragraphs. So things, like names of chapters, are not paragraphs at all: these simple strings are to be cleaned from paragraph information.

$obj->expandTemplate(LOCATION, [FORMAT])

    Translate a filename, directory name or hash with file/directory names which are specified as LOCATION for templates into hash of filenames names and related formatting options. The FORMAT is an array of options which can be overruled by values which the LOCATION is specified as hash.

    Example: expanding template specification into files

     my $exp = $self->expandTemplate("html/manual", [show => 'NO']);
 while(my ($fn,$opts) = each %$exp) {print "$fn @$opts\n"}
 # may print something like
 #   index.html show NO
 #   main.html show NO

 my $exp = $self->expandTemplate(
   { "html/manual/index.html" => [show => 'YES']
     "html/manual/main.html"  => []
   } , [show => 'NO']);
 # will print something like
 #   index.html show YES
 #   main.html show NO

$obj->format(OPTIONS)

     Option  Defined in  Default 
 manual              C<undef>

    . manual MANUAL

$obj->link(MANUAL, OBJECT, [TEXT])

    Create the html for a link which refers to the OBJECT. The link will be shown somewhere in the MANUAL. The TEXT is displayed as link, and defaults to the name of the OBJECT.

$obj->mark(MANUAL, ID)

    Write a marker to items file. This locates an item to a frameset.

$obj->templateChapter

$obj->templateIndex(ATTRS, OPTIONS)

    The index template is called with one keyword, which tells the kind of index to be built. Valid values are MANUALS, SUBROUTINES, DIAGNOSTICS, and DETAILS. In the future, more names may get defined.

    The tag produces a list of columns which should be put in a table container to produce valid html.

     Option         Defined in       Default
 starting_with                   'ALL'  
 table_columns                   2      
 type                            'ALL'

    . starting_with 'ALL'|STRING

      Only selects the objects which have names which start with the STRING (case-insensitive match). Underscores in the string are interpreted as any non-word character or underscore.

    . table_columns INTEGER

      Produce a table with that number of columns.

    . type 'ALL'|STRING

      The types of objects which are to be selected, which is not applicable to all kinds of indexes. The STRING may contain an underscore separated list of types, for instance method_tie when subroutines are listed or error for diagnostics.

    Example: use of the template tag "index"

     <table cellspacing="10">
 <!--{index DIAGNOSTICS type error starting_with A}-->
 </table>

$obj->templateInheritance(OPTIONS)

$obj->templateList(ATTRS, OPTIONS)

    The ATTRS (which originate from the template file) start with the name of a chapter or 'ALL'. The rest of the ATTRS are interpreted as argument list which overrule the OPTIONS.

     Option            Defined in       Default   
 manual                             <required>
 show_sections                      'LINK'    
 show_subroutines                   'LIST'    
 subroutine_types                   'ALL'

    . manual MANUAL

    . show_sections 'NO'|'NAME'|'LINK'

      This option is only used when a chapter name is specified. It tells how to treat sections within the chapter: must they be shown expanded or should the subroutines be listed within the chapter.

    . show_subroutines 'NO'|'COUNT'|'LIST'

    . subroutine_types 'ALL'|LIST

      The LIST contains a underscore separated set of subroutine types which are selected to be displayed, for instance method_tie_function. The separator underscore is used because Text::MagicTemplate subroutine does not accept commas in the tag parameter list, which is a pity.

$obj->templateMeta(ATTR, ARGS)

    ARGS is a reference to a hash with options. ATTR contains the attributes in the template.

$obj->writeTable

     Option  Defined in       Default   
 ARRAY                    <required>
 header                   <required>
 output                   <required>

    . ARRAY -OF-ARRAYS

      An array of arrays, each describing a row for the output. The first row is the header.

    . header ARRAY

    . output FILE

Initiation

OODoc::Format::Html->new(OPTIONS)

     Option          Defined in       Default             
 html_meta_data                   ''                  
 html_root                        '/'                 
 jump_script                      <html_root>/jump.cgi
 manifest        OODoc::Format    C<undef>            
 project         OODoc::Format    <required>          
 version         OODoc::Format    <required>          
 workdir         OODoc::Format    <required>

    . html_meta_data STRING

      Will be (usually) be added to the header, and may contain links to Cascading Style Sheets, and such.

    . html_root URI

    . jump_script URI

    . manifest OBJECT

    . project STRING

    . version STRING

    . workdir DIRECTORY

Collected

$obj->extends([OBJECT])

Commonly used functions

$obj->filenameToPackage(FILENAME)

OODoc::Format::Html->filenameToPackage(FILENAME)

$obj->mkdirhier(DIRECTORY)

OODoc::Format::Html->mkdirhier(DIRECTORY)

Manual Repository

$obj->addManual(MANUAL)

$obj->mainManual(NAME)

$obj->manuals

$obj->manualsForPackage(NAME)

$obj->packageNames

Attributes

$obj->cleanup(MANUAL, STRING)

$obj->createInheritance(MANUAL)

$obj->createManual(OPTIONS)

     Option          Defined in       Default       
 append          OODoc::Format    C<undef>      
 format_options  OODoc::Format    []            
 manual          OODoc::Format    <required>    
 project         OODoc::Format    <required>    
 template                         "html/manual/"

    . append STRING|CODE

    . format_options ARRAY

    . manual MANUAL

    . project STRING

    . template DIRECTORY|HASH

      A DIRECTORY containing all template files which have to be filled-in and copied per manual page created. You may also specify an HASH of file- and directory names and format options for each of those files. These options overrule the general createManual(format_options) values and the defaults. These options can be overruled by values specified in the template file.

    Example: template specification

    Default:

     template => "html/manual/"

    Complex:

     template => { "man_index/"    => [ show_examples => 'NO' ]
             , "man_main.html" => [ show_examples => 'EXPAND' ]
             }

$obj->createOtherPages(OPTIONS)

     Option   Defined in       Default            
 process  OODoc::Format    qr/\.(s?html|cgi)$/
 source   OODoc::Format    "html/other/"      
 verbose  OODoc::Format    0

    . process REGEXP

    . source DIRECTORY

    . verbose INTEGER

$obj->manifest

$obj->project

$obj->showChapter(OPTIONS)

$obj->showExamples(OPTIONS)

$obj->showOptionExpand(OPTIONS)

$obj->showOptionTable(OPTIONS)

$obj->showOptionUse(OPTIONS)

$obj->showOptionalChapter(NAME, OPTIONS)

$obj->showOptions(OPTIONS)

$obj->showRequiredChapter(NAME, OPTIONS)

$obj->showStructureExpanded(OPTIONS)

$obj->showStructureRefer(OPTIONS)

$obj->showSubroutine((@))

$obj->showSubroutineDescription(OPTIONS)

$obj->showSubroutineName(OPTIONS)

$obj->showSubroutineUse(OPTIONS)

$obj->showSubroutines(OPTIONS)

$obj->version

$obj->workdir

DIAGNOSTICS

Error: cannot find chapter NAME in manual $name

Error: cannot find template source $name

Somewhere was specified to use $name (a file or directory) as source for a template. However, it does not seem to exist. Unfortunately, the location where the source is specified is not known when the error is produced.

Error: cannot write html manual at $filename: $!

Error: chapter NAME in manual $name has illegal shape

Error: chapter without name in template.

In your template file, a {chapter} statement is used, which is erroneous, because it requires a chapter name.

Error: html source directory $source does not exist.

Error: illegal value to show_sections: $show_sec

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 directory to put other html pages in.

Error: no group named as attribute for index

In your template file, an {index} statement is used without a chapter name or 'ALL'. Therefore, it is unclear which kind of index has to be built.

Error: no group named as attribute for list

Warning: no meaning for container $contained in list block

Warning: no meaning for container $container in chapter block

Warning: no meaning for container $container in index block

Error: no package name for html production

Error: not a manual, so no automatic title in $template

Error: not a manual, so no manual name for $template

Error: not a manual, so no name for $template

Error: unknown group $name as list attribute

Warning: unknown subroutine type $type for $name in $manual

DETAILS

Configuring

REFERENCES

See the OODoc website at http://perl.overmeer.net/oodoc/ for more details.

COPYRIGHTS

Module version 0.04. 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.