NAME
OpenOffice::PerlPoint - an Open Office / Open Document to PerlPoint converter class
VERSION
This manual describes version 0.03.
SYNOPSIS
# load the module
use OpenOffice::PerlPoint;
# build an object
my $oo2pp=new OpenOffice::PerlPoint(file=>$ooFile);
# convert document
my $perlpoint=$oo2pp->oo2pp;
DESCRIPTION
OpenOffice::PerlPoint
is a translator class to transform Open Office 1.0 and 2.0 (and generally OASIS Open Document) documents into PerlPoint sources. It is based on OpenOffice::OODoc
.
Once you have transformed an Open Office or Open Document document into PerlPoint, it may be furtherly processed using the PerlPoint utilities.
If you prefer, you do not need to perform an explicit transformation. Beginning with release 0.40, PerlPoint::Package
can process Open Office / Open Document sources directly. Please see PerlPoint::Parser
for details, or the documentation that comes with PerlPoint.
This software is in alpha state. It supports just a subset of the source format features. Please see the NOTES sections below.
METHODS
new()
The constructor.
Parameters:
All parameters except the first are named.
- class
-
The target class name. This parameter is set automatically if you use the usual Perl syntax to call a constructor.
- file
-
The (absolute or relative) path to the Office document that should be converted.
- imagebufferdir
-
OO document images refer to images stored within the document or located externally at a location that is specified by an URL. Both image sources cannot be accessed by PerlPoint, so the converter makes copies from those sources and refers to them. The
imagebufferdir
option specifies where these intermediate copies should be stored. The directory is made unless it already exists.A relative path will result in a directory relative to the document. An absolute path is suitable if images from various documents should be collected in one place, or if the resulting PerlPoint document should be written to a special path.
- metadataTemplate
-
A template to include document meta data to the transformation result. The template is expected to be in
Text::Template
format, in a safe compartment.These data are available:
- %metadata
-
A hash of all document meta data. The keys of this hash are the following, while the values hold the document data assigned to that keys.
- %tools
-
Keys:
generator
holds the name of the program that wrote the OO document.converter
holds the name of the converter, usually the name of this module. - $source
-
Source name, usually the name set by option
file
.
This option has no effect if
skipmetadata
is set. - skipmetadata
-
If set to a true value meta data processing is bypassed.
- userdefinedDocdata
-
Each OO document can be described by various predefined data, which are set automatically (like the modification date) or set up by the document author in a dialog (like the documents title). Additionally, OO allows to define up to four user informations. Called
info1
to info4 by default, they can be named individually if required.This option expects a reference to an array of names for those user defined document data entries. The names can be used in templates passed in via option
metadataTemplate
to access the data stored in the related document fields.
Returns: the new object.
Example:
# build an object
my $oo2pp=new OpenOffice::PerlPoint(file=>$ooFile);
oo2pp()
Perform conversion of the document specified in the constructor call.
Parameters:
- object
-
A object as supplied by
new()
.
Returns: the PerlPoint string.
Example:
# convert document
my $perlpoint=$oo2pp->oo2pp;
NOTES
First of all, please note the alpha state of this software. OpenOffice::PerlPoint
does support just a subset of the very rich features potentially occuring in an Open Office document. Some features should be added later, other features have no expression in PerlPoint and therefore are ignored.
Supported features
- Meta data
-
Selected meta data are transformed into PerlPoint variables. The names of these variables are fix in the current version of
OpenOffice::PerlPoint
, but shall become configurable in later versions.- Title
-
Stored in
$docTitle.
- Subject
-
Stored in
$docSubtitle.
- Description
-
Stored in
$docDescription.
- Author
-
Stored in
$docAuthor.
- Date
-
Stored in
$docDate.
- Version
-
If the user defines a data named
version
, it is stored in$docVersion
. - Copyright
-
If the user defines a data named
copyright
, it is stored in$docCopyright
.
- Headlines
-
Headlines are supported. Make sure to use the predefined headline formats in the Office document, and avoid gaps in headline hierarchies (as they will cause PerlPoint translation errors later).
- Text formatting
-
Bold, italic, underlined, colorized text portions within a paragraph are translated into the related PerlPoint tags
\B
,\I
,\U
and\F
. - Text marked as code
-
In Perlpoint, text within a paragraph can be marked as "code" by the
\C
tag. As there is no comparable feature in OpenOffice (I know of), all text assigned to the font Courier New is treated as such code.The font is fix for now, but shall be configurable in a future version.
- Blocks
-
In PerlPoint, examples can be written into "code blocks", which are paragraphs marked by indentation. Open Office as an office suite is not focussed on code, so again there is a convention. All paragraphs assigned to a style "Code" are treated as blocks.
The style name is fixed for now, but shall be configurable in a future version.
- Lists
-
Lists are basically supported.
Unfortunately, it is difficult to distinguish between ordered and bullet lists in OASIS OpenDocument. That's why ordered lists are transformed into bullet lists if an OpenDocument source is translated. For OpenOffice 1.0 documents ordered lists are handled correctly.
- Tables
-
Tables are supported as long as they are not nested.
- Images
-
Images embedded into the document are fully supported.
- Comments
-
Comments are supported.
Limitations
- Limited to text documents
-
The current version can handle text documents only. Spreadsheets, presentations etc. cannot be transformed at this time.
- Footnote support
-
... is invalid yet. Current results will not pass a PerlPoint converter.
- OASIS OpenDocument
-
is not fully supported at the moment due to the beta status of both Open Office 2.0 and
OpenOffice::OODoc
. As both tools are well supported this is just a matter of time.
TOCs
Office document tables of contents cannot easily be transformed into PerlPoint TOCs. That's why they are ignored.
POD
It should be possible to adapt this library for POD output. This might be done in the future. Both versions could use a common base library.
Credits
This module is based on OpenOffice::OODoc
. Thanks to its author Jean-Marie Gouarné for the module and his helpful support with many questions.
TODO
Support nested tables.
TOC ignoration could become configurable.
Optionally image file copies stored in a buffer directory should be named generically.
Support other formats like spreadsheets and presentations.
SEE ALSO
- OpenOffice::OODoc
-
The module that made it possible to write
OpenOffice::PerlPoint
relatively quickly. - Bundle::PerlPoint
-
A bundle of packages to deal with PerlPoint documents.
- oo2pp
-
A OpenOffice / OpenDocument format to PerlPoint translator, distributed and installed with this module.
SUPPORT
A PerlPoint mailing list is set up to discuss usage, ideas, bugs, suggestions and translator development. To subscribe, please send an empty message to perlpoint-subscribe@perl.org.
If you prefer, you can contact me via perl@jochen-stenzel.de as well.
AUTHOR
Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2005. All rights reserved.
Parts of the module are derived from an oo2pod
example script that came with OpenOffice::OODoc
1.309.
This module is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.
The Artistic License should have been included in your distribution of Perl. It resides in the file named "Artistic" at the top-level of the Perl source tree (where Perl was downloaded/unpacked - ask your system administrator if you dont know where this is). Alternatively, the current version of the Artistic License distributed with Perl can be viewed on-line on the World-Wide Web (WWW) from the following URL: http://www.perl.com/perl/misc/Artistic.html
DISCLAIMER
This software is distributed in the hope that it will be useful, but is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or implied, INCLUDING, without limitation, the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.
The ENTIRE RISK as to the quality and performance of the software IS WITH YOU (the holder of the software). Should the software prove defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even if they arise from known or unknown flaws in the software).
Please refer to the Artistic License that came with your Perl distribution for more details.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 1061:
Non-ASCII character seen before =encoding in 'Gouarné'. Assuming CP1252