DragonFly On-Line Manual Pages

PP2HTML(1) User Contributed Perl Documentation PP2HTML(1)

NAME
pp2html - PerlPoint to HTML converter

VERSION
This man page describes $Revision: 1.22 $ from PerlPoint::Converters
Package 1.0205

SYNOPSIS
pp2html --help
pp2html [@options_file] [options] slide_text

DESCRIPTION
"pp2html" creates a set of HTML files for a foilset based on a simple
textfile slide_text. Due to its formatting features and the capability
of creating navigation, table of contents and index pages, "pp2html" is
also a suitable tool for writing online documentation.

A slide is normally made up by a header and a number of bullet items:

=Example of a Slide

* Contains a head line ("Example of a Slide")

* Should have some bullet items

* May have footer and/or header section with company logo
and navigation links

The intention of "pp2html" is to simply write down your headers and
bullet items just like above in an ASCII file and then automatically
create a set of HTML files ready for presentation.

The main features of "pp2html" are:

o Simple ASCII input file for your text

o Optional templates for header and footer of the slides (e.g. for
company logo, hyperlinks for navigation, copyright note etc.)

o Rudimentary formatting capabilities

o Creation of a contents page with links to all slides

o Creation of an index page with links to all keywords which have
been indexed

o Optional layout as HTML frame set (header frame, contents frame,
footer frame and eventually index frame). The footer frame has
always the same position on the screen.

o The index frame may use a TreeApplet which provides convenient
access to all pages.

For more information see: http://www.naturallyj.com

The PerlPoint-Converters package contains an older version of the
tree applet. The new release of the tree applet is not yet
supported.

The following documentation describes in detail the syntax of a pp2html
input file and all options of "pp2html".

SYNTAX of PerlPoint Files
The format for the "pp2html" input files is called "PerlPoint"-Format.
For a detailed and possibly more up-to-date description of the
"PerlPoint" language please refer to the excellent POD documentation of
the PerlPoint::Parser Module by Jochen Stenzel.

There are the following main components of an input file for "pp2html":

o Comments

o Headers

o Bullet Items

o Numbered Lists

o Definition Lists

o Paragraphs

o Blocks

o Verbatim Blocks

Comments
Lines which start with a double slash "//" are treated as comments.
They are not included in the slides.

Headers
Headers are lines which start with one or more "=" signs. The number
of "=" signs determines the level of the header:

=This is a level 1 header

==This is a level 2 header

It is necessary to put a blank line after the header. If you use
headers of different levels then you get a structured document with
chapter numbering e.g.

1 First chapter
1.1 Subsection 1
1.2 Subsection 2
2 Second chapter

The chapter numbers depend on the position of the page and the level of
its header.

Bullet Items and Numbered Lists
A bullet item is indicated by an asterisk "*" in the first column.

* Item one is very long
and continued on the next line

* Item 2

* Item Three

If you use hash signs "#" instead of asterisks, the list will
autmatically be a numbered list:

# First

# Second

Note: It is important to put a blank line after each bullet item,
otherwise the text on the following line belongs to the same bullet.

Paragraphs
Text which is not indented is treated as a normal paragraph. In HTML
terminology this is a <P> ... </P> container.

Blocks
Text which is indented by one ore more blanks will be put in a colored
box. The text will be treated as pre formatted. Special formatting
tags (see below) are still applied.

The HTML representation is a <TABLE> with colored background and the
text itself is put into a <PRE> ... </PRE> container.

Verbatim Blocks
Verbatim Blocks are copied as is into the HTML page. Special formatting
tags (see below) are not applied. (Only HTML meta characters are
escaped, for example the "<" or ">" sign.) This means that Verbatim
Blocks are suitable for code examples: Just cut and paste your piece of
code into the "pp2html" input file and put the verbatim box markers
around:

<<END_OF_BOX
sub verbatim_text
{
for example some piece of code;
}
END_OF_BOX

The block begins with `<<MARK' and ends with the text "MARK" on a
separate line. This is like a "here document" in perl or in a C-shell.
Note: There must not be white space between << and MARK.

Alternatively you can use the \INCLUDE tag with the example option:

\INCLUDE{type=example file="filename"}

Special Formatting Tags
Some rudimentary formatting is also supported by "pp2html". It is
similar syntax as in POD:

\C<this is code>
\B<bold face>
\I<italic>
\E<lt> \E<gt>
\E<uml>
\U<underline>
\SUP<superscript>
\SUB<subscript>

Note that the tags are preceeded by a backslash. This is necessary
because the "PerlPoint" format knows several tags that are longer than
one character. The general form of "PerlPoint" tags is

\TAGNAME{param1=value1 param2=value2 ...}<tag body>

The parameter list is optional and enclosed in curly braces.

It is possible to switch the box color from case to case with the
following tags:

\BOXCOLORS{bg=yellow}

\BOXCOLORS{fg=blue}

or in short: \BOXCOLORS{bg=yellow fg=blue}

Color and text size
There is a special tag

\F{color=value size=value face=typeface}<text>

which allows to set color and size and the typeface for a text. This is
translated to the HTML <FONT> tag.

Using Hyperlinks
In order to use internal hyperlinks there must be targets for those
links. A link target or "anchor" is defined by the following tag:

\A{name="target_name"}

An internal link to this target is written in the form:

\PAGEREF{name=target_name}
\SECTIONREF{name=target_name}

The first link is replaced with the page number of the page which
contains the target. The second link is replaced with the page header
of the corresponding page.

NOTE: Each page automatically gets an anchor with the page header as
target name. For this reason it is possible to use SECTIONREF tags with
the name=page_title parameter to get inernal links to each page.

External hyperlinks have the form:

\L{url=http://wwwpixel.de}<http//www.pixel.de>

Index and Cross References
A cross reference to an internal target has the form:

\XREF{name=target_name}<text of cross ref>

Index entries are defined by

\X<word>
\X{mode=index_only}<text, special>

The latter form creates an index entry which appears only in the index.
The "word" from the the first form appears in the current text and in
the index.

Note: The index_only form is useful, for example, if you want to have a
word from a heading included in the index. The index tag is not allowed
inside of a heading.

OPTIONS
--activeContents
PerlPoint sources can embed Perl code which is evaluated while the
source is parsed. For reasons of security this feature is
deactivated by default. Set this option to activate it. You can use
--safeOpcode to fine tune which operations shall be permitted.

--cache
parsing of one and the same document several times can be
accelerated by activating the PerlPoint parser cache by this
option. The performance boost depends on your document structure.

Cache files are written besides the source and named ".<source
file>.ppcache".

It can be useful to (temporarily) deactivate the cache to get
correct line numbers in parser error messages (currently numbers
cannot always reported correctly with activated cache because of a
special perl behaviour).

--cacheCleanup
PerlPoint parser cache files grow (with every modified version of a
source parsed) because they store expressions for every parsed
variant of a paragraph. This is usually uncritical but you may wish
to clean up the cache occasionally. Use this option to perform the
task (or remove the cache file manually).

--safeOpcode=opcode
If active contents is enabled (--activeContents), Perl code
embedded into the translated PerlPoint sources will be evaluated.
To keep security this is done via an object of class Safe which
restricts code to permitted operations. By this option you can
declare which opcode (or opcode tag) is permitted. Please see the
Safe and Opcode manual pages for further details. (These modules
come with perl.)

Pass "ALL" to allow everything.

This option can be used multiply.

You may want to store these options in default option files, see
below for details.

For the examples used in ppdoc.pp you should use

--safeOpcode=:filesys_open --safeOpcode=:still_to_be_decided --safeOpcode=:browse

--set=flag
This option allows you to pass certain settings - of your choice -
to active contents (like conditions) where it can be accessed via
the $PerlPoint hash reference. For example, your PerlPoint code
could contain a condition like

? $PerlPoint->{userSettings}{special}

Special part.

? 1

The special part enclosed by the two conditions would then be
processed only if you call "pp2html" with

--set special

and if active contents was enabled by -active, of course.

This option can be used multiply.

--trans_table=filename
The "--trans_table" option specifies a the filename of a tanslation
table for non ASCII characters like german Umlaute etc. The
characters are specifed as octal numbers as in the folowing
example:

#Translation Table for German Umlaute (this is the default)

\334 Ü
\374 ü

\326 Ö
\366 ö

\304 Ä
\344 ä

\337 ß

--filter=regexp
This specifies a regular expression "regexp" which should match all
allowed languages for EMBEDed code. The expression is evaluated
caseinsensitively.

Example: --filter="perl|html"

--nocopyright
suppresses the copyright message;

--noinfo
supresses runtime informations;

--nowarn
supresses warnings;

--quiet
a shortcut for "--nocopyright --noinfo --nowarn": all non critical
runtime messages are suppressed;

--count_only
If this option is set, only a counter will indicate that slides are
created. Otherwise for all slides the full header is printed while
generating the slides.

--box_color=color
--boxtext_color=color
Set background and forground colors for block paragraphs

--bgcolor=color
--fgcolor=color
--idx_bgcolor=color
--idx_fgcolor=color
--toc_bgcolor=color
--toc_fgcolor=color
--top_bgcolor=color
--top_fgcolor=color
--bot_bgcolor=color
--bot_fgcolor=color
--linkcolor=color
--alinkcolor=color
--vlinkcolor=color
Set the background and foreground color for all HTML pages. The
"idx_" and "toc_" options are for the index page and table of
contents respectively. The last three options set the colors for
hyperlinks, active links and followed links. The linkcolor options
can also be prefixed with "top", "bot", "toc" and "idx" for example
"--toc_linkcolor white".

--back_image
--toc_back_image
--idx_back_image
--top_back_image
--bot_back_image
Set background image for nomal slides, table of contents, index,
top frame or bottom frame.

--top_template=filename
--top_idx_template=filename
--top_toc_template=filename
--bottom_template=filename
--bottom_idx_template=filename
--bottom_toc_template=filename
--nav_template=filename
--nav_top_template=filename
--nav_bottom_template=filename
Filenames for template files (in HTML format). The bottom template
is appended to each slide. Can be used to create footers with
navigation, copyright note etc. The top template is inserted at
the top of each slide.

The "_idx_" templates are used for the index slide and the "_toc_"
templates are used for the table of contents slide.

The "nav_top" and "nav_bottom" templates are included in all pages
on top, just below the "top_template" and at the bottom just before
the "bottom_template". If the "--nav_template" option is set, the
"nav_template" will be used on top and at the bottom unless you
specify "--nav_top_template" or "--nav_bottom_template". The latter
both will overwrite the "--nav_template" option.

NOTE: Templates should not contain <HTML>, <HEAD>, <TITLE> or
<BODY> tags. These tags are always written by "pp2html". There is,
however, one exception: If you use the "--frame_set" option without
java script navigation (see below), then the top and bottom HTML
templates should be directly included in the frame set template and
should be full HTML files with HEAD and BODY lines.

The following keywords and "function calls" are substituted with
corresponding values when the templates are included. (Everything
should be completed in the line of its beginning, there's no
multiline support built in yet.)

TITLE text specified by --title option
URL_HERE hyperlink to the current page
URL_NEXT hyperlink to next page
TXT_NEXT header of next page
URL_PREV hyperlink to previous page
TXT_PREV header of previous page
URL_FIRST hyperlink to first page
TXT_FIRST header of first page
URL_LAST hyperlink to last page
TXT_LAST header of last page
URL_UP hyperlink to upper page
TXT_UP header of upper page
URL_DOWN hyperlink to subsection page
TXT_DOWN header of subsection page
URL_CONTENTS hyperlink to contents page
TXT_CONTENTS text specified by --contents_header
URL_INDEX hyperlink to index page
TXT_INDEX text specified by --index_header
LABEL_NEXT label text for "next" link
LABEL_PREV label text for "previous" link
LABEL_CONTENTS label text for "contents" link
LABEL_INDEX label text for "index" link
PAGE page or chapter number
PAGE_CNT number of pages
PAGE_PATH a clickable "path" of parent slides intended for navigation in deeply nested documents
TOP_LEFT_TXT text for left side in top templates, see --top_left_txt
TOP_RIGHT_TXT text for right side in top templates, see --top_right_txt
TOP_MIDDLE_TXT text for middle in top templates, see --top_middle_txt
BOT_LEFT_TXT text for left side in bottom templates, see --bot_left_txt
BOT_RIGHT_TXT text for right side in bottom templates, see --bot_right_txt
BOT_MIDDLE_TXT text for middle in bottom templates, see --bot_middle_txt
LOGO_IMAGE_FILENAME text for the logo image filename in template files,
see --logo_image_filename
START_ADDRESS start address URL as specified --startaddress
DATE(<format>) date (and/or time) in the specified C<POSIX::strftime> format,
(e.g. "DATE(%s)")
VAR(<variable>) insert the current value of the PerlPoint variable $<variable>
(e.g. "VAR(version)")
OPT(<option>, <part>) optionally insert <part> into the template, depending on whether
C<pp2html> option <option> is set or not. The inserted part might contain
further keywords. Make sure everything is places in I<one> line, and there
is no additional closing paranthesis. Example: "OPT(insert_date, DATE(%c))".

--top_left_txt
--top_right_txt
--top_middle_txt
--bot_left_txt
--bot_right_txt
--bot_middle_txt
--logo_image_filename
These texts will be used to replace the corresponding keywords in
template files which are used in the slides. See for example the
orange_slides style.

There is another option which allows to define your own keywords
which will be replaced with values from an option:

--define name=value
This option is a multiple option (may be specified more than once).
For example: Specifiy "--define main_bg_color=#CCCCEE" "--define
main_fg_color=#0000CC" in your options file. Then you can use
"MAIN_BG_COLOR" and "MAIN_FG_COLOR" in your own template files and
these texts are replaced with the values specified in the option
file. This can be useful for easily switching colors in your self
defined style by changing the "--define" options in the options
file.

--boxtext_bold=ON
--boxtext_bold=OFF
Text in colored textboxes will be printed bold or normal.

--box_border=width
Set the border width of block paragraphs.

--box_width=width
Set the width of block paragraphs. This assures that all colored
boxes have the same width.

Example: --box_width="80%"

--bullet=filename
Filename of a GIF or JPEG image which is used for the bullets in
bullet lists. This option can be used more than once. In this case
the first occurance is used for top level lists, the second
occurance for second level lists etc.

NOTE: The filename must be given as an absolute pathname or
relative to the directory where the "pp2html" program is started
(i. e. relative to the directory where the PerlPoint input file
resides). When the --style option is used, the filename must be
specified relative to the directory where the style is defined.
Normally all bullet images for a style reside in the style
directory.

--bullets_align_middle
If this option is set, bullets are aligend to MIDDLE. Otherwise
they are aligned to TOP. This options may yield better results for
presentation slides with large font size.

--block_indent=m
Indent each block by m levels (i. e. put m <UL> </UL> containers
around the block This can be used to shift the block boxes to the
right. Looks better if a block paragraph occurs within a bullet
list.

--center_headers
Page Headers are centered. Default is no centering.

--contents_header=text
Heading for contents page. Default is Contents

--frame_set=filename
filename for frame set template. This activates the frame set
generation.

--frame_start=filename
filename of the startfile for the frame set. The frame_set template
is copied to this file in the slide_dir directory.

--contents_target
This is used as the target frame in all hyperlinks to the table of
contents. Useful for example if you have a frame set without an
Index frame. In this case it might be usefull to set the
"--contents_target" option to "Data".

--contents_table_width=m
Specifies the width of the table used for the table of contents
(unless the tree applet is uses). A value of 0 suppresses the
width option in the HTML table.

--contents_css_id_index=<id>
Enforces pp2html to assign the passed CSS id to the TOC table on
the index page.

If this option is unset or set to an empty string, no id will be
assigned.

--contents_css_id_start=<id>
Enforces pp2html to assign the passed CSS id to the TOC table on
the start page.

If this option is unset or set to an empty string, no id will be
assigned.

--index_bot=n
--index_dat=n
--index_top=n
Indices of the bottom, top and index frames within the frame set.
Used for java script navigation procedure.

--index_header=text
Heading for index page. Default is Index

--no_index
Do not create an index

--java_script_navigation=value
value=1: on, value=0: off. If java_script_navigation is on and
frame sets are generated then for each page a separate top and
bottom page is created which is used in the top and bottom frames
of the frame set. If java_script_navigation is off, then only one
top template and one bottom template will be used for all pages.
(In this case there should be no place holders for PAGE etc. in
theses templates ... and they should be complete HTML Files.)

NOTE: This option is mainly used in combination with the
"--tree_applet" option because it is not possible to use the tree
applet with javascript navigation (the tree applet cannot call URLs
which contain javascript function calls).

--java_script_controls=value
If this option is used, additional javascript code is included in
each header of the slides. This makes it possible to use keyboard
keys and left mouse button to navigate through the slides. value=1
turns this option on and value=0 turns it off. Default is off.

The following table shows the keys which can be used for
navigation:

--linear_mode
This option influences the behaviour of PREV and NEXT links. In
linear mode all pages form a linear sequence which can be traversed
by means of the PREV and NEXT links. When this option is not set
then the PREV and NEXT links work only on the same level. For
example is it possible to traverse the sequence 2.1.1, 2.1.2,
2.1.3, 2.1.4 with PREV and NEXT links but the first section has no
PREV link and the last one has no NEXT link. In such a
constellation the UP and DOWN links may be used to change the level
and go the the next higher section or step down to a subsection.

--num_headers
--nonum_headers
All page headers are preceeded/not preceeded by the chapter number
(e.g. 2.2.3) which is determined by the position of the page and
the level of its header. The "--nonum_headers" overwrites a
previous "num_headers" option which allows to overwrite options
from predefined styles.

--trailing_point
If this option is set, all numbers in the page headlines will will
get a trailing point (e.g. 1. 2.3. instead of 1 and 2.3). The
default is no trailing points.

--no_contents_indent
--no_contents_bullets
These two options influence the appearance of the table of
contents. The first one prevents the indentation and the second one
avoids bullets in front of each entry.

--contents_indent=m
Indent table of contents by m levels (i. e. put m <UL> </UL>
containers around the table of contents.

--slide_dir=directory
--target_dir=directory
Directory in which the HTML files are to be created.

--slide_prefix=text
Prefix for all HTML files. Default is "Slide".

--slide_suffix=text
Suffix for all HTML files. Default is "htm".

--slide_md5
This option specifies, that all filenames should have the form
<slide_prefix><md5_checksum>.<slide_suffix> e. g.
"slide85b9a93686f5416d2f85964a33fad95b.htm". The "md5_checksum" is
calculated from the slide header. This can be usful, if there are
many changes in your document (addition/removal of slides) and you
use hyperlinks to pages of your document from within other
documents.

NOTE: This feature is still experimental.

--reverse_order
This options has the effect that the slides are numbered in reverse
order. If there are <m> slides (beside the contents slide) the
normal naming would be slide0000.htm, slide0001.htm ...
slide000<m>.htm. With the "--reverse_order" option the naming is
slide000<m>.htm, ... slide0002.htm, slide0001.htm. The contents
slide is still slide0000.htm.

--title=text
Text which is substituted for the TITLE keyword in template files.

--tree_applet
Activate usage of TreeApplet

--tree_app_width=m
--tree_app_height=m
Width and height of the tree applet area.

--tree_base
Codebase option for the tree applet. Default is ./

--style=style_name
--style_dir=style_dirname
Using pre-defined styles. Styles are pre-defined collections of
templates and configuration files which are stored in a directory
whose name is the name of this style. Several of such styles can be
placed in a style directory (collection of styles).

With "--style_dir=style_dirname" you can specify one or more style
directories (the option can be used more than once). All specified
style directories are searched for the style which is given by the
"--style" option.

Examples of styles are delivered with the PerlPoint-Converters
distribution.

--style_sheet=style_sheet_name
This option is still experimental. It allows to specifiy a style
sheet (.css) which will be referenced in HTML <head> tags in all
slides. It is not well tested and the settings in the style sheet
may conflict with some layout tricks used by pp2html.

--image_dir=dirname
This is the name of the image directory in the target area. All
images from the style directory and from the PerlPoint source are
copied to this location.

--mv2targetdir
If this option is set, all images mentioned in \IMAGE tags are
moved to the image directory, i.e. they are removed from the
source directory.

--start_page=filename
The default for this option is "index.htm". The table of contents
slide or the frame set start page is copied to this filename unless
the "--start_page" option is set to the empty string. This is
useful for web pages because most browsers automatically open the
"index.htm" if it exists. For example, if you have installed your
document or presentation at "http://somewhere.net/Example", a web
browser will automatically open the first page of your document if
the browser is directed to this URL.

--trace [<level>]
activates traces of the specified level. You may use the
environment variable SCRIPTDEBUG alternatively (but an option
overwrites environment settings). The following levels are defined
(use the numeric values) - if a description sounds cryptic to you,
just ignore the setting:

zero (0)
same as omitting the option: all traces are suppressed.

one (1)
paragraph detection,

two (2)
lexer traces,

four (4)
parsing,

eight (8)
semantic actions embedded into parsing,

sixteen (16)
active contents,

thirtytwo (32)
backend traces.

Using different levels may cause unexpected results.

Several levels are combined by addition.

# activate lexer and parser traces
--trace 6

--help
Print this manual page.

--version
Print version inforamtion and exit.

FILES
Template files for header and footer section.

Configuration file $HOME/.pp2html

ENVIRONMENT
The following environment variables have influence on the program:

SCRIPTDEBUG
may be set to a numeric value to activate certain trace levels. You
can use option -trace alternatively (note that a used option
overwrites an environment setting). The several levels are
described with this option.

TMP
TEMP
TMP or TEMP are used to specify a temporary directory (needed for a
temporary help file). If none of these variables is set, "/tmp"
will be used.

NOTES
The PerlPoint format was initially designed by Tom Christiansen. Tom
used a simple syntax which was inspired by POD and a simple script
which created HTML files from an ASCII file.

DragonFly On-Line Manual Pages

NAME

VERSION

SYNOPSIS

DESCRIPTION

OPTIONS

FILES

ENVIRONMENT

NOTES

SEE ALSO

SUPPORT

AUTHOR