The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PerlPoint-Template-Traditional-0.02
River stage zero No dependents
++
/ PerlPoint::Template::Traditional

NAME

PerlPoint::Template::Traditional - PerlPoint template processor for traditional pp2html layouts

VERSION

This manual describes version 0.02.

SYNOPSIS

DESCRIPTION

METHODS

new()

Parameters:

class

The class name.

Returns: the new object.

Example:

Template files

Following the tradition of pp2html, Traditional templates expect a page body to be described by up to four files which embed the page contents. The layer scheme is shown here:

 page body:    <body>

               top template

               optional top navigation template

               contents

               optional bottom navigation template

               bottom template

               </body>

Top and bottom template files are specified by options -top_template and -bottom_template for kernel pages, and -top_idx_template and -bottom_idx_template for index pages, and -top_toc_template and -bottom_toc_template for TOC pages.

Navigation template files are specified by -nav_top_template and -nav_bottom_template. These files are optional, the options can be omitted. If top and bottom navigation template are identical, one can use -nav_template to specify them both at once.

The <body> and </body> tags are no part of the templates, they are added automatically.

While in pp2html the header of a generated page was written automatically, it now became template driven as well. Use option -header_template (or header_idx_template or -header_toc_template, respectively) to specify the appropriate template.

A header template is built according to the same rules as body (part) templates, although there are template keywords that are designed for header use only, see below.

The following scheme shows the complete layer model, including tags added automatically. Those tags should not be written to the template files.

 page frame:   <html>

 page header:  <head>

               header template

               </head>

 page body:    <body>

               top template

               optional top navigation template

               - page contents -

               optional bottom navigation template

               bottom template

               </body>

 page frame:   </html>

Additionally, one can produce supplementary files such as frames. These files are templated completely, not in parts, and get specified by -doc_template for files to be produced once and -supplement_template (or -supplement_idx_template or -supplement_toc_template, respectively) for page specific files. The names of those generated files depend on the template names and are composed as a sequence of the -prefix value, the template file basename, a dash, the page number. another dash and the value of option -suffix for page specific files (<prefix-<tfile>-<pagenumber><suffix>>, example: doc-baseframe-10.html). For document specific files templated via -doc_template, the rule is <prefix-<tfile><suffix>>, example: doc-frameset.html. Each of these template options can be specified multiply, to produce as many files as you are in need of.

 Example: To produce a frameset with three frames
          (top, contents, bottom), we need a frameset
          file (one for all pages given we can navigate
          internally), and three frame files per chapter,
          which are the usual contents file plus two
          extra files for the page specific top and
          bottom frames.

          These options will do the job:

           -prefix doc -suffix .${\( lc($me->{generator}{options}{target}) )}

           -doc_template frameset.tpl
           -supplement_template topframe.tpl
           -supplement_template bottomframe.tpl

          plus the usual options to template the contents
          page (which is the middle frame here).

          As a result, we will get

            - one file doc-frameset.${\( lc($me->{generator}{options}{target}) )}
            - and three files per page:

               * doc-topframe-<page>.${\( lc($me->{generator}{options}{target}) )}
               * doc-<page>.${\( lc($me->{generator}{options}{target}) )}
               * doc-bottomframe-<page>.${\( lc($me->{generator}{options}{target}) )}

Knowing how the filenames are build, all files can be interlinked with ease.

Keywords

The keywords supported in Traditional templates are listed in the following.

BOT_LEFT_TXT

Inserts the text specified by option -bot_left_txt.

BOT_MIDDLE_TXT

Inserts the text specified by option -bot_middle_txt.

BOT_RIGHT_TXT

Inserts the text specified by option -bot_right_txt.

BOOTSTRAP_ADDRESS

Inserts the URL specified by option -boostrapaddress, pointing to the absolute start URL (a page that does not need to be generated, by the way).

DATE(<format>)

This is a function and will be replaced by the current data and time, formatted via POSIX::strftime(). The <format> is required in POSIX::strftime() syntax.

 Example: DATE(%c)
DOCAUTHOR

The document author, as specified by option -docauthor.

DOCDATE

The document date/time string, as configured by option -docdate.

DOCSUBTITLE

The document subtitle, as specified by option -docsubtitle.

DOCTITLE

The document title, as specified by option -doctitle.

LABEL_CONTENTS

Inserts the text specified by option -label_contents.

LABEL_INDEX

Inserts the text specified by option -label_index.

LABEL_NEXT

Inserts the text specified by option -label_next.

LABEL_PREV

Inserts the text specified by option -label_prev.

LOGO_IMAGE_FILENAME
OPT(<option>, <text>)

Inserts <text> if <option> is set. The <text> can contain further keywords, except for nested OPT() calls.

For reasons of parsing, make sure the closing paren is the last paren in the template line, as the function consumes everything till there.

 Example: OPT(flavicon, <p>These pages use flavicons.</p>)
PAGE_CONTENTS

The page number of the TOC page.

PAGE_FIRST

The page number of the first page.

PAGE_HERE

The page number of the current page.

PAGE_INDEX

The page number of the index page, if any.

PAGE_LAST

The page number of the last page.

PAGE_NEXT

The page number of the next page, if any.

PAGE_PATH

This inserts the "path" of the current chapter, which is a sequence of (short) chapter titles (being links to the chapters), leading from root to the current page. This is useful for navigation, to allow readers quick jumps to higher level base chapters.

The start URL specified by -bootstrapaddress always starts the path. Levels are delimited by slashes.

 Example: If in the hierarchy of chapters

            1. Root Level

            1.1. Sublevel

            1.2. More about this

            1.2.1. Example

          the PAGE_PATH keyword should be replaced on every page,
          the result would be

            for 1.: Start URL

            for 1.1.: Start URL / Root Level

            for 1.2.: Start URL / Root Level

            for 1.2.1.: Start URL / Root level / More about this
PAGE_PREV

The page number of the previous page, if any.

PAGE_UP

The page number of the parent page.

REF(<separator><whitespace(s)><address> <separator> <text>)

A link to a document anchor, described by <address>. Addresses are specified the same way as in the name option of \REF tags, see there for details. The <text> is used to set up the link text. Address and text are delimited by a string defined as <separator>. The whitespace after the separator definition is mandatory, more whitespaces can be used at your option.

Examples:

  REF(, An interesting chapter, Chapter)

  REF(--- Overview | perl, parl and PAR --- A PAR intro)

Closing parens within addresses or texts have to be preceeded by a backslash.

  REF(# Tools (par and parl\) # Tools)
START_ADDRESS

Inserts the URL specified by option -startaddress, pointing to the very first page.

TREE_APPLET_TOC

Inserts code for the free Java navigation applet traditionally provided with pp2html. Different to pp2html, the "Traditional" template engine does not generate applet TOC pages on its own, but it supports styles that build such pages. To do so, just use this wildcard in a TOC template specified by -top_toc_template or -bottom_toc_template.

If the wildcard is used, the template engine copies all necessary Java files into the directory specified by option -appletdir. Other related options are -appletdir (or -applet_dir), -appletref (or -applet_ref), -tree_app_hint, -tree_app_height, -tree_app_width and -tree_base.

TXT_CONTENTS

The title of the TOC page.

TXT_FIRST

The title of the first page.

TXT_HERE

The title of the current page.

TXT_INDEX

The title of the index page, if any.

TXT_LAST

The title of the last page.

TXT_NEXT

The title of the next page, if any.

TXT_PREV

The title of the previous page, if any.

TXT_UP

The title of the parent page.

TOP_LEFT_TXT

Inserts the text specified by option -top_left_txt.

TOP_MIDDLE_TXT

Inserts the text specified by option -top_middle_txt.

TOP_RIGHT_TXT
TITLE

The page title (chapter headline).

URL_CONTENTS

The URL of the TOC page.

URL_FIRST

The URL of the first page.

URL_HERE

The URL of the current page.

URL_INDEX

The URL of the index page, if any.

URL_LAST

The URL of the last page.

URL_NEXT

The URL of the next page, if any.

URL_PREV

The URL of the previous page, if any.

URL_UP

The URL of the parent page.

VAR(<var>) or VAR_AT_FINISH(<var>)

Inserts the value of the PerlPoint variable <var>, with the value available at the end of the chapter.

 Example: VAR(language)
VAR_AT_BEGIN(<var>)

Inserts the value of the PerlPoint variable <var>, with the value available at the beginning of the chapter.

 Example: VAR_AT_BEGIN(language)
CSS_LINKTAGS

Inserts tags to load CSS files specified by option -css. The stylesheet specified first will be made the main stylesheet, while all subsequently specified sheets will be included as alternatives, in the order they were declared.

According to the specs, this keyword should be used in header templates only. (This will not be checked by the template engine.)

DOC_METATAGS

According to the specs, this keyword should be used in header templates only. (This will not be checked by the template engine.)

FAVICON_LINKTAG

Inserts a favicon link tag referring to the icon specified by option -favicon. If the option was omitted, the keyword will be replaced by an empty string.

For details about favicons, please see the description of -favicon.

According to the specs, this keyword should be used in header templates only. (This will not be checked by the template engine.)

Inserts navigation link tags as specified by the W3C (<link rel="start" ...> etc.). Most modern browsers translate them into navigation buttons to the first, previous, next etc. page.

According to the specs, this keyword should be used in header templates only. (This will not be checked by the template engine.)

PAGE

The number of the current page. Counting starts with 1.

PAGE_CNT

The number of chapters (pages) in the document.

 Example: to display "page x of y", use

          PAGE/PAGE_CNT
TITLE

This will insert the document title, as specified by option -title.

NOTES

SEE ALSO

SUPPORT

A PerlPoint mailing list is set up to discuss usage, ideas, bugs, suggestions and translator development. To subscribe, please send an empty message to perlpoint-subscribe@perl.org.

If you prefer, you can contact me via perl@jochen-stenzel.de as well.

AUTHOR

Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2004-2006. All rights reserved.

This module is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.

The Artistic License should have been included in your distribution of Perl. It resides in the file named "Artistic" at the top-level of the Perl source tree (where Perl was downloaded/unpacked - ask your system administrator if you dont know where this is). Alternatively, the current version of the Artistic License distributed with Perl can be viewed on-line on the World-Wide Web (WWW) from the following URL: http://www.perl.com/perl/misc/Artistic.html

DISCLAIMER

This software is distributed in the hope that it will be useful, but is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or implied, INCLUDING, without limitation, the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.

The ENTIRE RISK as to the quality and performance of the software IS WITH YOU (the holder of the software). Should the software prove defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even if they arise from known or unknown flaws in the software).

Please refer to the Artistic License that came with your Perl distribution for more details.