NAME

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

INHERITANCE

OODoc::Format::Html
  is an OODoc::Format
  is an OODoc::Object

SYNOPSIS

my $doc = OODoc->new(...);
$doc->formatter('html')->createPages(
   manual_options => [ show_examples => 'NO' ],
);

DESCRIPTION

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

Extends "DESCRIPTION" in OODoc::Format.

OVERLOADED

Extends "OVERLOADED" in OODoc::Format.

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

METHODS

Extends "METHODS" in OODoc::Format.

Constructors

Extends "Constructors" in OODoc::Format.

$class->new(%options)

Inherited, see "Constructors" in OODoc::Object

-Option         --Defined in     --Default
 format           OODoc::Format    'html'
 html_meta_data                    ''
 html_root                         '/'
 html_stylesheet                   undef
 index            OODoc::Format    <required>
 jump_script                       <html_root>/jump.cgi
 manifest         OODoc::Format    undef
 project          OODoc::Format    <required>
 version          OODoc::Format    <required>
 workdir          OODoc::Format    <required>

format => 'pod*'|'html*'|PACKAGE
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
html_stylesheet => STRING: Adds a link to the stylesheet to the meta-data.
index => OODoc::Index
jump_script => URI
manifest => OBJECT
project => STRING
version => STRING
workdir => DIRECTORY

Attributes

Extends "Attributes" in OODoc::Format.

$obj->filename( [$filename] ): The name of the documentation file which createManual() is currently processing.
$obj->format(): Inherited, see "Attributes" in OODoc::Format
$obj->htmlRoot(): Without trailing slash.
$obj->index(): Inherited, see "Attributes" in OODoc::Format
$obj->jumpScript()
$obj->manifest(): Inherited, see "Attributes" in OODoc::Format
$obj->manual( [$manual] ): Returns (optionally after setting) the $manual which is being processed.
$obj->markers( [$filehandle] ): The filehandle where createManual() writes the 'mark's to: the jump points.
$obj->meta(): Returns a string with html for the page header block.
$obj->project(): Inherited, see "Attributes" in OODoc::Format
$obj->publish(\%options): Inherited, see "Attributes" in OODoc::Object
$obj->unique(): Inherited, see "Attributes" in OODoc::Object
$obj->version(): Inherited, see "Attributes" in OODoc::Format
$obj->workdir(): Inherited, see "Attributes" in OODoc::Format

Page generation

Extends "Page generation" in OODoc::Format.

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

Inherited, see "Page generation" in OODoc::Format

$obj->cleanupString($manual, $string, %options)

The general OODoc::Parser::cleanupHtml() is 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. Improves base, see "Page generation" in OODoc::Format

$obj->createManual(%options)

Inherited, see "Page generation" in OODoc::Format

-Option  --Defined in     --Default
 append    OODoc::Format    undef
 manual    OODoc::Format    <required>
 project   OODoc::Format    <required>
 template                   "html/manual/"

append => STRING|CODE
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 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)

Inherited, see "Page generation" in OODoc::Format

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

process => REGEXP
source => DIRECTORY

$obj->createPages(%options)

Inherited, see "Page generation" in OODoc::Format

$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, [ ($html|undef), \%settings ] )

Create the html for a link which refers to the $object. The link will be shown somewhere in the $manual. The $html 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)

Inherited, see "Page generation" in OODoc::Format

$obj->showExamples(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionExpand(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionTable(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showOptionUse(%options)

Inherited, see "Page generation" in OODoc::Format

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

Inherited, see "Page generation" in OODoc::Format

$obj->showOptions(%options)

Inherited, see "Page generation" in OODoc::Format

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

Inherited, see "Page generation" in OODoc::Format

$obj->showStructureExpanded(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showStructureRefer(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutine(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutineDescription(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutineName(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutineUse(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->showSubroutines(%options)

Inherited, see "Page generation" in OODoc::Format

$obj->writeTable(%options)

-Option--Default
 header  <required>
 output  <required>
 rows    <required>

header => ARRAY
output => FILE
rows => ARRAY-OF-ARRAYS: An array of arrays, each describing a row for the output. The first row is the header.

Template processing

$obj->interpolate(%options)

-Option--Default
 manual  undef

manual => MANUAL

$any->mkdirhier($directory)

Creates this $directory and all its non-existing parents.

$obj->templateChapter()

$obj->templateDate($templ, $attrs, $if, $else)

$obj->templateDistribution($templ, $attrs, $if, $else)

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

$obj->templateHref($templ, $attrs, $if, $else)

$obj->templateIndex($templ, \%options, $if, $else)

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($templ, $attrs, $if, $else)

$obj->templateList($templ, \%options, $if, $else)

-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($templ, $attrs, $if, $else)

$obj->templateMeta($templ, $attrs, $if, $else)

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($templ, $attrs, $if, $else)

$obj->templateProject($templ, $attrs, $if, $else)

$obj->templateTitle($templ, $attrs, $if, $else)

$obj->templateVersion($templ, $attrs, $if, $else)

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.

DIAGNOSTICS

Error: cannot find chapter NAME in manual $file: Cast by templateName()
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. Cast by expandTemplate()
Fault: cannot write html manual to $file: $!: Cast by createManual()
Fault: cannot write html to $fn: $!: Cast by createOtherPages()
Fault: cannot write markers to $file: $!: Cast by createManual()
Error: chapter NAME in manual $manual has illegal shape: Cast by templateName()
Error: chapter without name in template $file: Cast by templateChapter()
Error: chapter without name in template $fn: In your template file, a {chapter} statement is used, which is erroneous, because it requires a chapter name. Cast by templateChapter()
Fault: chmod of $fn to $mode failed: $!: Cast by createOtherPages()
Fault: copy from $from to $to failed: $!: Cast by createOtherPages()
Error: expect one name with 'a': Cast by templateHref()
Fault: html source directory $dir: $!: Cast by createOtherPages()
Error: illegal show option choice: $value: Cast by showOptions()
Error: illegal value for show_option_table: $value: Cast by showSubroutine()
Error: illegal value for show_sub_description: $value: Cast by showSubroutine()
Error: illegal value for show_subroutine: $value: Cast by showSubroutine()
Error: illegal value to show_sections: $value: Cast by templateList()
Error: missing path for $dest: Cast by templateHref()
Error: missing required chapter $name in $manual: Cast by showRequiredChapter()
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. Cast by templateList()
Error: no group named as attribute for list: Cast by templateIndex()
Warning: no meaning for container $tags in chapter block: Cast by templateChapter()
Warning: no meaning for container $tags in index block: Cast by templateList()
Warning: no meaning for container $tags in list block: Cast by templateIndex()
Error: not a manual, so no automatic template title in $file: Cast by templateTitle()
Error: not a manual, so no manual name for template $file: Cast by templateManual()
Error: not a manual, so no name for template $file: Cast by templateName()
Error: unknown group $name as list attribute: Cast by templateIndex()

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)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

OVERLOADED

METHODS

Constructors

Attributes

Page generation

Template processing

DIAGNOSTICS

SEE ALSO

LICENSE

Module Install Instructions