view release on metacpan or  search on metacpan

Changelog  view on Meta::CPAN

continue to run or should be adapted soon (as I know there is an adapted Converters
package on the way).

Second, 0.40 introduces an extended framework, which in this release is in \I<beta state>
because of lacking tests and incomplete docs. Nevertheless, it is well tested in production
and should be save to use.

Read on for all the details!

\LOCALTOC


==Features

There are lots of new features, most of all an extended framework which should
make it much easier to write converters.

The new parts are just \I<extensions> of the "old" framework which remains in action
(and is used by the new parts), so converters using the traditional interface
should continue to run.


==Extended framework 

This version introduces a new converter, \BC<pp2tdo> ("template driven output"),
and a new part of the module framework, the \C<PerlPoint::Generator>
hierarchy, which implement a very generic and general converter approach.

See the new section "The formatter approach" in "Writing converters" for
details about this new model.

Here are a few highlights:

* Object oriented extension design.

* Separation of general function, language specific actions and formatting.

* A clear, simple to use, entity based interface for subclassing of only
  a few methods to overwrite.

* All the basic work - dealing with parser, stream, backend and backend events
  - is already done by \C<PerlPoint::Generator>.

* Easy to extend. Generator authors just add formatting.

* Every subclass can add additional options.

* Every subclass can add additional help portions.

* As formatting is determined by the formatter subclass, several templating
  systems can be used in parallel by just switching the template engine. A
  general template layer is provided.

* \I<All> generators can use styles.

* General style format with parts for configuration, templates, docs and screenshots.

* Subclasses can be defined even in a style, so a style can come with its
  own formatters and template systems if necessary.

* Most of the docstreaming and index work is now done a central place, so
  all generators can use it and do not have to deal with it themselves.

* \I<The "old" approach is still available and supported>, and existing converters
  will continue to run, as the old part of the framework is the base of the new part.
  The new generator part just adds an additional level of abstraction, making it easier
  to focus on the target format and layout.


===New SDF generator

As a reference implementation, the functionality of \C<pp2sdf> was reimplemented
in the generator model. To produce SDF this way, invoke \C<pp2tdo> with option
\C<-target SDF>.


===First pure XML generator(s)

Well, we already had the demo converter that produced XML for PPresenter,
but now a \I<common> implementation is available, implemented with the
new generator approach. To produce XML, invoke \C<pp2tdo> with option
\C<-target XML>.

Best of all, if the result does not meet your needs, it is easy to control
entity translation by options. If this is not sufficient, it is easy to write
a modified converter by subclassing \C<PerlPoint::Generator::XML>. See
\C<PerlPoint::Generator::XML::Default> for an example and "Writing converters"
for instructions.

Various formatters are available to produce XHTML, paged XHTML and AxPoint.
These are published as standalone CPAN packages, watch the PerlPoint namespace
or the project side on SourceForge.


===Further reading

To learn more about the new features and generators, please read via \C<perldoc>

* the docs of \C<pp2tdo>;

* the \I<help> of \C<pp2tdo>, activated by option \C<-help>, which adapts itself to
  the \C<-target>, \C<-formatter> and \C<-template> options:

  Here are a few example calls (each call on one line):

  pp2tdo -target SDF
  pp2tdo -target XML
  pp2tdo -target XML -formatter XHTML
  pp2tdo -target XML -formatter XHTML::Paged
  pp2tdo -target XML -formatter XHTML::Paged -templatetype Traditional
         -templatesAccept XML/XHTML::Paged
  pp2tdo -target XML -formatter AxPoint
  ...

... and have a look at the example template provided in the \C<demos> subtree.


==Incompatibel changes for users

* Empty (reset) variables will no longer be replaced by empty strings.
  This might become a problem - such variables were occasionally used

Changelog  view on Meta::CPAN

===\\INCLUDE

Now it's easy to use a central repository of (macro / variable / code /
filter / document) libraries:

* \BC<\\INCLUDE> now searches pathes specified by an environment variable
  \BC<PERLPOINTLIB> (similar to \C<perl>, shells, linkers etc.) if the
  specified file cannot be found directly. In the tradition of \C<PATH>
  and \C<PERL5LIB>, pathes are delimited by (optional whitespaces and)
  semicolons.

  path1\B<;>path2\B<;> path3   \B<;>   path4\B<;>path5

* The new C<PERLPOINTLIB> path feature is available immediately with
  this package version, regardless of converter adaptations.

* Converters can pass a new parameter \C<libpath> to the parsers method
  \C<run>. The argument of \C<libpath> should be a reference to an array
  filled by converter options. I suggest a new conventional option
  \I<\C<-includelib>> to be invoked multiple times (in the tradition of
  \C<-I> options available for \C<perl> and various compilers).

* \C<-includelib> needs converter adaptations, so please use
  \C<PERLPOINTLIB> till updated converters appear.

Pathes specified via \C<-includelib> (or the internal representation
\C<libpath>, respectively) are searched \I<before> pathes specified via
\C<PERLPOINTLIB>.

* Pathes of included files are resolved now - circular inclusions caused
  by links pointing to the same file can be detected earlier this way. As
  a side effect, the resulting absolute file names improve error messages.


===Cache

* Paragraphs containing tags using finish hooks are no longer cached.
  A tag finished after parsing makes the whole paragraph depending on
  something that cannot be cached on base of the parsed text.

* Anchors defined by a cached paragraph are cached now as well - and
  restored after a cache hit.

* The implementation of the mentioned last point required an extension
  of the internal cache format. Cache files made by versions prior
  0.37 will be rebuilt automatically next time they are used.



===pp2sdf

* Avoiding more backslashes in paragraphs starting with an SDF command.

* New option \BC<-result> to specify an output file.

* Supports document streams by three modes: docstreams can be ignored,
  entry points can be made headlines, or \C<pp2sdf> can produce one
  document per docstream.

* Provides new conventional converter options \BC<-includelib>,
  \BC<-docstreaming> and \BC<-skipstream>.


===Misc

* Slightly improved the \C<README> file.

* \BC<flagSet()> now takes a \I<list> of flag names and checks if at least one
  of the flags is set (implicit \I<or> condition). This makes it more handy
  to write combined conditions. Thanks to Helmut Steinbach to make me
  thinking about this.

  old:

  ? flagSet('a') or flagSet('b') or flagSet('all')

  new:

  ? flagSet(qw(a b all))


* \C<PerlPoint::Anchors> was extended by a logging mode to trace newly
  added anchors.

* Added tests of condition interface functions (currently \C<flagSet()>
  and \C<varValue()>).

* Improved headline tests.

* Added paragraph filter tests.

* Paragraph filter functions can access the type of the paragraph
  using the new variable $main::_pfilterType.

* Empty text paragraphs are no longer made part of the stream.

* Blocks were streamed with a final newline, improved.

* Demos \C<pp2pod> and \C<pp2tree> auto-anchor headlines now (so
  \C<\\REF> can be used).

* New headline shortcuts. Thanks to Robert Inder who asked for them.
  A shortcut is a plain string appended to the headline title,
  separated by a "~". \I<Converters need to be adapted - currently
  there is no shortcut support available.>

  =A very long headline which may not fit
   into the navigation bars \B<~ \I<Long headline>>

* Updated \C<hilit19> extensions for Emacs (in the \C<utilities> directory).

* Updated docs.



=0.36

This is a major update - in the sense that it modifies a lot of internals,
especially stream handling. Nevertheless, it's almost completely compatible
with earlier versions of the package (and the few \REF{name="Summary:
Incompatible changes" type=linked}<incompatible changes> most likely do