/ 
PerlPoint-Package-0.28
River stage one • 4 direct dependents • 5 total dependents
/ pp2sdf

NAME

pp2sdf - translates PerlPoint to SDF

VERSION

This manual describes version 0.03.

DESCRIPTION

This is a demonstration application of the PerlPoint package. It translates PerlPoint into SDF.

SDF as a target format is useful because sdf itself can produce various other formats.

SYNOPSIS

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

-allTags

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

-help

displays an online help and terminates the script.

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

-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

pp2sdf @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 .pp2sdf. If such a file is placed in the directory where the script itself resides, options in the file are read in automatically by all pp2sdf calls. These are global settings. If you place such a file in your home directory, it is read automatically as well but only if pp2sdf 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.

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

This is a first attempt of a working PerlPoint to SDF translator. It handles all of the PerlPoint elements but is still alpha software because

SDF phrases are not disabled

SDF recognizes POD tags like I, B and C. If a string looks like such a tag, sdf tries to evaluate it the tag way. This should be suppressed.

FILES

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

SEE ALSO

PerlPoint::Parser

PerlPoint::Backend

AUTHOR

Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2000. 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.