/ 
PerlPoint-Converters-0.009
River stage one • 1 direct dependent • 2 total dependents
/ pp2html

NAME

pp2html - PerlPoint to HTML converter

VERSION

This manual describes version 0.009, build 1.13.

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:

  • Simple ASCII input file for your text

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

  • Rudimentary formatting capabilities

  • Creation of a contents page with links to all slides

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

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

  • The index frame may use the TreeApplet which provides convenient access to all pages

    For more information see: http://www.mcsoftware.com.au/java/TreeControl/treeControl.html

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:

  • Comments

  • Headers

  • Bullet Items

  • Numbered Lists

  • Definition Lists

  • Paragraphs

  • Blocks

  • 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 a = sign. 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.

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.

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

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

--bottom_template=filename
--top_template=filename
--bottom_idx_template=filename
--top_idx_template=filename
--bottom_toc_template=filename
--top_toc_template=filename
--nav_top_template=filename
--nav_bottom_template=filename
--nav_top_template=filename

Filenames for template file (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 are substituted with corresponding values when the templates are included:

TITLE               text specified by --title option
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
PAGE_CNT            number of pages
PAGE                page or chapter number
--boxtext_bold=ON
--boxtext_bold=OFF

Text in colored textboxes will be printed bold or normal.

--box_color=color
--boxtext_color=color

Set background and forground colors for 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.

--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. Deafult 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.

--index_bot=n
--index_dat=n
--index_top=n

Indices of the bottom, top and index frames within the frameset. 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).

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

All page headers are 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.

--no_contents_indet
--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.

--nav_template=filename

Filename for a navigation template file which will be inlcuded at the top and bottom of each slide. This is useful for frame sets which use the TreeApplet because in this case the java script navigation should be disabled because the TreeApplet does not support this kind of URLs. Hence it might be a good idea to include navigation links at the top and bottom of each page.

--slide_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".

--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 ./

--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 &Uuml;
\374 &uuml;

\326 &Ouml;
\366 &ouml;

\304 &Auml;
\344 &auml;

\337 &szlig;
--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 active it. You can use --safeOpcode to fine tune which operations shall be permitted.

--allTags

pp2html implements the PerlPoint tags B, C, E, I and IMAGE. Because every PerlPoint translator can define its own tags it may happen that a source file containes more than these. If they do not pass translation try this option which makes all tags accepted. This is still an experimental feature.

--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).

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

--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.)

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.

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

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.

SEE ALSO

pp2latex

AUTHOR

Lorenz Domke (lorenz.domke@gmx.de), 2001. All rights reserved.