Using formatter based converters

With this approach, there is only one converter to know: perlpoint. This converter is installed with PerlPoint::Package.

perlpoint is kind of a launcher. It can handle various target languages by loading related modules. Likewise, it formats the results in a specific way, using templates if requested. You just have to define the way your output should be built. The setup is performed by options.

First, you have to choose the target language. At the time of this writing, these languages are available:

• SDF,
• XML.

To get the most recent list, please have a look at CPAN. Language generators are implemented as Perl modules, so you can search for modules named PerlPoint::Generator::<LANGUAGE>. Capitals are used intentionally: all language modules are capitalized by convention.

OK, let's say we want to produce XML, as this is cool and near to HTML. We use the -target option to let perlpoint know of this decision.

    perlpoint -target XML source.pp

Similar to other converters, the source files are passed in as parameters.

With this call, we get a list of copyright notes and an error message:

    perlpoint 0.01, (c) J. Stenzel (perl@jochen-stenzel.de), 2003-2005.
  
    This is a PerlPoint::Generator::XML::Default converter.
  
    PerlPoint::Generator::XML::Default 0.01 (c) J. Stenzel (perl@jochen-stenzel.de), 2003.
    PerlPoint::Generator::XML 0.01 (c) J. Stenzel (perl@jochen-stenzel.de), 2003-2004.
    PerlPoint::Generator 0.01 (c) J. Stenzel (perl@jochen-stenzel.de), 2003-2005.
  
    [Fatal] Missing mandatory option -doctitle.

First, the program is reported to be a PerlPoint::Generator::XML::Default converter. Every language is written by a formatter. Changing the formatter redefines your results. If no formatter is specified as in our call, perlpoint falls back to the default converter. Every language module comes with a related default converter, so it is always available.

Then, you see all the modules that were loaded automatically. From a users point of view, these are just internals handled behind the scenes, but you can see that there's a hierarchy.

Finally, we have that error message. Oops - perlpoint requires a minimum of document and file data, including the title ( -doctitle), filename prefix ( -prefix) and filename suffix ( -suffix) Different to pp2html, the -suffix option requires to specify the extension dot).

    perlpoint -target XML -doctitle Example -prefix example -suffix .xml source.pp

And with this call, the converter generates an XML file example.xml.

As our option list grows quickly, we switch to an option file now. Option files allow to read options from a file, written exactly as on the command line, intermixed with comments and empty lines for readability. At this opportunity we add a target directory:

    # document title
    -doctitle Example
  
    # filenames
    -prefix example
    -suffix .xml
  
    # target directory
    -targetdir example

The call now changes to

    perlpoint @options.cfg source.pp

In the following we will assume that all necesary options are stored in the option file. On the command line, we will focus on the options we are talking about.

Well! The XML produced is very general, but of course it follows a DTD. The DTD can be printed out by using -writedtd and -xmldtd.

    perlpoint @options.cfg -xmldtd example.dtd -writedtd source.pp

After this call, you not only have the required XML file but also example.dtd which describes the general format and can be used to transform the results in whatever you want. For example, we could produce XHTML using XSLT. But fortunately, there's a formatter that emits XHTML directly.

Formatters are plugins implemented by Perl modules. For a list of formatters available for your target language, again scan CPAN for modules named PerlPoint::Generator::<your target language>::<Something>. (The "Something" might include various module levels.) A search for the XML target currently replies these formatters:

• PerlPoint::Generator::XML:: XHTML,
• PerlPoint::Generator::XML:: XHTML::Paged,
• PerlPoint::Generator::XML:: AxPoint.

By installing their distributions, these formattes become available to perlpoint. To invoke a formatter, use the -formatter option.

    perlpoint @options -target XML -formatter XHTML -suffix .html source.pp

Note that the formatter name is specified in a short form. Only the module levels after PerlPoint::Generator::<target language> are required.

Our latest call produced a single HTML page example.html. The XHTML is basic but can be easily improved by using the various options of the new formatter. To find the available tuning tools, add -help to your call.

    perlpoint @options.cfg -help source.pp

This will display the online help, containing a section "Options". You'll find things like -css, -favicon, -norobots and more. These were not available before as we used the default formatter - check it by another help request:

    perlpoint @options.cfg -formatter Default -help source.pp

Indeed - now there are no XHTML specific sections. Instead we find XML specific stuff like -writedtd. The help adapts to the current call. Always use -help to find out the options you have.

Do we get even more options for the XHTML::Paged converter? Looking at the help it doesn't seem so at the moment (but this could change in the future, so always check the help after updates). What we get with this formatter is a splitted output - each chapter is on its own page now. These pages are named <prefix>-<chapter number><suffix>, e.g. example-10.html.

    perlpoint @options -formatter XHTML::Paged source.pp

The layout is still basic. There are two ways to beautify it. First, we can use the options provided by the language generator and the formatter, e.g. -css. Additionally, we can use the third component of the generator design: templates. pp2tdo means "template driven output", and all you need is typically a style for your language format. Styles are special directory structures containing configurations and templates for a certain layout, and are assigned using the -styledir and -style options:

    perlpoint @options -styledir . -style test source.pp

For a working style, please have a look at the demo/styles directory in the PerlPoint::Package distribution. To use the style "GPW7-PPGenerator-01", change your call to this

    perlpoint @options -styledir .../demo/styles -style GPW7-PPGenerator-01 source.pp

And voila - now your pages have a modern, CSS driven layout with navigation, colors, headers, footers, bullet graphics, JavaScript navigation and more!

Now, you might try the second example style, "FramesAndApplet" ...

    perlpoint @options -style FramesAndApplet source.pp

.. to get a layout with frames, different colors, detailed navigation bars on each page and a Java applet navigation tree.

Styles make it very easy to reproduce a layout and to share it with others.

Where to get more styles? We plan to have a download section on the project homepage, but it is not there yet. For the time being, search the net or write them on your own which is not as complicated as you might think. There is a special section about this later on, but as a short intro template modules add lots of options to fine tune your results. To get an impression please request help for a call with option -templatesAccept:

    perlpoint @options -templatetype Traditional -templatesAccept XML/XHTML::Paged -help source.pp

Don't care of the complicated call as it is usually hidden in a style definition.

Basically these are the basics of using PerlPoint generators. Call perlpoint for a target language, specify a formatter to use, add a style if available and use -help to find out which options are available for tuning. Everything else is handled behind the scenes.