view release on metacpan or  search on metacpan

doc/parser-active-contents.pp  view on Meta::CPAN

// declare an empty variable to separate bodyless tags from text
$empty=

=Active Contents

Document parts can be generated \I<dynamically>. This is done by evaluating a \I<condition>,
\I<embedded> or \I<included> \B<Perl> code \I<at translation time>. Paragraph and input filters
are more types of Active Content.

@|
active part       | description | example
condition         | A paragraph type to control inclusion of all subsequent source parts before the next condition. | \C<\B<?> \$PerlPoint-\>{targetLanguage} eq "HTML">
\I<tag> condition | A special tag option available for all tags which accept options which flags whether the tag should take effect or not.  If Active Contents is \REF{name=Security type=linked}<disabled>, the condition defaults to "false". | \C<\\IM...
embedded Perl     | Perl code embedded into \C<\\EMBED> and \C<\\END_EMBED> tags, marked as Perl by tag option \C<lang> set to \C<"perl">. The code is expected to return a string which will be interpreted as \B<PerlPoint>. | \C<This document was gene...
included Perl     | Perl code read from a file via an \C<\\INCLUDE> tag, marked as Perl by tag option \C<type> set to \C<"perl">. File contents is evaluated like embedded Perl. | \C<\B<\\INCLUDE{type=perl file="included.pl"}>>
input filters     | A special option to \C<\\EMBED> and \C<\\INCLUDE> tags which allows to preprocess embedded code or included files before they are furtherly processed. The filter code may be passed directly or refer to functions defined in \I<embe...
paragraph filters | Calls to functions declared in \I<embedded Perl> (see above) used to modify a complete paragraph and return it for reparsing. Filters are applied by preceeding the target paragraph with the filter call enclosed in \C<\|\|> pairs. ...

  As an introduction example of the active contents feature,
  here is a report about this document: it was generated
  at \EMBED{lang=perl}my @t=(localtime)[3, 4, 5]; sprintf("%d.%d.%d", $t[0], $t[1]+1, $t[2]+1900); \END_EMBED.


==What it is for

Well, honestly spoken, I'm looking forward to the usage people will make of this feature.
But I can already imagine things like

* document parts included depending on the target language (an article could
  possibly provide more informations than presentation sheets), the time of
  presentation generation (informations may be confidental until a certain
  point; or imagine exercises - solutions may be presented in a second step)
  or depending on the system state;

* automatic documentation of system parts (directories, partitions, or share
  a generic PerlPoint source which will produce a presentation automatically
  adapted to the target system);

* integration of sources provided in a format different to PerlPoint, automatically
  translated and integrated;

* including statistics and images made on the fly on base of whatever data
  Perl can access;

* grabbing presentation data from the web or a server;

* let Perl generate a presentation of complex data instead of having to write
  the PerlPoint yourself;

* using C, Assembler, Python or other languages (or libraries) to generate
  parts of your document on the fly via \B<Inline>;

* and more ...

As for conditions, they can be used to generate various different documents from
one and the same source, depending on decisions based on evaluated Perl code.


==An example

The following files were found in the source directory of this documentation part when this presentation was built:

\EMBED{lang=perl}

# read /tmp
opendir(D, '.');
my @snapshot=map {my $size=(stat($_))[7]; [$_, defined $size ? $size : 0]} sort readdir(D);
closedir(D);

# supply the listing as a table
join(
     # row separator
     "\n",

     # initial lines (to make sure the table paragraph is recognized)
     ('') x 2,