/ 
PerlPoint-Package-0.452
River stage one • 4 direct dependents • 5 total dependents
/ pp2ppresenter

NAME

pp2ppresenter - translates PerlPoint into XML readable by Mark Overmeers PPresenter

VERSION

This manual describes version 0.01.

DESCRIPTION

This is a demonstration application of the PerlPoint package. It translates PerlPoint into XML readable by Mark Overmeers PPresenter.

SYNOPSIS

pp2ppresenter [<options>] <PerlPoint sources>

Options

All options can be abbreviated uniqly.

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

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

geometry <geometry setup string>

geometry setting to control the size and proportions of the projector window. Defaults to "1024x768". See the PPresenter docs for details.

-help

displays an online help and terminates the script.

imageBaseSize <image geometry setup string>

geometry setting to control the base size and proportions of displayed images. Defaults to "1024x768". See the PPresenter docs for details.

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

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.

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

-set special

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

This option can be used multiply.

-title <title string>

sets a presentation title.

-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

Option files

Options may be loaded from files where they are stored exactly as you write them in the command line, but may be spread to several lines and extended by comment lines which start with a "#" character. To mark an option file in the commandline, simply enter its (path and) name prededed by a "@" character, for example

pp2ppresenter @myOptions ppfile

where the file myOptions could look like

# suppress infos
-noinfo

Option files may be nested. To avoid endless recursion, every option file is resolved only the first time it is detected.

# this is an option file which
# refers to another option file
-noinfo @moreOptions

The script also takes care of default option files which means that usual options can be stored in files named .pp2ppresenter. If such a file is placed in the directory where the script itself resides, options in the file are read in automatically by all pp2ppresenter calls. These are global settings. If you place such a file in your home directory, it is read automatically as well but only if pp2ppresenter is called under your account, so this is for personal preferences.

A personal default option file overwrites global settings, and all default options are overwritten by options passed to the script call.

SUPPORTED TAGS

All supported tags are declared by PerlPoint::Tags::SDF (currently, this shall become PerlPoint::Tags::XML). Please see there for a complete list.

pp2ppresenter supports several foreign tags initially introduced by pp2html. Support means that they are handled, but possibly different to the original handling.

At the moment, the only tag of this type is \L, which is translated into an HTML like hyperlink. Note: PPresenter support of hyperlinks is only assumed yet.

EMBEDDING TARGET CODE

There may be things you want to see in the target document but find no way to express them in PerlPoint. Well, PerlPoint lets you embed target code very easily directly into the PerlPoint script. Nevertheless, it is recommended to use native PerlPoint wherever possible ;-).

Please note that embedded target code intended for certain translators like pp2ppresenter may be ignored if the PerlPoint document is processed by other translators. pp2html, for example, accepts embedded HTML but ignores embedded XML.

Embedding XML

Just use the \EMBED and \END_EMBED tags to place native XML if really necessary:

This is \I<PerlPoint> with embedded
\EMBED{lang=xml}<B>XML<B/>\END_EMBED.

\EMBED{lang=xml}

<UL>

  <LI>This ...<LI/>

  <LI>... and that.<LI/>

<UL/>

\END_EMBED

You may as well include complete XML files by \INCLUDE.

\INLUDE{type=xml file="snippet.xml"}

Embedding other languages

pp2ppresenter will ignore any other embedded or included target language than XML.

PREDECLARED VARIABLES

pp2ppresenter predeclares several variables which can be used like any user defined PerlPoint variable.

CONVERTER_NAME

The name of the converter currently processing the document ("pp2ppresenter").

CONVERTER_VERSION

The version of the running converter.

FILES

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.

NOTES

PerlPoint allows to process a document by all of its converters. Nevertheless, possibly several foreign tags might be ignored. See above for details.

This is a demo. Not all PPresenter features might be supported, but feel free to make this software the base of an improved implementation. Just let me know.

FILES

pp2ppresenter activates the PerlPoint parser cache to accelerate repeated translations. Because of this the usual PerlPoint parser cache files will be written next to the parsed sources (as ".<source file name>.ppcache" in the source directory).

SEE ALSO

The PPresenter homepage (http://ppresenter.org).

PerlPoint::Tags::XML

PerlPoint::Parser

PerlPoint::Backend

AUTHOR

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

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