Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PP2HTML(1)	      User Contributed Perl Documentation	    PP2HTML(1)

       pp2html - PerlPoint to HTML converter

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

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

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

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

       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

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

       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.

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

       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

	 sub verbatim_text
	   for example some piece of code;

       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>
	 \E<lt>	 \E<gt>

       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:



	 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:


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


       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:


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

	   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.

	   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

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

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

	   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

	   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.

	   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

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

	     \334 &Uuml;
	     \374 &uuml;

	     \326 &Ouml;
	     \366 &ouml;

	     \304 &Auml;
	     \344 &auml;

	     \337 &szlig;

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

	   Example: --filter="perl|html"

	   suppresses the copyright message;

	   supresses runtime informations;

	   supresses warnings;

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

	   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.

	   Set background and forground	colors for block paragraphs

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

	   Set background image	for nomal slides, table	of contents, index,
	   top frame or	bottom frame.

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

	   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

	   Text	in colored textboxes will be printed bold or normal.

	   Set the border width	of block paragraphs.

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

	   Example: --box_width="80%"

	   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

	   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.

	   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

	   Page	Headers	are centered. Default is no centering.

	   Heading for contents	page. Default is Contents

	   filename for	frame set template. This activates the frame set

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

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

	   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.

	   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

	   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

	   Indices of the bottom, top and index	frames within the frame	set.
	   Used	for java script	navigation procedure.

	   Heading for index page. Default is Index

	   Do not create an index

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

	   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

	     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

	   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.

	   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.

	   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.

	   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.

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

	   Directory in	which the HTML files are to be created.

	   Prefix for all HTML files. Default is "Slide".

	   Suffix for all HTML files. Default is "htm".

	   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

	   NOTE: This feature is still experimental.

	   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.

	   Text	which is substituted for the TITLE keyword in template files.

	   Activate usage of TreeApplet

	   Width and height of the tree	applet area.

	   Codebase option for the tree	applet.	Default	is ./

	   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

	   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.

	   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.

	   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.

	   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 "", 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)

	   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

	   Print this manual page.

	   Print version inforamtion and exit.

       Template	files for header and footer section.

       Configuration file $HOME/.pp2html

       The following environment variables have	influence on the program:

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

       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.


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

       If you prefer, you can contact me via as well.

       Lorenz Domke (, Copyright (C) 2005. All rights

perl v5.32.1			  2021-08-28			    PP2HTML(1)


Want to link to this manual page? Use this URL:

home | help