NAME

OODoc::Format::Html - Produce HTML pages using Template::Magic

INHERITANCE

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

OODoc::Format::Html
  is a OODoc::Format::TemplateMagic

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 Template::Magic template system. Producing HTML is more complicated than producing POD, because one manual page may be spread over multiple output files.

METHODS

Constructors

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

-Option        --Defined in     --Default
 html_meta_data                   ''
 html_root                        '/'
 jump_script                      <html_root>/jump.cgi
 manifest        OODoc::Format    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

Inheritance knowledge

$obj->extends([OBJECT]): See "Inheritance knowledge" in OODoc::Object

Attributes

$obj->manifest: See "Attributes" in OODoc::Format
$obj->project: See "Attributes" in OODoc::Format
$obj->version: See "Attributes" in OODoc::Format
$obj->workdir: See "Attributes" in OODoc::Format

Page generation

$obj->cleanup(MANUAL, STRING)

See "Page generation" in OODoc::Format

$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->createManual(OPTIONS)

-Option        --Defined in     --Default
 append          OODoc::Format    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->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->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->showChapter(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showExamples(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showOptionExpand(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showOptionTable(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showOptionUse(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showOptionalChapter(NAME, OPTIONS)

See "Page generation" in OODoc::Format

$obj->showOptions(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showRequiredChapter(NAME, OPTIONS)

See "Page generation" in OODoc::Format

$obj->showStructureExpanded(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showStructureRefer(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showSubroutine((@))

See "Page generation" in OODoc::Format

$obj->showSubroutineDescription(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showSubroutineName(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showSubroutineUse(OPTIONS)

See "Page generation" in OODoc::Format

$obj->showSubroutines(OPTIONS)

See "Page generation" in OODoc::Format

$obj->writeTable

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

Template processing

$obj->format(OPTIONS)

-Option--Default
 manual  undef

manual => MANUAL

$obj->templateChapter

$obj->templateDate(ZONE, ARGS)

$obj->templateDistribution(ZONE, ARGS)

The name of the distribution which contains the manual page at hand.

$obj->templateHref(ZONE, ARGS)

$obj->templateIndex(ZONE, ARGS)

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       --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 or pipe 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(ZONE, ARGS)

$obj->templateList(ZONE, ARGS)

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

-Option          --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 Template::Magic does not accept commas in the tag parameter list, which is a pity.

$obj->templateManual(ZONE, ARGS)

$obj->templateMeta(ZONE, ARGS)

ARGS is a reference to a hash with options. ZONE contains the attributes in the template. Use new(html_meta_data) to set the result of this method, or extend its implementation.

$obj->templateName(ZONE, ARGS)

$obj->templateTitle(ZONE, ARGS)

$obj->templateVersion(ZONE, ARGS)

The version is taken from the manual (which means that you may have a different version number per manual) when a manual is being formatted, and otherwise the project total version.

Commonly used functions

$obj->filenameToPackage(FILENAME)

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

See "Commonly used functions" in OODoc::Object

$obj->mkdirhier(DIRECTORY)

OODoc::Format::Html->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

$obj->zoneGetParameters(ZONE|STRING): See "METHODS" in OODoc::Format::TemplateMagic

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

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

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)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

METHODS

Constructors

Inheritance knowledge

Attributes

Page generation

Template processing

Commonly used functions

Manual Repository

DIAGNOSTICS

SEE ALSO

LICENSE

Module Install Instructions