NAME

VERSION

SYNOPSIS

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

DESCRIPTION

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 frame set (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 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

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

• Comments
• Headers
• Bullet Items
• Numbered Lists
• Definition Lists
• Paragraphs
• Blocks
• Verbatim Blocks

 =This is a level 1 header

 ==This is a level 2 header

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

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

 * Item 2

 * Item Three

 # First

 # Second

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

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

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

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

  \BOXCOLORS{bg=yellow}

  \BOXCOLORS{fg=blue}

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

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

  \A{name="target_name"}

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

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

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

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

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:

  Key             |  Action
  ----------------+----------------------------
   Button 1 click |  go to next slide
   n              |  go to next slide
   p              |  go to previous slide
   s              |  go to start slide
   i              |  go to index slide
    

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

 # activate lexer and parser traces
 --trace 6

--help

Print this manual page.

--version

Print version inforamtion and exit.

FILES

Configuration file $HOME/.pp2html

ENVIRONMENT

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

SEE ALSO

SUPPORT

If you prefer, you can contact me via lorenz.domke@gmx.de as well.

AUTHOR