Provides the tools for doing the conversion of StarWriter XML to and from AportisDoc format.
It follows the {@link org.openoffice.xmerge} framework for the conversion process.
Since it converts to/from a Palm application format, these converters
follow the
PalmDB stream format for writing out to the Palm sync client or
reading in from the Palm sync client.
Note that PluginFactoryImpl also provides a
DocumentMerger object, i.e. {@link org.openoffice.xmerge.converter.xml.sxw.aportisdoc.DocumentMergerImpl DocumentMergerImpl}.
This functionality was derived from its superclass
{@link org.openoffice.xmerge.converter.xml.sxw.SxwPluginFactory
SxwPluginFactory}.
The AportisDoc pdb format is widely used by different Palm applications, e.g. QuickWord, AportisDoc Reader, MiniWrite, etc. Note that some of these applications put tweaks into the format. The converters will only support the default AportisDoc format, plus some very minor tweaks to accommodate other applications.
The text content of the format is plain text, i.e. there are no styles or structures. There is no notion of lists, list items, paragraphs, headings, etc. The format does have support for bookmarks.
For most Doc applications, the default character encoding supported is the extended ASCII character set, i.e. ISO-8859-1. StarWriter XML is in UTF-8 encoding scheme. Since UTF-8 encoding scheme covers more characters, converting UTF-8 strings into extended ASCII would mean that there can be possible loss of character mappings.
Using JAXP, XML files can be parsed and read in as Java Strings
which is in Unicode format, there is no loss of character mapping from UTF-8
to Java Strings. There is possible loss of character mapping in
converting Java Strings to ASCII bytes. Java characters that
cannot be represented in extended ASCII are converted into the ASCII
character '?' or x3F in hex digit via the String.getBytes(encoding)
API.
The DocumentSerializerImpl class implements the
org.openoffice.xmerge.DocumentSerializer.
This class specifically provides the conversion process from a given
SxwDocument object to DOC formatted records, which are
then passed back to the client via the ConvertData object.
The following XML tags are handled. [Note that some may not be implemented yet.]
Paragraphs <text:p> and Headings <text:h>
Heading elements are classified the same as paragraph elements since both have the same possible elements inside. Their main difference is that they refer to different types of style information, which is outside of their element tags. Since there are no styles on the DOC format, headings should be treated the same way a paragraph is converted.
For paragraph elements, convert and transfer text nodes that are essential. Text nodes directly contained within paragraph nodes are such. There are also a number of elements that a paragraph element may contain. These are explained in their own context.
At the end of the paragraph, an EOL character is added by the converter to provide a separation for each paragraph, since the Doc format does not have a notion of a paragraph.
White spaces <text:s> and Tabs <text:tab-stop>
In SXW, normally 2 or more white-space characters are collapsed into a single space character. In order to make sure that the document content really contains those white-space characters, there are special elements assigned to them.
The space element specifies the number of spaces are in it. Thus, converting it just means providing the specific number of spaces that the element requires.
There is also the tab-stop element. This is a bit tricky. In a StarWriter document, tab-stops are specified by a column position. A tab is not an exact number of space, but rather a specific column positioning. Say, regular tab-stops are set at every 5th column. At column 4, if I hit a tab, it goes to column 5. At column 1, hitting a tab would put the cursor at column 5 as well. SmartDoc and AporticDoc applications goes by columns for the ASCII tab character. The only problem is that in StarWriter, one could specify a different tab-stop, but not in most of these Doc applications, at least I have not seen one. Solution for this is just to go with the converting to the ASCII tab character and not do anything for different tab-stop positioning.
Line breaks <text:line-break>
To represent line breaks, it is simpliest to just put an ASCII LF character. Note that the side effect of this is that an end of paragraph also contains an ASCII LF character. Thus, for the DOC to SXW conversion, line breaks are not distinguishable from specifying the end of a paragraph.
Text spans <text:span>
Text spans contain text that have different style attributes from the paragraphs'. Text spans can be embedded within another text span. Since it is purely for style tagging, we only needed to convert and transfer the text elements within these.
Hyperlinks <text:a>
Convert and transfer the text portion.
Bookmarks <text:bookmark> <text:bookmark-start> <text:bookmark-end> [Not implemented yet]
In SXW, bookmark elements are embedded inside paragraph elements. Bookmarks can either mark a text position or a text range. <text:bookmark> marks a position while the pair <text:bookmark-start> and <text:bookmark-end>
marks a text range. The DOC format only supports bookmarking a text position. Thus, for the conversion, <text:bookmark> and <text:bookmark-start> will both mark a text position.Change Tracking <text:tracked-changes> <text:change*> [Not implemented yet]
Change tracking elements are not supported yet on the current OpenOffice.org XML filters, will have to watch out on this. The text within these elements have to be interpreted properly during the conversion process.
Lists <text:unordered-list> and <text:ordered-lists>
A list can only contain one optional <text:list-header> and one or more <text:list-item> elements.
A <text:list-header> contains one or more paragraph elements. Since there are no styles, the conversion process does not do anything special for list headers, conversion for the paragraphs within list headers are the same as explained above.
A <text:list-item> may contain one or more of paragraphs, headings, list, etc. Since the Doc format does not support any list structure, there will not be any special handling for this element. Conversion for elements within it shall be applied according to the element type. Thus, lists with paragraphs within it will result in just plain paragraphs. Sublists will not be identifiable. Paragraphs in sublists will still appear.
<text:section>
I am not sure what this is yet, will need to investigate more on this.
There may be other tags that will still need to be addressed for this conversion.
Refer to {@link org.openoffice.xmerge.converter.xml.sxw.aportisdoc.DocumentSerializerImpl DocumentSerializerImpl}
for details of implementation. It uses DocEncoder class to do the encoding
part.
The DocumentDeserializerImpl class implements the
org.openoffice.xmerge.DocumentDeserializer. It is
passed the device document in the form of a ConvertData object.
It will then create a SxwDocument object from the conversion of
the DOC formatted records.
The text content of the Doc format will be transferred as text. Paragraph elements will be formed based on the existence of an ASCII LF character. There will be at least one paragraph element.
Bookmarks in the Doc format will be converted to the bookmark element <text:bookmark> [Not implemented yet].
As mentioned above, the DocumentMerger object produced by
PluginFactoryImpl is DocumentMergerImpl.
Refer to the javadocs for that package/class on its merging specifications.