Options

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

 # activate lexer and parser traces
 -trace 6

Option files

  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.

Embedding SDF

  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

  \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

The generated SDF is not handcrafted

Paragraph styles

 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

SDF phrases are not disabled

Foreign PerlPoint tags might cause confusion

Multiline tags in examples are handled correctly

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