view release on metacpan or  search on metacpan

doc/writing-converters-formatters.pp  view on Meta::CPAN

Because the \C<Generator> module does most of the work, the startup needs are really small
and independent on the target format. So the few startup code lines are collected in a single
script called \BCX<perlpoint> ("tdo"="template driven output", based on an initial goal of the
new design (to write a common platform for the integration of arbitrary templating systems)).


=Getting started

To write a formatter, you first should know what the base modules of the generator already do,
which methods of \CX<Generator> objects can be overwritten and which interface they provide.

For this, the following sections describe what's done on the several generator levels.

\LOCALTOC{type=linked depth=1}


==The startup script

\LOCALTOC{type=linked}


===Options declared on this level

The startup script declares very basic options, which will be available in general.

@|
option          | arguments                | example              | description
\BCX<target>    | the target format        | \C<-target XML>      | mandatory
\BCX<formatter> | the formatter to be used | \C<-formatter Easy>  | defaults to "Default"
\BCX<styledir>  | a directory to be searched for styles | \C<-styledir ~/perlpoint/styles> | Can be used multiply. Defaults to the startup directory. For reasons of compatibility with older converters, \CX<style_dir> is allowed as well.
\BCX<style>     | a style name             | \C<-style modern>    | The name of a \REF{type=linked name="Style featured"}<style>.


===Function

Basically this script takes options, builds a \X<\PP::Generator> object and starts it
(by calling its \C<run()> method). This is just a bootstrap.



==The generator level

This is where most of the work is done. Behind the scenes ;-)

This is \CX<\PP::Generator>.

\LOCALTOC{type=linked}


===Options declared on this level

The \CX<Generator> module is the base of all generators, so these options are generally
available.

@|
option               | arguments             | example              | description
\BCX<activeContents> |                       | \C<-activeContents>  | enables active contents
\BCX<cache>          |                       | \C<-cache>           | activates the cache
\BCX<cacheCleanup>   |                       | \C<-cacheCleanup>    | performs a cache cleanup
\BCX<docstreaming>   | method code           | \C<-docstreaming 1>  | configures the document stream handling
\BCX<help>           |                       | \C<-help>            | displays online help ("usage")
\BCX<includelib>     | directory             | \C<-includelib inc>  | Adds a directory to the path searched for files to be included via \CX<\\INCLUDE>. Can be used multiply.
\BCX<nocopyright>    |                       | \C<-nocopyright>     | suppress copyright message
\BCX<noinfo>         |                       | \C<-noinfo>          | suppress runtime informations
\BCX<nowarn>         |                       | \C<-nowarn>          | suppress runtime warnings
\BCX<quiet>          |                       | \C<-quiet>           | suppress all runtime messages except of errors
\BCX<safeOpcode>     | an opcode or "ALL"    | \C<-safeOpcode ALL>  | specifies permitted opcodes in active contents (see the Opcode manpage for details), can be used multiply
\BCX<set>            | a user setting        | \C<-set test>        | allows user settings which can be evaluated in documents
\BCX<skipstream>     | the stream name       | \C<-skipstream left> | skip a certain document stream
\BCX<tagset>         | the set               | \C<-tagset HTML>     | adds a tag set to the scripts own tag declarations (making those tags available)
\BCX<title>          | presentation title    | \C<-title Examples>  | sets up the presentation title
\BCX<trace>          | numerical trace level | \C<-trace 2>         | activates trace messages


===Object data defined on this level

The following public object attributes are defined by this class:

@|
attribute       | description
\BCX<anchorfab> | generates anchor names, use: \C<$me-\>{anchorfab}-\>generic>
\BCX<backend>   | the backend object (see \CX<\PP::Backend>)
\BCX<options>   | a hash of options passed to the generator script
\BCX<parser>    | the parser object (see \CX<\PP::Parser>)

Please note that due to the concepts of this module hierarchy and the mechanisms of Perls
\CX<base> pragma, there are more attributes visible in subclasses, but those are not intended
for public use.


===Function

The base module of the generator hierarchy controls the translation process. It performs
initializations, parses the \PP source and prepares the results for formatters, which it
invokes at the right time.

Knowledge of the internals of this class is no precondition to write subclasses, so the
details are not furtherly explained here. To sum them up, a generator module performs
initializations, parses the \PP sources, runs a backend object to deal with the results
and invokes formatters as soon as their target entities are completely available.


===Inheritable methods

These methods are intended to be inherited and overwritten.

\LOCALTOC{type=linked}


====bootstrap()

\B<Invocation:> called after the constructor (of a subclass).

\B<Function in the \C<Generator> class>: collects options and source filters.

\B<Intention for subclasses:> perform own bootstrap operations.

\B<Parameters:> the object.

\B<Return values:> none expected.