PerlPoint-Package

 view release on metacpan or  search on metacpan

Changelog  view on Meta::CPAN

This update affects the test suite \I<only>.

=0.451

This version is similar to 0.45 in function, it fixes the test suite on UNIX
systems. Thanks to Andreas König who triggered me to publish this fix.

=0.45

=Fixes

* The chapter delimiter parameter of the \CX<INDEXCLOUD> tag was documented
  as \C<chapterdelimiter>, not \C<chapter\B<B>elimiter>.
	
=0.44

\ILLT

=Features

* New basic tag \CX<INDEXCLOUD>. The tag collects index entries of a chapter
  range (and all included subchapters) or the whole document. The stream
  contains all the tag options. Generator based converters can rely on
  additional informations, which include a list of all index entries in the
  chapter range specified, and a quick ranking - a unified list of indexed
  phrases and their occurence number.

* \CX<PP::Generator::SDF> shows an example implementation for \C<\\INDEXCLOUD>
  in generator based converters. As SDF cannot paint clouds, the tag
  is transformed into an ordered  ranking list.

* \C<\\INDEXCLOUD> implementations in traditional backend based converters
  are more expensive and depend on the converters internal index management
  and data structures, so they can vary. \C<pp2sdf> shall show one
  possible implementation in future versions.

* New value for \CX<\\INCLUDE>'s \CX<type> option: \CX<parsedexample> works
  like \CX<example>, but embeds the file contents as a standard block (which
  is parsed), instead of as a verbatim block like \C<example>. Parsing an
  example file is especially handy when working with (highlighting) paragraph
  filters.


=Fixes

* \X<SDF> generator had not been adapted to several of the last stream format
  updates.

* Code passed to \CX<_cnd_> was not accepted if it evaluated to "false" in Perl.
  Now the valid "0" is handled correctly.
	
	
=0.43

\ILLT

==Features

\ILLT

===Import filter API for the INCLUDE and EMBED tags

PerlPoint supports import filters for other formats since package version
0.38, via tag option \C<ifilter>:

  \\INCLUDE{type=pp ifilter='pod2pp' file="file.pod"}

Nevertheless, this could be simplified. With the new option C<import>
this can be written as

  \\INCLUDE{type=pp import=pod file="file.pod"}

, given a module \C<PerlPoint::Import::POD> is installed (note: see the
\C<Pod::PerlPoint> distribution for this module). The import
module API is new and requires the module to define a function \C<importFilter()>,
with the same interface as functions for \C<ifilter>. In fact,
\C<import=pod> is a shortcut for \C<ifilter="PerlPoint::Import::POD">.

With \C<\\INCLUDE>, the import option can use the \I<source file extension> as the
source format. This is enforced by using a true numeric value for this option,
instead of a string:

  \\INCLUDE{type=pp import=1 file="file.pod"}

When both \C<import> and \C<ifilter> are used together \C<import> is ignored.

===Automatic import of entire files
	
The new standard import filter API is used to allow automatic import of source
files in other formats. Import is requested by the special prefix \C<IMPORT:>,
like in

  > perlpoint ... \B<IMPORT:>source.pod

With the prefix, PerlPoint treats the file extension (\C<pod>) as the name
of the source format, searches for the related import module (\C<PerlPoint::Import::\B<POD>>,
again the format is all uppercased in the module name by convention) and
invokes it automatically.

This feature applies to all existing converters automatically.

	
===Misc

* new option \BC<-version> for \C<perlpoint> and \C<PerlPoint::Generator>,
  thanks to Achim Grolms for the suggestion;
	
* the default file type for C<\\INCLUDE> and the default language for
  \C<\\EMBED> are \C<pp> now;
	
* all generator based converters now accept the new option \C<-acceptedFormat>,
  which specifies languages to be accepted in included files or embedded
  snippets (with \C<\\INCLUDE> or \C<\\EMBED>);

* parser: slight code optimizations;

	
=0.42

The main intention of this update is to allow the production of better
structured results (like correct XHTML). On the way to there, fixes and
improvements were made.

There should be no incompatibility with 0.41.

\ILLT
	
==Features

* Tag authors can declare their tags as standalone now. If the parser
  finds a text paragraph is occupied by such a tag entirely, the
  paragraph "wrapper" is removed from the stream. This allows to
  produce better output for tags that are transformed into something
  that does not fit into a paragraph. (We had this before for images
  and a few other special tags, but now this is a general mechanism.)
  Standalone tags not used standalone have no special effect.

* Likewise, if all that is found in a paragraph is an embedded area
  (\C<\\EMBED{...} ... \\END_EMBED>, the wrapping paragraph directives
  are removed from the stream.

* \C<IMAGE> tags now get an \C<alt> option by default unless they define
  their own (the default is "Image").
	
* \C<perlpoint> now reads option files from the start directory, allowing to
  have a \C<.perlpoint> file in a project tree.

	
	
==Fixes
	
* statistics for list shifters did not work;

* macro default parameters were not documented!

	
==Misc

* dummy tokens inserted by the parser now are special strings that are filtered
  out by the backend module, the old string solution injected empty tokens into
  the stream;


=0.41

This is a light update performed with the introduction of \C<PP::Template::TT2>.
No adaptations should be required except for the name change from \C<pp2tdo> to
\C<perlpoint>.
	
As \CX<pp2tdo> is intended to be one converter for many formats, it is now renamed
to \CX<perlpoint>. It does \I<not> mean other \C<pp2...> converters are out of
support in any way which they are not. The idea just came up when thinking about a
binary package built with pp (from \C<PAR>), for which a name of "perlpoint" seems
appropriate and memorable.


==Features

* \C<PP::Generator> provides a new option \C<-mainstream> which allows to specify
  an alternative name for the document stream "main" (as a usage example, this
  helps to produce S5 slides which require DIV areas with certain names)

* main document stream now produces entry and leave point as well, allowing to
  format this stream a special way in the target format (again, S5 is an example
  of how this can be used)
	

==Fixes

* Generator classes did ignore the parsers nested table configuration, therefore no
  generator based converter could provide nested table support. Fixed.

	
==Misc

* Updated \C<MANIFEST> and \C<TODO>.

* Prepared for use with \C<PP::Template::TT2>.

Changelog  view on Meta::CPAN

their subchapters> should be scanned, too. Finally, there's an option
to configure a minimal match threshold (absolutely or by percentage).

Converters can take the provided chapter list and present them as
they like.

The appropriate tests and docs were added.


==Docs

* The documentation now mentions explicitly that list indentation is
  reset \I<automatically> by any subsequent non list paragraph. Thanks
  to Marcus Holland-Moritz for suggesting this.



=0.38

This is maintenance update for paragraph filters. If you are using
paragraph filters, it is strongly recommended to upgrade.

But hopefully the new features make it worth to update for others, too ;-)
The POD input feature, for example. Or any language you like. Read below.

There are no incompatibilities between \REF{name="0.37"}<0.37> and 0.38.
All PerlPoint sources which passed 0.37 should pass 0.38 as well. All
converters should continue to work.


==Bugfixes

* Paragraph filters did remove guarded backslashes (\C<\\\\>) and
  guarded ">" characters (\C<\\>>). Improved.

* Paragraph filters restored the original source with bodies for
  bodyless tags, fixed.

* Paragraph filters did not reinsert all backslashes (they handled
  the first occurence only) when restoring the original source.

* Paragraph filters inserted backslashes into verbatim paragraphs
  when restoring the original source (thanks to Lorenz for the report).

* Empty headlines could cause errors and infinite parser loops.

* \C<pp2sdf>: removed occasional warnings displayed without real
  reason. Fixed a \C<splice()> usage bug.



==Changes

* Tags are streamed with an additional information. Both opening and closing
  directives now provide a body hint telling a backend programmer if the tag
  has a body or not.

* The lexer makes use of precompiled patterns now, but it seems not to affect
  the performance of parsing.

* \C<\\INCLUDE>, \C<\\EMBED> and \C<\\TABLE> now support the \C<_cnd_> option,
  like tags defined externally.

* Embedded parts and included files can be preprocessed by the new "input
  filters" - snippets of PerlPoint author defined Perl code transforming
  the included or embedded parts before they are processed as usual. This
  is a generic implementation of sourcefile import.

  For example, it is possible to process POD sources
  directly now. Here is a simple filter that does the job:

  \\EMBED{lang=perl}

  use Pod::PerlPoint 0.03;

  sub pod2pp
   {
    my ($pod2pp, $result)=(new Pod::PerlPoint());
    $pod2pp->output_string(\\$result);
    $pod2pp->parse_string_document(@main::_ifilterText);
    $result;
   }

  \\END_EMBED


* Or try the new demo source file, \C<demo/perlpods.pp>, with your favourite
  PerlPoint converter. (Make sure the cache is deactivated and you are using
  \C<-active -safe ALL>. Depending on your system, this is a CPU, memory and
  time consuming job producing over 12.000 pages when processed with perl 5.8.0.)

* Demo converters \C<pp2pod>, \C<pp2pp> and \C<pp2tree> got the usual interface
  (supporting traces etc.).

* New trace switch \C<\X<TRACE_TMPFILES>> avoids removal of temporary files
  (which are new as well - and written when on includes files via input filters).



==pp2sdf

* Brackets (\C<[]>) seem to have a special meaning in SDF:
  \C<sdf> evaluates their contents by \C<eval()>, which causes
  a lot of confusion in (Perl) example paragraphs - as a
  workaround, all opening brackets in blocks are now written
  as \C<\\[>.

* Anchor and links names (in \C<id=> and \C<jump=> specifications)
  are enclosed by Perls \C<q()> operator now, in the hope to
  avoid trouble with quotes in the anchor. (But what about
  parantheses in an anchor name now? It seems to work.)



=0.37

This is a maintenance update. It can replace version 0.36 transparently
except for verbatim block paragraph filters and \C<pp2sdf> output handling.
See next section for details.


==Incompatible changes

* Paragraph filters intended to be applied to verbatim paragraphs need
  to be adapted: they now receive the \I<full> paragraph text
  \I<including> the enclosing heredoc parts (e.g. \C<<<EOE> and matching
  \C<EOE>).

* Extended headline stream interface. This only effects converter authors,
  but not really, because there are just two \I<additional> parameters now.
  See below.

* \BC<pp2sdf> now needs an explicit result file setup by the new option
  \C<-sdffile>. Previous versions wrote to \C<STDOUT>.




==Bugfixes

* \C<pp2sdf>: \BC<\\SEQ> did not set an anchor when the \C<name> option
  was specified.

* A combination of \C<\\REF>, \C<\\SEQ> and activated cache caused trouble

Changelog  view on Meta::CPAN

  \\FORMAT{\B<align=left>}

This should make all following text paragraphs and table cells left justified,
until the end of the document or another alignment setting is made. So the
meaning of \C<\\FORMAT> is to configure \I<default> formattings.

As formatting is very target language specific, each converter can define
valid settings it accepts and evaluates. C<\\FORMAT> may then be used to
make settings interpreted by \I<various> converters \I<at once>:

  // this example uses imaginary settings
  \\FORMAT{\B<html_xxx=2 sdf_xxx=5>}

Nevertheless, certain configurations may have a common meaning. I encourage
converter authors to establish conventions. The first conventional setting
established is \C<align> which shall accept the values \C<left>, \C<center>,
\C<justify> and \C<right>.

This tag was invented after Carlos Malvar suggested we could offer
justification. Thanks, Carlos.



===New basic tag \\HIDE

This tag removes all its contents. This makes sense if used together
with a tag condition.

 \\HIDE{_cnd_="$hideSecrets"}<\SECRETS>


===New basic tag \\STOP

Another tag that makes most sense if used with tag conditions. It
raises a syntactical error and thereby stops document processing
immediately. So, to check if the used parser version meets the needs
of your up to date document, write

  \\STOP{_cnd_="\$_PARSER_VERSION<0.36"}


===New type of active contents: paragraph filters

Carlos Malvar asked me for automatic example highlightning.
Thinking about how users could afford automatic highlightning
without having to support various example languages by PerlPoint
directly, I thought a general solution might meet such needs.
So now users can declare \I<paragraph filters> which means they
declare that certain paragraphs should be passed to a specified
piece of code when parsed. This is, obviously, Active Content.
The filters results must be valid PerlPoint which will then be
reparsed.

So finally those filters are there. Here is a complete example to
demonstrate how this feature can be used. The example document
contains a verbatim block of Perl code, which is made a block by
a user filter. The simple filter marks all Perl comments bold
(using a straight forward comment detection).

  // define the paragraph filter
  \\EMBED{lang=perl}

  sub formatComments
   {
    # $main::_pfilterText is used to
    # pass the paragraph content
    $main::_pfilterText=~s/(#.+)$/\\\\B<$1>/mg;
    $main::_pfilterText;
   }

  \\END_EMBED

  Now, an example in a verbatim block paragraph:

  \B<||formatComments||><<EOM

    # 1st comment
    This is my example. # 2nd comment

    Continued.

    # another comment
    $c=5+10;

  EOM

  Example completed.

Please note the preamble which installs the filter to use.

Here is another filter that automatically numbers example lines:

  sub filter2
   {
    # init line counter
    my $c;

    # transform example text
    my $t=$main::_pfilterText;
    $t=~s/^([ \t]*)/join('', ' ', ++$c, ": $1")/mge;

    # provide result
    $t;
   }

Filters can be chained by using a single pipe character:

  ||markComments\B<|>numberLines||<<EOM

  ...

  EOM

To try this successfully, Active Content has to be enabled
(converter option \C<-active>). If Active Content is disabled,
filters cannot be installed. (Copy the example from a converters
result, not from this Changelog source to avoid backslash trouble.)

Paragraph filters can be assigned to almost all types of paragraphs,
not only verbatim blocks. But because they work after a paragraph is
processed, they make no sense for paragraphs which do not produce
output directly. So filters are not allowed for conditions,
alias definitions and variable assignments (for grammatical reasons
filters \I<can> be assigned to the last mentioned paragraph type,
but I hope to fix this in future releases).

There is no loop check currently. If a filter produces a filtered
paragraph, things might end in an endless loop.

As always, feedback is highly appreciated. Documentation and tests
are planned to be added.