NAME

Pod::OOoWriter - converts a POD file to an OpenOffice.org Writer document.

SYNOPSIS

use Pod::OOoWriter;

my $p = new Pod::OOoWriter outputfile => 'out.sxw', ootemplate => 'tmpl.sxw';
$p->parse_from_file('in.pod');
$p->flush();

DESCRIPTION

This class generates an OpenOffice.org Writer document by merging a text in POD format into an existing OOo document that acts as a template. It derives from Pod::Parser and therefore inherits all its methods.

Constructor

new ootemplate => TMPL, outputfile => OUT

Creates and returns an instance of Pod::OOoWriter. TMPL and OUT are mandatory arguments and are the paths to the OOo template and the output file, respectively.

Methods

Pod::OOoWriter inherits all the methods from its ancestor. See Pod::Parser for details, but parse_from_file() and parse_from_filehandle() are available for parsing the POD text.

flush

This methods actually does the job of generating the output file (given to the constructor as outputfile), based on the template (ootemplate) and the POD text, parsed by parse_from_file() or parse_from_filehandle().

Template Format

The template should contain markup that tells Pod::OOoWriter what formatting to apply when it encounters a given POD directive.

The template must thus contain sample paragraphs in heading style, level 1 to 4. These paragraphs must contain the tokens #head1# to #head4# respectively. This way, when Pod::OOoWriter encounters a =head2 directive, it will apply the same style than that of the paragraph that contained the token #head2#.

Similarly, sample paragraphs must be provided for normal text, including the token #para#, and for verbatim text, including the token #verbatim#. The sample normal paragraph should also contain tokens #bold#, #italic#, #file# and #code#, in character styles that denote, respectively, bold, italic, file names or paths, and code snippets or identifiers.

Samples should also be provided for bulleted, unordered lists, in levels 1 to 3, containing the tokens #over4# to #over6#. 4 is the default indentation level for the =over directive, hence the seemingly weird choice of tokens. Alternatively, #ul1# to #ul3 can be used instead.

For numbered lists, use tokens #ol1# to #ol2#.

A basic template example is included in directory eg/ of the source distribution.

Keyword substitution

Keywords surrounded by double hashes (e.g. ##KEYWORD##) can be included anywhere in the OOo template: in the text, in the page headers and footers or in the document's properties. This allows for defining the document's title, or the author, or the address of the company producing it, etc.

Values for the keywords must be defined in the POD itself, in a =begin OOoWriter section. Each paragraph with such a section will be parsed as a key/value pair, separated by a colon (whitespace on either side of the colon is allowed and optionnal).

=begin OOoWriter

TITLE : Testing Pod::OOoWriter

AUTHOR: Cédric Bouvier

=end

Keywords are case-sensitive, and should match /^\w+$/ (i.e., only letters, digits and underscores).

The Parsing

Pod::OOoWriter starts by parsing the template in search for the #head1# token. Anything before that is copied verbatim to the output. This means that the template can contain a front page, or a table of contents, as long as they appear before the token #head1#.

Once #head1# is found, the rest of the template is still parsed in search for the other tokens, but it is no longer copied to the output. Instead, the output consists of the POD document, with styles applied according to the tokens found in the template.

Once the template has been parsed and the POD text merged within, the keyword substitution occurs.

BUGS AND LIMITATIONS

The numbered list support is still somewhat buggy. For instance, a numbered list nested within another would not start with 1, but with the number that follows the latest item in its parent list, e.g.:

1.
2.
    3.
    4.
3.
4.

Probably many, many more, and then some.

SEE ALSO

perlpod, Pod::Parser

AUTHOR

Copyright © 2004 Cédric Bouvier <cbouvi@cpan.org>

This module is free software. You can redistribute and/or modify it under the terms of the GNU General Public License.

cpanm Pod::OOoWriter

perl -MCPAN -e shell
install Pod::OOoWriter