NAME

pp2cppp - translates PerlPoint to Clinton Pierce's Perl Projector

VERSION

This manual describes version 0.01.

DESCRIPTION

This is a demonstration application of the PerlPoint package. It translates PerlPoint into Clinton Pierce's Perl Projector format (see ). In this documentation, I call this format "CPPP".

SYNOPSIS

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

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

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

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

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

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

L

The tag body becomes plain text, followed by the URL in paranthesis. Any other options besides url are ignored.

Example:

 \L{url=link}<Look there!> becomes "Look there! (link)".

U

Marks the body to be underlined

Example:

 \U<text> becomes "u<text>".

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 pp2cppp may be ignored if the PerlPoint document is processed by other translators. pp2html, for example, accepts embedded HTML but ignores embedded CPPP.

Embedding CPPP

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

This is \I<PerlPoint> with embedded
\EMBED{lang=cppp}{{B:CPPP}}\END_EMBED.

\EMBED{lang=cppp}

=t An CPPP chapter

=comment A CPPP comment.

\END_EMBED

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

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

Embedding other languages

pp2cppp will ignore any other embedded or included target language than CPPP.

PREDECLARED VARIABLES

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

CONVERTER_NAME: The name of the converter currently processing the document ("pp2cppp").
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 produce unexpected results.

FILES

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

AUTHOR

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.

To install PerlPoint::Tags, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PerlPoint::Tags

CPAN shell

perl -MCPAN -e shell
install PerlPoint::Tags

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

SYNOPSIS

Options

Option files

SUPPORTED TAGS

EMBEDDING TARGET CODE

Embedding CPPP

Embedding other languages

PREDECLARED VARIABLES

FILES

ENVIRONMENT

NOTES

FILES

SEE ALSO

AUTHOR

DISCLAIMER

Module Install Instructions