PP2SDF(1) User Contributed Perl Documentation PP2SDF(1)NAMEpp2sdf - translates PerlPoint to SDF
VERSION
This manual describes version 0.12.
DESCRIPTION
This is a demonstration application of the PerlPoint package. It
translates PerlPoint into SDF.
SDF is, of course, no presentation format by itself. Nevertheless it is
useful as a target format because sdf can produce various other
formats. Presentation formats are fine but often one wants to provide
additional handouts, notes or a printed version. pp2sdf opens a simple
way to do this.
SYNOPSISpp2sdf [<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).
-docstreaming <mode>
sets up the mode the converter handles document streams. Document
streams are document parts belonging to the last recent headline
and starting with a document stream entry point (which is a special
paragraph):
=This is the main stream
Bla bla
~A special document stream starts here
Blu blu
~And this is another one
Bli bli
=The next headline switches back to the main stream
Bla bla
You might think of these streams as "document threads" or "docs in
docs".
Now, the transformations of those streams are controled by this
option.
Mode 0 is the default. It is entered automatically if a document
contains docstreams and "-docstreaming" is not set.
This mode causes "pp2sdf" to produce one document per document
stream, each of them containing only the main stream and the parts
written of one certain stream. For example, the first produced
document according to the code above would be equivalent to the
following source:
=This is the main stream
Bla bla
Blu blu
=The next headline switches back to the main stream
Bla bla
Result files will be named as specified by -sdffile, with a
sequentially incremented appendix ("name.stream1", "name.stream2"
etc.). If the document contains no docstream, the result file
defaults to the specified name (without appendix).
Mode 1 causes the converter to ignore everything except of the main
stream. In this mode, the example above is converted according to
this source:
=This is the main stream
Bla bla
=The next headline switches back to the main stream
Bla bla
Mode 2 transforms every stream entry point into a sub-headline of
the same name. In the example, this results in a document part
equivalent to the following source:
=This is the main stream
Bla bla
==A special document stream starts here
Blu blu
==And this is another one
Bli bli
=The next headline switches back to the main stream
Bla bla
So results are slightly different in different modes. The best way
to get an impression is to give a certain mode a try.
-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.
-sdffile <filename>
The file to store results in. This option is mandatory.
-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 pp2sdf with
-set special
- and if active contents was enabled by -active, of course.
This option can be used multiply.
-skipstream <stream identifier>
instructs the converter to ignore the document stream specified by
the identifier string.
-skipstream 'The stream seldomly read'
This would ignore everything between a
~The stream seldomly read
paragraph and the next document stream entry point or the next
headline, depending on what follows first.
-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.
SUPPORTED TAGS
All supported tags are declared by PerlPoint::Tags::SDF. Please see
there for a complete list.
pp2sdf supports foreign tags like PAGEREF and SECTIONREF initially
introduced by "pp2html". Support means that they are handled, but
possibly different to the original handling:
A Makes the body a named anchor.
Example:
\A{name="an anchor"}<text> becomes "{{N[id=q(an anchor)]text}}".
Using "q()" avoids sdf trouble caused by quotes in an anchor.
L The tag body is made a hyperlink to the URL passed bz the "url"
option. Any other options besides "url" are ignored.
Example:
\L{url=link}<Look there!> becomes "{{CMD[jump=q(link)]Look there!}}".
Using "q()" avoids sdf trouble caused by quotes in the link.
PAGEREF
The section title provided by the "name" option is treated as the
text to be displayed. This text is made a hyperlink to the
referenced chapter.
Example:
\PAGEREF{name=chapter} becomes "{{CMD[jump=q(#chapter)]chapter".
pp2sdf currently does not replace the title by chapter numbers as
usually intended by a page reference. This might be improved by
later versions.
Using "q()" avoids sdf trouble caused by quotes in the link.
SECTIONREF
The section title provided by the "name" option is treated as the
text to be displayed. This text is made a hyperlink to the
referenced chapter.
Example:
\SECTIONREF{name=chapter} becomes "{{CMD[jump=q(#chapter)]chapter".
Using "q()" avoids sdf trouble caused by quotes in the link.
XREF
The tag body is made a hyperlink to an internal target, usually
declared by an \A tag or (implicitly) by a headline.
Example:
Do not miss \XREF{name=chapter}<this>
is translated into
"Do not miss {{CMD[jump=q(#chapter)]this".
Using "q()" avoids sdf trouble caused by quotes in the 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 pp2sdf may be ignored if the PerlPoint document is processed by
other translators. pp2html, for example, accepts embedded HTML but
ignores embedded SDF.
Embedding SDF
Just use the \EMBED and \END_EMBED tags to place native SDF if really
necessary:
This is \I<PerlPoint> with embedded
\EMBED{lang=sdf}{{B:SDF}}\END_EMBED.
\EMBED{lang=sdf}
H2: An SDF chapter
Note: An SDF note.
\END_EMBED
You may as well include complete SDF files by \INCLUDE.
\INLUDE{type=sdf file="snippet.sdf"}
Embedding HTML
is as easy as embedding SDF directly. It is, of course, only useful if
you plan to transform your presentation to an HTML page via SDF. You
can embed complete HTML sections:
\EMBED{lang=html}
<h1>An HTML chapter</h1>
<p>
This was written in <i>HTML</i>.
\END_EMBED
This way pp2sdf will produce SDF inline blocks like this:
!block inline
<h1>An HTML chapter</h1>
<p>
This was written in <i>HTML</i>.
!endblock
Further proceeding is up to sdf, so please refer to the SDF manuals for
details.
Alternatively, you may choose to embed HTML directly into a PerlPoint
paragraph:
This is \I<PerlPoint> with embedded
\EMBED{lang=html}<b>HTML</b>\END_EMBED.
This will be translated into an SDF inline phrase:
This is {{I:PerlPoint}} with embedded {{INLINE:<b>HTML</b>}}.
Please note that for unknown reasons SDF processes POD tags in inlined
phrases (even if it was not intended to use POD). In the example above,
this causes a wrong result because an "L" tag is assumed. This is
currently a feature of sdf, not pp2sdf.
HTML code can be embedded by complete files as well, of course:
\INLUDE{type=html file="snippet.html"}
Embedding other languages
pp2sdf will ignore any other embedded or included target language than
SDF and HTML.
HYPERLINKS
Each headline is implicitly made an anchor named like the headline
itself. For example,
=Headline level 1
is converted into
H1[id=q(Headline level 1)]Headline level 1
, making it easy to set links to certain headlines which is usually
done by using the "PAGEREF", "SECTIONREF" and "XREF" tags.
Anchors can be set explicitly as well. Please have a look at the
description of the \A tag.
PREDECLARED VARIABLESpp2sdf predeclares several variables which can be used like any user
defined PerlPoint variable.
CONVERTER_NAME
The name of the converter currently processing the document
("pp2sdf").
CONVERTER_VERSION
The version of the running converter.
FILESENVIRONMENT
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
The generated SDF is not handcrafted
As pp2sdf is a generator. It produces another kind of SDF than a human
would write because its target is to make a file which can be processed
by sdf without problems. Nevertheless, in most cases it should be
simple to manually modify the results if necessary.
Paragraph styles
SDF markes paragraphs types by special prefixes followed by a colon,
like in
Note: Think twice.
Now, authors of a PerlPoint document may start a text paragraph the
same way, by a word and a colon, without thinking of SDF. If this would
be plainly translated SDF could be confused (it may take words as
paragraph style markers which were not intended to be this, or mention
an unknown paragraph style and return an error code). That is why all
text paragraphs in the generated SDF document are preceded by a
backslash, except if they begin with "Note" or "Sign" because in these
cases the special SDF formatting makes sense. Backslash prefixes are
avoided as well if the paragraph starts with an SDF tag or inlined
HTML.
SDF does only support six headline levels
While the headline level in PerlPoint is unlimited in depth, that is
not the case in SDF. The sdf translator will warn you if such a
headline level is detected.
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.
Foreign PerlPoint tags might cause confusion
PerlPoint allows to process a document by all of its converters.
Nevertheless, possibly several foreign tags might produce unexpected
results.
Multiline tags in examples are handled correctly
While PerlPoint allows you to open a tag in a line and close it in a
subsequent line even in examples, SDF requests a tag to be closed at
the opening line. This means it is correct PerlPoint to write
My tag \I<encloses
line breaks>.
but it needs to be transformed into the quiet differently structured
E: My tag {{I:encloses}}
E: {{I:line breaks}}.
which is automatically arranged by \pp2sdf for the PerlPoint tags \B,
\C, \E, \I and \U. (These are the supported tags with bodies. \L,
because of its special transformation, does not need to be handled this
way.)
FILESpp2sdf 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::Tags::SDF
PerlPoint::Parser
PerlPoint::Backend
AUTHOR
Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2000-2002. 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.
perl v5.20.2 2006-03-12 PP2SDF(1)
