view release on metacpan or  search on metacpan

doc/parser-paragraphs.pp  view on Meta::CPAN

Please note that normalization refers to the headline row. If another line contains
\I<more> columns than the headline, normalization does not care.

In all tables, leading and trailing whitespaces of a cell are
automatically removed, so you can use as many of them as you want to
improve the readability of your source. The following table is absolutely
equivalent to the last example:

  @|
  A                |       B         |      C
  1                |                 |
   1               |                 |
    1              | 2               |
     1             |  2              |
      1            | 2               |      3

There is also a more sophisticated way to describe tables, see the \I<tag> section.


==Conditions

start with a  \B<"?"> character. If \I<active contents> is enabled, the paragraph text
is evaluated as \I<Perl code>. The (boolean) evaluation result then determines if
subsequent PerlPoint is read and parsed. If the result is false, all subsequent
paragraphs until the next condition are \I<skipped>.

This feature can be used to maintain various language versions of a presentation
in one source file:

  ? $PerlPoint->{userSettings}{language} eq 'German'

Or you could enable parts of your document by date:

  ? time>$main::dateOfTalk

Please note that the condition code shares its variables with \I<embedded> and \I<included>
code.

To make usage easier and to improve readability, condition code is evaluated with
disabled perl warnings (the language variable in the example above may not even been set).


==Variable assignments

Variables can be used in the PerlPoint text and will be automatically replaced by their string
values (if declared).

  The next paragraph sets a variable.

  $var=var

  This variable is set to $var.

All variables are made available to \I<embedded> and \I<included> Perl code as well as to
\I<conditions> and can be accessed there as package variables of "main::". Because a
variable is already replaced by the parser if possible, you have to use the fully
qualified name or to guard the variables "$" prefix character to do so:

<<EOE
  \EMBED{lang=perl}join(' ', $main::var, \$var)\END_EMBED
EOE

Variable modifications by embedded or included Perl \I<do not> affect the variables
visible to the parser. (This includes condition paragraphs.) This means that

<<EOE
  $var=10
  \EMBED{lang=perl}$main::var*=2;\END_EMBED
EOE

causes \C<\$var> to be different on parser and code side - the parser will still use a
value of 10, while embedded code works on with a value of 20.

Translator software \I<can> make additional use of variables, especially predeclare
certain settings (such variables are usually capitalized). Please see your converters
documentation for details.


==Macro definitions

Sometimes certain text parts are used more than once. It would be a relieve
to have a shortcut instead of having to insert them again and again. The same
is true for tag combinations a user may prefer to use. That's what \I<aliases>
(or "macros") are designed for. They allow a presentation author to declare
his own shortcuts and to use them like a tag. The parser will resolve such aliases,
replace them by the defined replacement text and work on with this replacement.


===Basic definition

An alias declaration starts with a \B<"+"> character followed \I<immediately> by the
alias \I<name> (without backslash prefix), followed \I<immediately> by a colon.
(No additional spaces here.) \I<All text after this colon up to the paragraph
closing empty line is stored as the replacement text.> So, whereever you will
use the new macro, the parser will replace it by this text and \I<reparse> the result.
This means that your macro text can contain any valid constructions like tags or
other macros.

The replacement text may contain strings embedded into doubled underscores like
\C<__this__>. This is a special syntax to mark that the macro takes parameters
of these names (e.g. \C<this>). If a tag is used and these parameters are set,
their values will replace the mentioned placeholders. The special placeholder
\C<__body__> is used to mark the place where the macro body is to place.

Here are a few examples:

<<EOE

  +RED:\FONT{color=red}<__body__>

  +F:\FONT{color=__c__}<__body__>

  +IB:\B<\I<__body__>>

  This \IB<text> is \RED<colored>.

  +TEXT:Macros can be used to abbreviate longer
  texts as well as other tags
  or tag combinations.

  +HTML:\EMBED{lang=html}

  Tags can be \RED<\I<nested>> into macros. And \I<\F{c=blue}<vice versa>>.
  \IB<\RED<This>> is formatted by nested macros.
  \HTML This is <i>embedded HTML</i>\END_EMBED.

  Please note: \TEXT

EOE


===Option defaults

If an option is declared but unused, it defaults to an empty string unless
the definition declared a default value itself by using an assignment list
after the macro name.

  +MACRO\B<{\I<value>="default value"}>:value is \B<__value__>

Please note that the default assignment uses the \I<real> option name, no
placeholder.

As long as the option is set in the macro call, the passed value will be used:

  Now I'm using the macro the usual way, \MACRO{value=passed}.

But if the option is omitted, PerlPoint falls back to the stored default value:

  Using this macro the convenient way: \MACRO.

Default assignment lists are syntactically similar to the ones used in tag and
macro \I<calls>, so it is possible to make various settings.

  +MACRO{\B<a=1 b=2 c=3>}:sum(__a__, __b__, __c__)
  
Setting a default value for an option not declared in the macros replacement
text takes no effect and is silently ignored.


===Recognition

\I<If no parameter is defined in the macro definition, options will not be recognized.>
The same is true for the body part. \I<Unless \C<"__body__"> is used in the macro
definition, macro bodies will not be recognized.> This means that with the definition

  +OPTIONLESS:\\B<__body__>

the construction

  \\OPTIONLESS{something=this}<more>

is evaluated as a usage of \C<\\OPTIONLESS> without body, followed by the \I<string>
\C<"{something=here}">. Likewise, the definition

  +BODYLESS:found __something__

causes

  \\BODYLESS{something=this}<more>

to be recognized as a usage of \C<\\BODYLESS> with option \C<something>, followed
by the \I<string> \C<"<more\>">. So this will be resolved as \C<"found this">. Finally,

  +JUSTTHENAME:Text phrase.