NAME

OpenOffice::OODoc::Notes - Notes of the OpenOffice::OODoc man pages

DESCRIPTION

The OpenOffice::OODoc::Notes page contains all the notes corresponding to the "[nn]" note citations included in the other documents.

NOTES

        [1] In fact in this case a more complex (but hidden) operation is
        carried out: firstly it writes to a temporary file and if no error
        occurs, the source file is deleted and its name given to the
        temporary file. OODoc::File never writes directly to the source
        file.

        [2] For example, the pair ('/office:body/text:p', 12) or
        ('//text:p', 12) represent, in an OpenOffice.org document, the
        thirteenth occurrence of the 'text:p' element or the 13th paragraph
        of text (XPath occurrences are numbered table elements in Perl,
        starting from 0).

        [3] For example, you can easily copy a paragraph from one document
        to another but only if you knowingly modify the paragraph's style
        attribute if that style is not already defined in the destination
        document. You can also copy the style but only if you are sure that
        this style is not already defined by another unknown style in the
        destination document (and so on).

        [4] Can also be shortened to ooXPath() if the XPath module is loaded
        via the main OODoc module.

        [5] (removed)

        [6] It is just a single element 'office:body' which contains all the
        text in an OpenOffice.org document. Therefore, the XPath path
        indicating the text is always ('//office:body', 0). Remember that in
        the case of an OpenOffice.org text file (Writer), it would be better
        to use the appendParagraph method of OODoc::Text as this requires
        fewer parameters.

        [7] "automatic styles" are styles which are not explicitly indicated
        in the styles list as it appears to the end user.

        [8] If for any reason you absolutely have to use a non-UTF8 XML
        string which contains 8-bit characters (accented letters, etc.), you
        can always convert the string using the encode_text method before
        passing it to appendElement. Of course, the problem will not arise
        if you are absolutely sure that the string only contains ASCII (7
        bit).

        [9] XML syntax is checked, but it is up to the user to verify that
        the element import conforms to OpenOffice.org document syntax.

        [10] OpenOffice.org documents use UTF8 XML encoding.

        [11] In the examples we have looked at, handling of UTF8 strings is
        rudimentary but effective in the current version. It appears at
        least to generate French accented characters properly. Any potential
        contributors who have mastered UTF8 are invited to improve the
        implementation of this method.

        [12] See the Perl/Encode manual for the list of supported character
        sets. If the user's character set is selected using the
        localEncoding() function, any unsupported value (according to the
        current Perl installation) is automatically rejected. A list of
        accepted encodings can be returned by Encode::encodings(':all')
        (the Encode module is loaded by OpenOffice::OODoc, so this function
        is always available for the application). Some encodings can be
        named using aliases (see the Encode::Alias documentation).

        [13] To do a Find/Replace in an entire text document, use the
        selectTextContent(filter, replacement) method in OODoc::Text.

        [14] In the current version, inserting an element imported in XML
        can mess up the internal numbering of elements. Such inconsistencies
        are only a problem for methods which will later access elements
        according to their position. They have no effect on the document's
        integrity when updated using save, and do not affect methods which
        select elements according to content criteria. A reorganize call
        after one or more element insertions imported in XML is normally
        enough to re-establish order.

        [15] However, contrary to insertElement, a copy of the given element
        is indeed created, not just a reference to it.

        [16] (removed)

        [17] (removed)

        [18] Note: such forced attributes do not upset the function of
        OpenOffice.org which ignores them. They could therefore be useful in
        programs which handle documents out of reach of the end user.
        However, if such a document is then edited or updated by
        OpenOffice.org or StarOffice (using currently released versions),
        these "foreign" attributes will be lost and the software will
        replace what it considers to be the "real" values to those
        attributes it manages.

        [19] Remember that in OpenOffice.org document logic, a page break is
        not an element but a paragraph attribute. Generally, you insert a
        page break by giving a 'page break before' attribute to a paragraph.
        This is just one example of the usage of the 'attribute' option.

        [20] See OODoc::Styles module for information about styles.

        [21] 'text:p' refers to a paragraph element, just as 'text:h' refers
        to a header element.

        [22] Any tables contained in headers and footers belong to the page
        layout ('styles.xml') and not the content ('content.xml') of
        OpenOffice.org documents. Such tables are therefore ignored by
        OODoc::Text methods.

        [23] For example: if a currency-formatted cell contains 155.12, the
        'currency' attribute is set to 'GBP' and the presentation style is
        the standard default setting for a British user, the cell's text
        would be "£155.12".

        [24] To access a header of a particular level, you need to use
        selectElementByAttribute and select the 'text:level' attribute (see
        OODoc::XPath).

        [25] See note 41.

        [26] Footnotes are physically inserted into the text at the place
        where they are called, just after the link element indicating the
        footnote's number. Its display at the foot of the page or elsewhere
        is a trick of the graphical interface.

        [27] These methods are implemented as XML::Twig package extensions
        even though they are physically defined in the OODoc/Text.pm module.

        [28] A call to $element->getName returns the element's XML name
        including its namespace prefix e.g. 'text:p' for a paragraph or
        'table:table-row' for a row of a table.

        [29] The program function can return quite sophisticated temporary
        data which is to be inserted into the text and reused later, again
        with this method, in order to do some complex processing in several
        passes.

        [30] You can easily use getText and setText (getText returns "flat"
        text with all style divisions removed) when performing an iteration
        on all of a document's elements. This means you can perform search
        and replace operations which ignore style divisions. In this case,
        however, when you update (setText), any style divisions in the
        original element will be lost.

        [31] Obviously, opening a document in OpenOffice.org or StarOffice
        which contains references to non-existent styles will give
        unpredictable results as to the viewing of the given paragraphs or
        headers.

        [32] The short form ooImage() is available if the main
        OpenOffice::OODoc module is already loaded.

        [33] See OpenOffice::OODoc::Styles for style creation or, better,
        OpenOffice::OODoc::Document for image styles.

        [34] OpenOffice.org Writer gives default names to images (e.g.
        Image1, Image2, ...) if the user does not deliberately name them.
        This is not the case in Impress.

        [35] If you want to know why a background colour is controlled by an
        attribute in the "style" namespace when the colour of the characters
        is controlled by an attribute in the "fo" namespace, post a question
        on xml.openoffice.org...

AUTHOR/COPYRIGHT

Copyright 2004-2005 by Genicorp, S.A. (http://www.genicorp.com)

Initial developer: Jean-Marie Gouarne (http://jean.marie.gouarne.online.fr)

Initial English version of the reference manual by Graeme A. Hunter (graeme.hunter@zen.co.uk)

License:

        - Genicorp General Public Licence v1.0
        - GNU Lesser General Public License v2.1

Contact: jmgdoc@cpan.org