=head1 NAME OODoc::Format::Html - Produce HTML pages using Template::Magic =head1 INHERITANCE OODoc::Format::Html is a OODoc::Format is a OODoc::Object OODoc::Format::Html is a OODoc::Format::TemplateMagic =head1 SYNOPSIS my $doc = OODoc->new(...); $doc->createManual ( 'html' # or 'OODoc::Format::Html' , format_options => [show_examples => 'NO'] ); =head1 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. =head1 METHODS =head2 Constructors =over 4 =item OODoc::Format::Html-EB(OPTIONS) -Option --Defined in --Default html_meta_data '' html_root '/' jump_script /jump.cgi manifest OODoc::Format undef project OODoc::Format version OODoc::Format workdir OODoc::Format =over 2 =item html_meta_data => STRING Will be (usually) be added to the header, and may contain links to Cascading Style Sheets, and such. =item html_root => URI =item jump_script => URI =item manifest => OBJECT =item project => STRING =item version => STRING =item workdir => DIRECTORY =back =back =head2 Inheritance knowledge =over 4 =item $obj-EB([OBJECT]) See L =back =head2 Attributes =over 4 =item $obj-EB See L =item $obj-EB See L =item $obj-EB See L =item $obj-EB See L =back =head2 Page generation =over 4 =item $obj-EB(MANUAL, STRING) See L =item $obj-EB(MANUAL, OBJECT) The general L 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. =item $obj-EB(OPTIONS) -Option --Defined in --Default append OODoc::Format undef format_options OODoc::Format [] manual OODoc::Format project OODoc::Format template "html/manual/" =over 2 =item append => STRING|CODE =item format_options => ARRAY =item manual => MANUAL =item project => STRING =item 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 L values and the defaults. These options can be overruled by values specified in the template file. =back example: template specification Default: template => "html/manual/" Complex: template => { "man_index/" => [ show_examples => 'NO' ] , "man_main.html" => [ show_examples => 'EXPAND' ] } =item $obj-EB(OPTIONS) -Option --Defined in --Default process OODoc::Format qr/\.(s?html|cgi)$/ source OODoc::Format "html/other/" verbose OODoc::Format 0 =over 2 =item process => REGEXP =item source => DIRECTORY =item verbose => INTEGER =back =item $obj-EB(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 =item $obj-EB(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. =item $obj-EB(MANUAL, ID) Write a marker to items file. This locates an item to a frameset. =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(NAME, OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(NAME, OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB((@)) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB(OPTIONS) See L =item $obj-EB -Option--Default ARRAY header output =over 2 =item ARRAY => -OF-ARRAYS An array of arrays, each describing a row for the output. The first row is the header. =item header => ARRAY =item output => FILE =back =back =head2 Template processing =over 4 =item $obj-EB(OPTIONS) -Option--Default manual undef =over 2 =item manual => MANUAL =back =item $obj-EB =item $obj-EB(ZONE, ARGS) =item $obj-EB(ZONE, ARGS) The name of the distribution which contains the manual page at hand. =item $obj-EB(ZONE, ARGS) =item $obj-EB(ZONE, ARGS) The I template is called with one keyword, which tells the kind of index to be built. Valid values are C, C, C, and C
. 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' =over 2 =item 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. =item table_columns => INTEGER Produce a table with that number of columns. =item 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 I or I separated list of types, for instance C when subroutines are listed or C for diagnostics. =back example: use of the template tag "index"
=item $obj-EB(ZONE, ARGS) =item $obj-EB(ZONE, ARGS) The ZONE (which originate from the template file) start with the name of a chapter or C<'ALL'>. The rest of the ZONE are interpreted as argument list which overrule the OPTIONS. -Option --Default manual show_sections 'LINK' show_subroutines 'LIST' subroutine_types 'ALL' =over 2 =item manual => MANUAL =item 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. =item show_subroutines => 'NO'|'COUNT'|'LIST' =item subroutine_types => 'ALL'|LIST The LIST contains a I separated set of subroutine types which are selected to be displayed, for instance C. The separator underscore is used because Template::Magic does not accept commas in the tag parameter list, which is a pity. =back =item $obj-EB(ZONE, ARGS) =item $obj-EB(ZONE, ARGS) ARGS is a reference to a hash with options. ZONE contains the attributes in the template. Use L to set the result of this method, or extend its implementation. =item $obj-EB(ZONE, ARGS) =item $obj-EB(ZONE, ARGS) =item $obj-EB(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. =back =head2 Commonly used functions =over 4 =item $obj-EB(FILENAME) OODoc::Format::Html-EB(FILENAME) See L =item $obj-EB(DIRECTORY) OODoc::Format::Html-EB(DIRECTORY) See L =back =head2 Manual Repository =over 4 =item $obj-EB(MANUAL) See L =item $obj-EB(NAME) See L =item $obj-EB(NAME) See L =item $obj-EB See L =item $obj-EB(NAME) See L =item $obj-EB See L =back =over 4 =item $obj-EB(ZONE|STRING) See L =back =head1 DIAGNOSTICS =over 4 =item Error: cannot find chapter NAME in manual $name =item 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. =item Error: cannot write html manual at $filename: $! =item Error: chapter NAME in manual $name has illegal shape =item Error: chapter without name in template. In your template file, a {chapter} statement is used, which is erroneous, because it requires a chapter name. =item Error: html source directory $source does not exist. =item Error: illegal value to show_sections: $show_sec =item Error: manual definition requires manual object A call to L expects a new manual object (a L), however an incompatible thing was passed. Usually, intended was a call to L or L. =item Warning: missing required chapter $name in $manual =item Error: no directory to put other html pages in. =item 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. =item Error: no group named as attribute for list =item Warning: no meaning for container $contained in list block =item Warning: no meaning for container $container in chapter block =item Warning: no meaning for container $container in index block =item Error: no package name for html production =item Error: not a manual, so no automatic title in $template =item Error: not a manual, so no manual name for $template =item Error: not a manual, so no name for $template =item Error: unknown group $name as list attribute =item Warning: unknown subroutine type $type for $name in $manual =back =head1 SEE ALSO This module is part of OODoc distribution version 1.06, built on January 26, 2011. Website: F =head1 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 F