libopenoffice-oodoc-perl 2.125-3 / usr / share / perl5 / OpenOffice / OODoc / Text.pod

=head1	NAME

OpenOffice::OODoc::Text - The text processing submodule of OpenOffice::OODoc

=head1	DESCRIPTION

This manual chapter describes the text-oriented methods of OpenOffice::OODoc,
implemented by the OpenOffice::OODoc::Text class, and inherited by the
OpenOffice::OODoc::Document class.

These methods are not essentially dedicated to string processing; they are
more precisely focused on text containers. A text container is a document
element which can (and must) be used in order to support a text and
integrate it at the right place and according to the right presentation rules.
The OpenDocument specification defines a lot of such containers, and the
present API supports many of them, such as paragraphs, headings, tables (or
spreadsheets), lists, sections, and draw pages. Some of these containers can
host other containers: for example, a table contains rows, a row contains
cells, a section can contain almost everything including other sections, etc.

These features are text-oriented, but can be used on documents of any class,
such as spreadsheets or presentations as well as text documents. So, the
'Text' word doesn't mean that the features described in the present manual
chapter are dedicated to OpenDocument Text (ODT) documents only. In the other
hand, a few methods can't apply to any document class (ex: creating or
retrieving draw pages makes sense with presentation and drawing documents
only).

OODoc::Text should not be explicitly used in an ordinary application, because
all its features are available through the OpenOffice::OODoc::Document class,
in combination with other features. Practically, the present manual is
provided to describe the text-oriented features of OpenOffice::OODoc::Document
(knowing that these features are technically supported by the
OpenOffice::OODoc::Text component of the API).

The OpenOffice::OODoc::Text class is a specialist derivative of
OpenOffice::OODoc::XPath for XML elements which describe the text content
of OOo/ODF documents. Here, "text content" means containers that can
host text containers (i.e. tables, lists...) as well as flat text.

Knowing that the "styles.xml" member of an OpenDocument file can contain
text (because some style definitions, such as page headers or footers, can
contain text), the presently described features can be used against this
member as well as the "content.xml" member.

This module should be used in combination with OpenOffice::OODoc::Styles,
via the OpenOffice::OODoc::Document class, if the application has to handle
detailed presentation parameters of text elements. This is because such
parameters are held in styles elements and not in the text elements
themselves, according to the principle of separation of content and
presentation which is one of the foundations of the OpenDocument format.

=head2	Methods

=head3	Constructor : OpenOffice::OODoc::Text->new(<parameters>)

        Short Form: odfText(<parameters>)

	This constructor should not be explicitly used in ordinary applications
	knowing that all the features of the returned object are inherited by
	any Document object.

        See OpenOffice::OODoc::XPath->new for common arguments.

        Returns an OODoc::XPath OpenDocument connector with additional
	features mainly focused on text containers.

	This constructor is generally not explicitly called, knowing that
	it's automatically triggered each time a Document object is created.

	The XML member loaded by default is 'content.xml'. The most common
        creation method is like this:

            my $doc = odfText(file => 'my_file.odt');

	This constructor should generally not be called directly, because it's
	inherited by odfDocument().

        Other parameters can be supplied as options (see the properties list
        at the end of the chapter).

        Example:

            my %delim =
            	(
            	'text:h'		=>
            		{
            		begin	=> '\sect{',
            		end	=> '}'
            		},
            	'text:list-item'	=>
            		{
            		begin	=> '\item'
            		}
            	'text:footnote-body' =>
            		{
            		begin	=> '\footnote{',
            		end	=> '}'
            		}
            	);
            my $doc = odfText
            		(
            		file		=> 'filename.odt',
            		paragraph_style	=> 'My Paragraphs',
            		heading_style	=> 'My Headings',
            		delimiters	=> { %delim }
            		);

        This technique gives the default styles to be used when creating new
        text elements. It also gives the particular delimiters (in this case
        LaTeX style markers) to be used at the beginning or end of some
        elements (in this case headings, list elements, footers) where the
        text is to be exported "as is". See the getText method of
        OODoc::Text for information about exporting text.

=head3	appendDrawPage([options])

	In a presentation or drawing document, appends a new page at the en
	of the document.

	Possible options are:

		name		=> page name (unique)
		id		=> page numeric ID (unique)
		style		=> page style name
		master		=> master page name

	Returns the new draw page element if successful, undef if not.

=head3	appendHeading([options])

        Creates a new heading of any level and appends it to the end of the
        document.

        Options are given as a hash [key => value]:

            'text'		=> <heading text>
            'level'		=> heading level, default is 1
            'style'		=> heading style, default is 'Heading 1'

        Examples:

            $doc->appendHeading(text => 'Next section');

        adds the text 'Next section' as a level 1 heading.

            $doc->appendHeading
            	(
            	text	=> 'Chapter Conclusion',
            	level	=> '2',
            	style	=> 'Heading_20_2'
            	);

        adds a level 2 heading to the end of the text body. 'Heading_20_n'
	styles, where 'n' is the level number, are presently available by
	default in OpenOffice.org.

        You can give any XML attribute to the new heading except for style or
        heading level. In this case, the program must construct a hash
        containing pairs of key-values for the attributes you want to create
        and pass it using the 'attribute' option. Example:

            my %attr	= ( 'att1' => 'value1', 'att2' => 'value2' );
            $doc->appendHeading
            	(
            	text	=> 'Attributes are important',
            	level	=> '1',
            	style	=> 'Chapter heading',
            	attributes => {%attr}
            	);

        If the 'text' option is empty, the heading is created with an empty
        content.

	Caution, creating headings with level attributes is not always
	sufficient to produce the needed result. For example, in order to
	generate headings with appropriate levels of numbering, each one
	must be attached to the right position in a hierarchy of lists,
	in combination with appendItemList(), insertItemList(), and
	appendListItem().

        Note: this method can only be used with a new header i.e. it adds
        while it creates. To add an already available element using
        getHeading() from the same document or from another document, use
	the appendElement() method instead which is inherited from
	OODoc::XPath.

=head3	appendItem(list [, text => text ,style => style ,[other_options]])

	See appendListItem().

=head3	appendItemList([type => list_type, [style => style [, options]]])

        Creates a new (empty) list and appends it to the end of the
        document.

	In OpenOffice.org 1 documents, an unordered list is the default,
        and if the 'type' option is given with the value 'ordered', then an
	ordered list is created. In Open Documents, the 'type' option is
	ignored because there are generic lists only (a list is ordered or
	"bulleted" according to a style, and not natively).

        The 'style' options controls the list's style (as opposed to each
        item's style). If absent, the list takes the default paragraph style
        (see appendParagraph).

        Like appendParagraph, this method actually creates a new list
        element. To copy an existing list in the same document or in
        another, use appendElement or replicateElement instead.

=head3	appendListItem(list [, text => text ,style => style ,[other_options]])

        Adds a new item to a list (ordered or unordered).

        The first argument is the existing list element (created using
        getOrderedList or getUnorderedList, for example). Options are the
        same as for appendParagraph.

        If the 'style' option is absent, the element is inserted according
        to the following rule:

	- if the new item is not the first one of the list, it takes the
	same style as the first item;

	- otherwise, it takes the default paragraph style of the document.

	The new item is created as a paragraph container by default. A
	'type' option may be provided in order to require another type.
	Possible values are 'header', 'paragraph' or the XML name of any
	OpenDocument-compliant text container.

	If the type is provided and set to undef, the new item is created
	as an empty element, so it could/should receive a content later.
	An empty item could be used as the attachment point of another
	list, in order to create a hierarchy of lists.

=head3	appendParagraph(<options>)

        Creates a new paragraph and appends it to the document.

        Options:

            'text'		=> <paragraph text>
            'style'		=> <paragraph style>

        An 'attribute' option is also available under the same conditions as
        for the appendHeading method (see above).

        If the 'text' option is empty, calling this method is the equivalent
        of adding a line feed.

        If the 'style' option is empty, the style from the 'paragraph_style'
        property of the OODoc::Text instance is used.

	By default, the new paragraph takes place at the end of the document.
	But it's possible to attach it as the last child of an existing
	text container (ex: a table cell). To do so, the container must be
	provided through an 'attachment' option. For example, to append a new
	paragraph in a table cell, one can write

		my $cell = $doc->getTableCell("Table1", "B12");
		$doc->appendParagraph
			(
			text		=> "The cell, reloaded",
			attachment	=> $cell
			);

        Note: this method can only be used with a new paragraph i.e. it adds
        while it creates. To add an already existing paragraph using
        getParagraph from the same document or from another document, use
        the appendElement, insertElement or replicateElement methods instead
	which are inherited from OODoc::XPath.

	Note: The repeated spaces are not properly processed, so any sequence
	of spaces (whatever its length) in the 'text' string is replaced by a
	single space in the target document. See setText() and extendText().

=head3	appendRow(table [, options])

        Appends a row to the end of the given table either by reference, by
        logical name or by sequential number. By default, the new row is
        simply an exact copy of the preceding row (in terms of content and
        presentation). You can pass an options hash which will give certain
        attributes to the created row, under the same conditions as for the
        appendElement method of OODoc::XPath. The returned value is the
        created row element.

        Example:

            open SRC, '<', 'data.txt';
            my $table = $doc->getTable("Table1");
            my ($h, $l) = $doc->getTableSize($table);
            for (my $i = 0 ; my $record = <SRC> ; $i++)
            	{
            	last unless $record;
            	chomp $record;
            	my @data = split ';', $record;
            	my $row = $i < $h ?
            		$doc->getRow($table, $i) :
            		$doc->appendRow($table);
            	for (my $j = 0 ; $j < $l ; $j++)
            		{
            		$doc->cellValue($row, $j, $data[$j]);
            		}
            	}

        The above program reads a CSV format data file sequentially (one
        record per line, comma-separated fields). Each record is split and
        put into a row in table Table1. On reading each new record, the
        reference for the following row is loaded by getRow, until the total
        number of rows is reached (total obtained previously using
        getTableSize). If the table is already full, it is lengthened by a
        row using appendRow. The internal loop loads the read data into the
        row's cells (pre-existing or newly created). See the sections on
        getTable, getRow, getTableSize and cellValue for a better
        understanding of this example.

        However, if good performance is what you are after, massive
        repetition of this method is not recommended (e.g. for lengthening a
        table dynamically, row by row, whilst loading external data into
        it). Rather than running dozens or hundreds of successive
        appendRows, it would be better for the application to read the total
        number of records to be loaded (using, for example, select count if
        from a relational database or otherwise preloading the data into an
        ordinary Perl table) and create a table of appropriate size in
        advance using insertTable() or appendTable().

=head3	appendSection(name [, options])

	Creates a new section with the given name, and appends it by default
	to the end of the document body. If the "attachment" option is
	provided, with an existing element as its value, the new section is
	appended in the context of this element. For example, if the value
	of "attachment" is an existing section, the new section is appended
	as the last sub-section of the existing one.

	A section may be used either to hold a local content or to insert
	a subdocument which can be reached through an external link.

	In order to insert a subdocument link instead of an ordinary section,
	the application must provide a "link" option whose value is either a
	local file path or an URL.
	Example:

	    $doc->appendSection
		(
		"Article",
		link => "http://mycompany.com/doc/article.odt"
		);

	Other possible options:

	    'style'	allows the application to explicitly select a style
	    		for the new section
	    'protected'	write-protects the section when the document is
	    		edited; "true" or "false", default "false"
	    'key'	in combination with "protected" => "true", write-
	    		protects the section by password (the value of
			"key" is not the real password, but an encrypted
			password, so the end-user will never remove the
			protection by simply typing the key as it is
			written in the program); see lockSection(),
			unlockSection() and sectionProtectionKey()

=head3	appendTable(name, rows, columns [, options])

        Creates a new table with the given name, number of rows and number
        of columns, and appends it by default to the end of the document
        body. The name must be unique within the document (the call is
        rejected if the name already exists). Returns the created table
        element if successful.

	Beware: Creating simple tables from scratch is very easy; however,
	for a realistic application, it's strongly recommended to replicate
	XML table templates previously created with an ODF-compatible editing
	software. A reasonably sophisticated table implies dozens of style
	definitions and would require a lot of perl code and a deep knowledge
	of the ODF specification, while it could be created in a few minutes
	through a WYSIWYG tool.

	'rows' and/or 'columns', if omitted, are replaced by the 'max_rows'
	and 'max_cols' properties of the document (see the properties below).

        By default, the table is set to fit the entire width between the
        left and right margins with equal sized columns, cells of type
        string and without borders or background colour.

        Possible options:

            'table-style'	=> table style
            'cell-type'		=> default cell type
            'cell-style'	=> default cell style
            'text-style'	=> default cell text style

        The first option is the name of a table style which defines
        certain global properties for the table (width, background colour,
        etc.). See the OpenOffice::OODoc::Styles manual for information about
	styles.

        The second option is the cells' default data type. The main types
        available are string, float, currency, date, percentage. Caution: to
        be properly treated as having a numeric format in OOo/ODF, a
        cell needs more than to be just marked 'numeric'. If the cell really
        needs to be treated properly as a number, you must also give it a
        cell style which itself refers to a number style. The cell-style
        parameter can do this. However, even though the OODoc::Styles module
        is there to otherwise help you create and add styles from a program,
        this type of exercise can become very labour-intensive. We therefore
        recommend using basic tables created in advance from document
        templates or style libraries created from an office application,
        rather than creating complex number tables from code.

        The text-style option selects the paragraph style applicable to the
        text displayed in each cell.

        Once the table is created, you can obviously modify each cell's type
        and style individually.

        Example:

            my $table = $doc->appendTable
            			(
            			"Rate", 22, 5,
            			'table-style' => 'Table1',
            			'text-style' => 'Text body'
            			);

=head3	appendTableRow(table)

        See appendRow.

=head3	autoSheetNormalizationOff()

	Deactivates the automatic sheet normalization.

	See autoSheetNormalizationOn().

=head3	autoSheetNormalizationOn('full')

=head3	autoSheetNormalizationOn(height, width)

	Activates the automatic normalization of any used table.
	This method instructs the API to automatically normalize anything
	table or sheet as soon as it's reached through getTable() or another
	table-related access method. The automatic normalization is not
	activated by default. It can be deactivated at any time using
	autoSheetNormalizationOff().

	See normalizeSheet() for details about the arguments and the
	effects.

=head3	bibliographyEntryContent(id [, key1 => value1, key2 => value2, ...])

	Gets, and optionally sets, the properties of a given (existing)
	bibliographic entry. The optionally updated properties are provides
	as a hash. The returned description is a hash.

	The first argument can be either the logical identifier of the entry
	(as it appears for the end-user) or a previously found bibliography
	entry element (see getBibliographyElements()).

	Example:

		my %desc = $doc->bibliographyEntryContent
					(
					"GEN99",
					author	=> 'Genicorp',
					pages	=> 62
					);

	This sequence updates the "Author" and "Pages" values of the "GEN99"
	entry, then returns all the content of the entry in %desc.

	Caution: Several bibliography entries can have the same identifier.
	This method processes one element at a time. In the example above,
	only the first occurrence of the "GEN99" entries is updated. So, if
	the user needs to ensure that all the entries with the same identifier
	have the same content, the appropriate code should be something like:

		my @entries = $doc->getBibliographyElements("^GEN99$");
		foreach my $entry (@entries)
			{
			$doc->bibliographyEntryContent
				(
				$entry,
				author	=> 'Genicorp',
				pages	=> 62
				)
			}

	Caution: This method allows the user to create any new property and
	to put any value in any property, without control. For information
	about the legal and/or recommended properties, see the OpenDocument
	specification and the OpenOffice.org bibliographic project
	(http://bibliographic.openoffice.org).

=head3	bookmarkElement(element, name [, offset])

	See setBookmark().

=head3	cellCurrency(table, row, column [, currency])

=head3	cellCurrency(cell [, currency])

	Get/set the currency unit of a cell.
	If a currency is provided, the cell value type is automatically
	switched to 'currency'.

=head3	cellFormula(table, row, column [, formula])

=head3	cellFormula(cell [, formula])

        Accessor which returns the formula (or function) contained in the
        given table cell. Returns undef if no formula is found in the cell.

        The cell address is the same as for getCellValue().

        If a formula is given as the last argument, it is put into the cell,
        overwriting any existing formula. No check of the syntax is carried
        out on the inserted formula. It is up to the application to insert a
        formula which conforms to OOo/ODF syntax. Example:

            $doc->cellFormula(1,3,2, "sum <C2:C5>");

        Note 1: inserting or replacing a formula does not directly modify
        the value or text of the cell. Proper interpretation of a formula
        does not happen until the fields are updated when the document is
        reloaded into the office software.

        Note 2: syntax and functionality of cell formulae differ greatly
        between office applications.

=head3	cellSpan(table, row, column [, hspan [, vspan]])

=head3	cellSpan(cell [, hspan [, vspan]])

	In a spreadsheet document, get/set the span of a table cell,
	knowing that this span can be one or more columns. The cell addressing
	is the same as with getTableCell().
	Example:

		$doc->cellSpan($table, "B4", 3);

	creates a 3-cell span from B4 in a spreadsheet.

	With only one span argument, this method works for horizontal, left to
	right expansion. With an additional argument, the expansion is bi-
	directional, covering one or more rows below the given cell. The
	horizontal span should be set to 1 in order to get a vertical span
	only.

	The text of the covered cells (if any) is concatenated to the original
	content of the expanded cell (as in OOo Writer or Calc).

	The user should make sure that the cell expansion will not invade the
	span of another, previously expanded cell. Assuming A is a the target
	of cellSpan(), B is an existing expanded cell, and C is a covered cell
	in the span of B, the following rules apply:

	If B is to be covered by the span of A, the span of B is automatically
	reset to 1, so C becomes visible, then B is covered by A. But if C is
	in the target range of cellSpan() while B is not, the method produces
	an inconsistency in the table (this inconsistency doesn't prevent
	OpenOffice.org and KSpread from loading the file but the span of A is
	just ignored).

	In list context, the method returns the horizontal span, then the
	vertical span. In scalar context, it returns the horizontal span only.

	Caution: when related to table cells, "span" has not the same
	meaning as when related to flat text (see getSpan() and setTextSpan()).

=head3	cellStyle(table, row, column [, stylename])

=head3	cellStyle(cell [, stylename])

	Get or set the style of a table cell.

=head3	cellValue(table, row, column [, value [, text]])

=head3	cellValue(cell [, value [, text]])

	Without the "value" argument: see getCellValue().

	With "value" (and, optionally, "text"): see updateCell().

=head3	cellValueType(table, row, column [, type])

=head3	cellValueType(cell [, type])

	Get/set the data type of a table cell.

	Possible value types are 'string', 'float', 'percentage', 'currency',
	'date', 'time', 'boolean'.

	Note: If an application must convert a 'string' cell to a numeric
	one and fill it with a numeric value, cellValueType() must be called
	*before* cellValue(). Ex:

		my $cell = $doc->getTableCell('Sheet1', 4, 8);
		$doc->cellValueType($cell, 'float');
		$doc->cellValue($cell, 12.34);

=head3  checkIndexMark(name, type [, context])

        Checks the existence and validity of an index mark (see setIndexMark()
        for details about range index marks). The mandatory argument are the
        index entry identifier and the index entry type (namely 'toc' or
        'alphabetical index'. A context element may provided in order to
        restrict the search context.
        
        This method may return 1, 0 or undef.
        
        '1' means that the index mark is present and consistent;
        
        '0' means that the index mark is present in the context but not valid;
        
        undef means that the index mark doesn't exist in the context.
        
        If the result is 0, the are 2 possible reasons: the start point or the
        end point of the index mark has been found, but not both, or both have
        been found but there relative positions are wrong (the end is located
        before the start). Whatever the explanation, this result means that some
        cleaning should be done (see deleteIndexMark()).

=head3  checkRangeBookmark(name [, context])

        Checks the existence and validity of a range bookmark (see setBookmark()
        for details about range bookmarks). The mandatory argument is the
        bookmark name. A context element may provided in order to restrict the
        search context.
        
        This method may return 1, 0 or undef.
        
        '1' means that the range bookmark is present and in the right order;
        
        '0' means that the bookmark is present in the context but not valid;
        
        undef means that the bookmark doesn't exist in the context.
        
        If the result is 0, the are 2 possible reasons: the start point or the
        end point of the range has been found, but not both, or both have been
        found but there relative positions are wrong (the end is located before
        the start). Whatever the explanation, this result means that some
        cleaning should be done (see deleteBookmark()).

=head3	columnStyle(column_element [, style])

=head3	columnStyle(table, column [, style])

        Returns the style name of the given column or replaces it with a new
        one. A column can be indicated either directly by reference or by
        the pair [table, column number]. The table itself can be indicated
        either by a table element, its number or its logical name. If the
        'style' argument is given, it replaces the old column style.

        Giving a column a style is actually the only way to control the
        width of a column in a table.

        Example:

            $doc->columnStyle('Table1', 2, 'NewStyle');

        Caution: columns are numbered beginning at 0.

=head3	copyRowToHeader(table, rownum)

=head3	copyRowToHeader(row)

	This method appends a copy of a given table row to the header of the
	table. It may be called repeatedly, allowing multi-row header
	creation.

	A table header is a row, or a sequence of rows, that is displayed at
	the top of a table and repeated at the top of every page if the table
	is spanned across more than one page.

	The given row remains in place unchanged; it's used as a template for
	the new header row.
	
=head3	createParagraph([text [, style]])

	Creates a free paragraph for later use. Unlike appendParagraph() or
	insertParagraph(), this method doesn't attach the new paragraph to
	the document.
	
	Without arguments, the paragraph is created empty. The first argument,
	if any, provides the text content of the paragraph. The second one,
	if any, is regarded as the style name; the default style is
	"Standard". 

=head3	createTextBox(options)

	Creates a new text box. Can apply to any document class, but mostly
	used in presentations or drawings (where text boxes are required to
	host text content).
	
	Text boxes are implemented through frame element, so you should see
	createFrame() in the OpenOffice::OODoc::XPath manual chapter in order
	to understand the meaning of every option.
	
	The following options are allowed (and generally required in order
	to make a text box really visible and properly rendered):
	
	page: the page where the box must be attached; in presentations or
	drawings, this option should be set with the page name;
	
	name: the (unique) name of the text box;
	
	size: the size of the box;
	
	position: the page-relative position;
	
	style: the graphic style of the box; like an image box, a text box
	often requires a style to be properly displayed;
	
	content: the content to be displayed in the box; if this option is
	set to a literal, the given content is inserted as a paragraph in
	the box; if the given value is the reference of an element, this
	element is attached as is in the box (so it's possible to insert
	any complex object, such as a table, an item list, etc).
	
	The method returns the reference of the new text box element.
	
	The example below creates an graphic style ("TB"), then a text box
	("The Box") which uses the new style. See O::O::Styles for comments
	about createStyle(). The text box is attached in a presentation page
	identified by its name ("AnyPageName"). The size (width then height)
	and position (x, y) options are provided in centimeters (other units
	are allowed), each one in a single string.

		$doc->createStyle
                	(
                	"TB",
                	family          => "graphic",
                	parent          => "objectwithshadow",
                	properties      =>
                        	{
                        	'style:vertical-pos'    => 'from-top',
                        	'style:horizontal-pos'  => 'from-left',
                        	'style:vertical-rel'    => 'page',
                        	'style:horizontal-rel'  => 'page'
                        	}
                	);
		$doc->createTextBox
                	(
                	page            => "AnyPageName",
                	name            => "The Box",
                	size            => '12cm, 4cm',
                	position        => '8cm, 14cm',
                	style           => 'TB',
                	content         => "The text in the box"
                	);
			
	In this example, the content option is set to a flat text, so
	it will be inserted as a standard paragraph. If we want to insert
	a paragraph with a non-default style, this option must be set to
	the reference of an existing paragraph (which may have been created
	using createParagraph() or copied from another place).

=head3	defaultOutputTerminator([chars])

	Get or set the default terminator character for text export.
	Example:

		$doc->defaultOutputTerminator("\n");

	After this instruction, a line-break will be appended at the end of
	every paragraph or header exported by getText(), selectTextContent()
	or other text extracting methods.

	To reverse this behaviour, the user can call this method with an
	empty string.

	Without argument, returns the currently selected terminator, if any.

=head3	deleteBookmark(name [, context])

	Deletes the bookmark owning the given name (if defined).
	A context optional argument is provided; if so, the bookmark is deleted
	only if it's located in the given context.

        If several bookmarks wrongly own the same name, they are removed.
        
        The method returns the number of physical deleted elements, i.e. 1 for
        a regular position bookmark, 2 for a range bookmark, 0 for nothing. Any
        other return value means that deleteBookmark() has cleaned up a strange
        situation (ex: more than one bookmark for a single name, a position
        bookmark with one start and many ends, and so on).
        
        Warning: if the context argument is set (or if the default current
        context is not the whole document), and if the bookmark to be deleted
        is not entirely included in the context, the result may be a partially
        deleted bookmark (wrong).
        
        See also deleteBookmarks().

=head3  deleteBookmarks([context])

        Delete all the bookmarks in the current context (by default the whole
        document) or in a given optional context, and returns the number of
        physical deleted elements (that may be greater than the number of
        deleted bookmarks, knowing that a bookmark may be stored a one or two
        XML elements).
       
        Warning: some inconsistencies may result if the context is not the whole
        document, knowing that a range bookmark could run across the border of
        the restricted context.
        
        See also deleteBookmark().

=head3	deleteColumn(table, col_num)

=head3	deleteColumn(col_elt)

	Deletes a given column in a given table.

	Caution: Before using this method, the application should ensure that
	the whole area from the beginning of the table to the last cell of the
	column to be deleted is "normalized". See normalizeSheet() for details
	about table normalization.

=head3	deleteHeading()

	See removeHeading().

=head3	deleteRow(table, row_num)

=head3	deleteRow(row_elt)

	Deletes a given row in a table.

=head3  deleteIndexMark(id [, type [, context]])

	Deletes the index mark owning the given identifier (if defined).
	The first argument (mandatory) is the index mark identifier. The second
	argument is the index type ('alphabetical index' or 'toc', the first one
	is the default).

	A context optional argument is provided; if so, the index entry is
	deleted only if it's located in the given context.

        If several index marks wrongly own the same identifier, they are
        removed.
        
        The method returns the number of physical deleted elements, that should
        be 0 (if the index mark did not exist) or 2 (the start and the end
        points). Any other return value means that deleteIndexMark() has cleaned
        up a strange situation (less or more than two range delimiters).
        
        See also deleteIndexMarks().

=head3  deleteIndexMarks([type [, context])

        Without argument, deletes all the TOC marks and alphabetical index marks
        in the document (or the default context).
        
        The first argument, if set, non-blank and non-empty, restricts the
        deletion to one type of index marks; it should be either 'toc' or
        'alphabetical index' (unless the user need to remove non standard index
        marks).
        
        A particular context may set through the third argument in order to
        restrict the index mark removal to the content of a particular element.
        
        See also deleteIndexMark().

=head3	drawPageId(page [, new_id])

	Returns the internal identifier of a presentation page, and changes
	it if a second argument is provided. The page id is a positive
	integer.

	The first argument must comply to the same rules as with getDrawPage.

=head3	drawPageName(page [, newname])

	Returns the visible name of a presentation or drawing page.
	The first argument can be a page order number, a page element or the
	present page name (see getDrawPage). The page is renamed if a
	second argument is provided. Example:

		$doc->drawPageName("oldname", "newname");

=head3	deleteTableColumn(table, col_num)

	See deleteColumn().

=head3	deleteTableRow(table, row_num)

	See deleteRow().

=head3	expandSheet()

	Synonym of expandTable().

=head3	expandTable(table, height, width)

	Increases the size of the given table or spreadsheet.

	This method silently executes a full normalization of the table before
	resizing it. See normalizeSheet() for details about this operation.

	This method is specially useful in order to ensure the availability of
	an appropriate workspace in a spreadsheet whose apparent size is
	almost unlimited through the GUI of a typical desktop software but
	but whose real size is unknown and/or doesn't include all the target
	area of the application.

	The vertical expansion is implemented by repetitive replication of the
	last row, while the horizontal expansion is implemented by repetitive
	replication of the last cell of the last row. So the new cells in the
	right side are copies of the old bottom-right cell, while the new rows
	are copies of the old last row.

	Any size argument which is not larger than the previous height or width
	is silently ignored, so method produces the same effect as
	normalizeSheet() with the "full" parameter.

	The return value is the table element itself in scalar context, or
	the table size in array context.

	Note that there is no direct method to shrink a table. However, it's
	possible to do the job by deleting selected rows and or columns
	through deleteTableColumn() and/or deleteTableRow().

=head3	extendText(element, text [, style [, offset]])

	Inserts the text provided as the second argument into the element
	specified by the first argument. The second argument may be either a
	flat string or another existing text element.
	
	If the 'text' argument is a paragraph or heading element, the text
	content (and not the element itself) is inserted. But if 'text' is
	any other element (for example: a variable text field or a sequence
	of spaces), its inserted as is.

	This method is an improvement of the general extendText() method
	which is documented in the OpenOffice::OODoc::XPath manual page.

	If a third argument is provided and is neither 0 nor an empty string,
	it's regarded as the desired style of the new text, which is inserted
	as a "styled span" (see setTextSpan() for details about text "spans").
	By default, the text is inserted without any special style (i.e. with
	the same style as the containing element).

	The new text is, by default, appended to the existing content of the
	element. However, if a valid numeric value is provided as the fourth
	argument, the new text is inserted within the existing content, at the
	given offset. If the offset is negative, it's counted backwards from
	the end of the string. If it's set to 0, the insertion takes place at
	the beginning.

		$doc->createStyle
			(
			"BlueYellow",
			family		=> "text",
			properties	=>
			    {
			    "fo:color"			=> odfColor("blue"),
			    "fo:background-color"	=> odfColor("yellow")
			    }
			);
		my $p = $doc->getParagraph(4);
		$doc->extendText($p, "New text", "BlueYellow", 5);

	In the example above, "New text" is inserted at the offset 5 within
	the 5th paragraph, in blue letters on a yellow background.

	Of course, the offset argument can't be passed unless the style one is
	present. However, in order to pass an offset without setting a style,
	the application has just to provide a 0 or an empty string as the
	third argument. Example:

		$doc->extendText($p, "New text", "", 5);
	
	Caution: the use of extendText() with the style and offset optional
	arguments is allowed for some simple situations; however, there are
	more powerful methods to insert additional text, with or without a
	particular style, within en existing element. See updatetext() and
	setTextSpan().

=head3	getBibliographyElements([id])

	Returns the list of the bibliographic entry elements contained in the
	document.

	If an argument is provided, the returned list is restricted to the
	bibliographic entries matching it (this argument can be a regexp).

	Example:

		my @biblio = $doc->getBibliographyElements("^W3C");

	returns the bibliographic entries where the identifier begins with
	"W3C".

=head3	getBookmark(name)

	Returns the bookmark element (if defined) corresponding to the given
	bookmark name.

	If the bookmark covers a range of text (i.e. if it's not a position),
	the returned element is the "bookmark start" one.

=head3	getCell()

	Synonym of getTableCell().


=head3	getCellParagraph(table, row, column)

=head3	getCellParagraph(cell)

	Returns the paragraph element contained in a given table cell, if
	the cell contains a paragraph. If the cell contains more than one
	paragraph, returns the first one.

=head3	getCellParagraphs(table, row, column)

=head3	getCellParagraphs(cell)

	Returns the list of the paragraph elements contained in a given
	table cell (knowing that a single cell can contain one or more
	paragraphs).

=head3	getCellPosition(cell)

	Returns an array corresponding to the zero-based, numeric coordinates
	of a table cell in a document, which can be used later to retrieve
	a cell at the same location through getCell(). The return values
	represent, in this order, the table, the row and the column. The header
	rows of the table, if any, are not counted.

	Example:

		my @coord = $doc->getCellPosition($cell);

	A triplet such as (2, 4, 9) tells that the cell is located at the
	10th position in the 5th row of the 3rd table of the document.

	In scalar context, this method returns nothing more than the first
	element of the triplet, i.e. the zero-based position of the table
	in the order of the document. However, if the real need is to retrieve
	the table element itself, $cell->parent->parent is more efficient.

	This method produces a warning and returns undef if the argument is
	not a table cell.

	Caution: getCellPostion(), like any other accessor using object
	coordinates related, works only with normalized tables.

=head3	getCellValue(table, row, column)

=head3	getCellValue(cell)

        Returns the value of a table cell, if the cell is defined and
	uncovered. Caution, in order to get the cell element itself for
	further processing, use getCell() instead.

        The first form indicates a cell by its 3D coordinates, as with
        getCell().

        The second form (quicker) takes a cell element as its only argument
        (e.g. as returned by a previous getCell call).

        This method behaves in two different ways depending on the cell
        type. The displayable text of the cell is regarded as the cell value
	if the cell type is 'string'. If the cell type is one of the possible
	numeric types ('float', 'currency', 'date'), the returned value is the
	internal, numeric value.

        This difference in handling is designed to allow programs to use
        returned numeric values directly in calculations.

	See also cellValueType().

        Note: To get information about a cell other than its value or value
	type (numeric, etc.), the best way is first to get its element
	reference with getCell() and then use it with getAttribute.

=head3	getChapterContent(heading [, options])

	This method returns the list of the elements depending (from the
	end-user's point of view) on a given heading element, not including
	the heading element itself. The argument and the options are the
	same as with getHeading().

	Examples:

		my @list = $doc->getChapterContent(2, level => 3);
		foreach my $element (@list)
			{
			my $text = $doc->getText($element);
			print "$text\n";
			}

	The code above selects and prints all the text elements below the
	third level 3 heading of the document (not including the content of
	the header itself. The following example creates a new section whose
	content is made of a heading and the content of the depending chapter
	(the heading text is used as the section name):
	
		my $heading = $doc->getHeading(2, level => 3);
		my $heading_text = $doc->getFlatText($heading);
		my $section = $doc->appendSection($heading_text);
		my @content = $doc->getChapterBodyElements($heading);
		$doc->moveElementsToSection($section, $heading, @content);

	(See appendSection(), getHeading(), moveElementsToSection() in the
	present manual chapter, and getFlatText() in OpenOffice::OODoc::XPath)
		
	Caution, this method returns a list of elements and not an element.
	Chapters, unlike sections, are not defined in OpenDocument. So,
	getChapterContent() should be used as a possible workaround in order
	to isolate a logical set of content elements which is not packaged in
	a section.

=head3	getColumn(table, column)

        Returns the element reference of the given column in the given
        table. The first argument is either the table's sequential number in
        the document, logical name or element reference. The second argument
        is the column's number in the table. Synonym: getTableColumn.

	Caution: The application should ensure that the area including the
	needed column is "normalized". See normalizeSheet() for details about
	table normalization.

=head3	getDrawPage(pos/name)

	For presentation and drawing documents.

	Returns the element reference of the given page name or position.

	If the argument contains an integer, the page is selected according to
	its zero-based position. If the value is negative, the position is
	counted backwards from the end.

	If the argument is alphanumeric, it's regarded as a page name, and the
	page is selected accordingly.

	Caution: This method can't retrieve a page by name if the name
	contains numeric characters only; selectDrawPageByName() should be
	preferred to do so.

=head3	getEndnoteCitationList()

 	Returns the list of all the endnote citations (i.e. references to
        footnotes included in the text) contained in the document.

=head3	getEndnoteList()

        Returns the list of all the endnote body elements contained in the
        document. Should be replaced by getNoteList() with the "class" option
	set to "endnote".

=head3	getFootnoteCitationList()

 	Returns the list of all the footnote citations (i.e. references to
        footnotes included in the text) contained in the document.

=head3	getFootnoteList()

        Returns the list of all the footnote body elements contained in the
        document. Should be replaced by getNoteList() with the "class" option
	set to "footnote".

=head3	getHeading(n [, options])

        Returns the nth+1 heading element.

        If n is negative, headings are counted backwards from the last.
        getHeader(-1) returns the last heading element of the document.

	The only one possible option is "level". It allows the application
	to select the nth+1 heading element for a given level.

	Example:

		my $heading = $doc->getHeading(2, level => 3);

	selects the third level 3 heading in the whole document.

	See also getChapterContent().

        Caution: without the "level" option, this method counts sequentially
	through all headings along a single plane, irrespective of their
	level. E.g. if you have a level 1 heading then two level 2 headings
	then a level 1 heading, the call getHeading(3) returns the last
	level 1 heading.

=head3	getHeadingList([level => value])

        Returns a list of heading elements (i.e. elements called 'text:h' in
        the document body).

	If the "level" option is provided, the list is restricted to the
	headings having the given level.

=head3	getHeaderRow(table [, row_number])

	See getTableHeaderRow().

=head3	getHeadingText(n)

        Returns the text of the nth+1 heading element. Elements are counted
        in the same way as for getHeading().

=head3	getHeadingTextList()

        Returns a list of document heading texts.

        In a list context, the result is returned in the form of a list of
        character strings. In a scalar context, the result is a single
        string in which the headings are separated by a line-break character
        ("\n").

        Note: This list is "flat". It contains no information about the
        headings' hierarchy. To get a hierarchical contents list, you must
        start with the list of headings obtained using getHeadingList and
        check each element's level attribute ('text:level').

=head3	getItemElementList(list)

        Returns a list of elements which represent items of an ordered or
        unordered list. The argument is a "list" element (obtained
        previously e.g. using getItemList, getOrderedList or
	getUnorderedList). Each element in this list can be used with item
	handling methods.

=head3	getItemList(n)

	Returns the element which represents the nth+1 list in a document
	if found.

	WARNING: In the OpenOffice.org 1 documents, only "ordered lists" and
	"unordered lists" can be present. In the Open Document format, there
	are generic list objects only, and each one is made "ordered" or
	"unordered" by its style. So, this method will never return anything
	from an OOo 1 document.

=head3	getLevel(element)

	See getOutlineLevel().

=head3	getList(n)

	See getItemList().

=head3	getListItem(list, n)

	Returns the nth+1 item in a given list if found.

	The list (1st argument) may be given either by its order number in
	the document, or directly as an element reference.

=head3	getNoteCitationList()

	For OpenDocument only (doesn't work on old OpenOffice.org documents).

	Returns the list of all the note citation elements (whatever their
	note class, i.e. "endnote" or "footnote").

=head3	getNoteClass(note_element)

	Returns the class of the given note element. Possible values are
	presently "endnote" and "footnote". Returns undef unless the given
	element is a note.

=head3	getNoteElement(class => $note_class, citation => $note_citation)

	Returns the first note element matching the given class and citation,
	if any. Returns undef if the target note element doesn't exist.

	The "class" parameter is either "endnote" or "footnote".

	The "citation" parameter is the numeric or literal which refers to
	the note, as it's visible for the end user.

	Caution: The uniqueness of a note citation in a given note class is
	not a general rule. The citation is an identifier when it belongs to
	an ordered sequence (such as 1, 2, 3... or "i", "ii", "iii"...). But
	the author is allowed to use the same citation (ex: an asterisk) for
	more than one footnote or endnote. In such a situation, the method
	returns the first note matching the given citation and the given
	class. As a consequence, the note identifier, if known, is a better
	option (see the second form of getNoteElement()).

=head3	getNoteElement(id => $note_identifier)

	Returns the note element matching the given internal note identifier
	(which is a "text:id" attribute according to the ODF specification).

	This internal identifier is unique, whatever the note class, so the
	"class" parameter is not needed. However, "class" may be provided as
	an additional filter; if so, the method will return undef if the
	element matching the identifier doesn't match the class.

=head3	getNoteElementList()

	Returns the list of the endnote and footnote main elements.

=head3	getNoteList()

	Returns the list of the endnote and footnote body elements.

=head3	getOrderedList(n)

        Returns the element which represents the nth+1 ordered list in a
        document if found.

	WARNING: Ordered lists are possible in the OpenOffice.org 1 format
	only. Don't use it against OpenDocument.

=head3	getOutlineLevel(element)

	Returns the level number of a text element, or undef if the given
	element don't have a level number. Every heading element should have
	a level, while ordinary text body elements should not. Example:

		my $level = $doc->getOutlineLevel($element);
		if ($level)
			{
			print "There is a level $level heading\n";
			}
		else
			{
			print "Non-heading element\n";
			}

=head3	getParagraph(n)

        Returns the nth+1 paragraph in the document body, or undef if the
        given number is greater than or equal to the total number of
        paragraphs in the document.

        You can also pass a negative argument, in which case paragraphs are
        counted backwards from the end (-1 being the last paragraph).

        By paragraphs we mean 'text:p' elements, which excludes headers but
        includes non-empty table cells, contents of list items and
        footnotes.

        Returned value is an element and not the text of the paragraph. All
        read/write operations involving attributes and content can use this
        element.

=head3	getParagraphList()

        Returns a list of paragraph elements (i.e. 'text:p' elements in the
        document body).

=head3	getParagraphText(n)

        Returns the text of the nth+1 paragraph, counted using the same
        rules as for getParagraph.

=head3	getParagraphTextList([filter])

        Returns a list of texts contained in the paragraphs of a document
        ('text:p' elements).

        A filter can be passed as an optional argument (literal or regular
        expression). In this case, only paragraph texts whose content match
        the filter are returned.

        In a list context, the result is returned in the form of a list of
        character strings. In a scalar context, the result is a single
        string in which the paragraphs are separated by a line-feed
        character ("\n").

=head3	getRow(table, row_num)

        Returns the element reference which corresponds to a row in a table.
        The first argument is either the table's sequential number in the
        document, logical name or element reference. The second argument is
        the row number in the table. Synonym: getTableRow.

	This methods ignores the table header (if any). It can retrieve a
	row in the table body only. See getTableHeaderRow().

=head3	getRowCells(table, row)

=head3	getRowCells(row)

	Returns the list of the uncovered cell elements corresponding to a
	given table row. The row can be provided either by table ID and row
	number or by direct row object.

=head3	getSection(name/number)

        If the first argument is a number, returns the nth+1 section in a
	document (section numbers are zero-based; if the argument is negative,
	the sections are counted from the end).

        The second form allows you to select a section by its logical name (as
        it would appear to the end user when editing the section's
        properties). This name is obviously easier to use than a number.
        Moreover, this type of selection means the application will still
        work even if a section changes position within a document.

	The returned object is a "handle" that can be used for subsequent
	element creations or retrievals in the selected section.

=head3	getSpanList([context])

        Returns a list of elements, in the given context, which correspond
	to texts which "stand out" from the regular flat text, i.e. which have
	been given a style which makes them stand out from the rest of the
	paragraph containing them. The context may be a paragraph, a section,
	or any other text container. The context argument is optional; the
	default context is the whole document.

        For example, a word in italics or in font size 12 in a paragraph of
        mostly standard characters in font size 10 is a 'span' element and
        would therefore appear in a list returned by getSpanList().

=head3	getSpanTextList([filter])

        Gets a list of texts which "stand out" in the same way as
        getSpanList() and returns it under the same conditions as
        getParagraphTextList() or getHeadingTextList(), with optional filter.

=head3	getStyle(path, position)

=head3	getStyle(element)

        Obsolete. See textStyle().

=head3	getTable(number_or_name [, 'normalize'])

=head3	getTable(number_or_name [, length, width])

	Returns the reference of a table, selected by name or number, in a
	scalar context. In an array context, returns the table size, like
	getTableSize().

	This method works with spreadsheets as well as with tables included
	in other documents.

	If the first argument is a number, returns the nth+1 table in a
	document (table numbers are zero-based; if the argument is negative,
	the tables are counted from the end). If it's a string, the table is
	selected by its its logical name (as it would appear to the end user
	when editing the table's properties). This name is obviously easier
	to use than a number. Moreover, this type of selection means the
	application will still work even if a table changes position within
	a document. But the retrieval by name works with two restrictions:

	- if a table name is made of digits only, or if if represents a
	numeric expression, it's automatically regarded as a table number and
	the table is selected according to its sequential (zero-based)
	position in the document; if (and only if) the given number is greater
	than the position of the last table, the given argument is regarded as
	a name (for example, if the document contains 3 tables, getTable(365)
	will attempt to retrieve a table whose name is "365"); in order to
	avoid any retrieval by number, use getTableByName();

	- getTable() can't retrieve a table by name if the name contains
	one or more "$", "{" or "}" characters; these characters are allowed
	in the table names in text documents (ODT), but not allowed
	in spreadsheets (ODS).

	The returned object is a "handle" that can be used for subsequent
	accesses to its components (rows, cells).

	The additional arguments, if any, instruct OODoc to normalize they
	target table in order to allow subsequent addressing of its content.
	If the "normalize" keyword is provided, the table will be fully
	normalized. If length and width arguments are provided instead,
	only an accordingly limited area, beginning at the "A1" position.
	Practically, getTable() uses normalizeSheet() in order to perform
	this job, so you should have a look at the normalizeSheet()
	documentation (in the same chapter) for explanations.

	Examples:

		my $sheet = $doc->getTable('Checklist');

	returns the reference of the sheet (or table) corresponding to the
	given name, without processing

		my $first_sheet = $doc->getTable(0);
		my $last_sheet = $doc->getTable(-1);

	returns the references of the first and the last tables according to
	the physical order of the document

		($lines, $columns) = $doc->getTable('Friends', 'normalize');

	fully normalizes the table whose title is "Friends" and returns itself	
	size.

=head3	getTableByName(name [, 'normalize'])

=head3	getTableByName(name [, length, width])

	Retrieves a table according to its name (if it exists). This methods
	allows the retrieval of a table whose name is made of digits without
	possible confusion between names and numeric positions.

	The optional arguments and the limits are the same as for getTable().

=head3	getTableCell(table, row, column)

=head3	getTableCell(table, coord)

=head3	getTableCell(row, column)

        Returns the element which represents the given cell. Possible
        arguments are respectively: the table number or its reference in the
        document, row number and column number. Each table cell contained in
        the body of an OOo/ODF document can be referenced in this
        manner, as if it belonged to a single 3D table irrespective of the
        rest of the document.

	If the cell is defined in the spreadsheet but covered (because of a
	cell merge), the return value is undef. In other words, this method
	doesn't provide access to a covered cell.

        The first argument can be either the sequential number of the table
        (starting at 0), the logical name of the table, or a 'table' object
	(which can be retrieved in advance using getTable). If it's a number
	or a name, getTable() is automatically called by getTableCell() in
	order to convert it in a 'table' object. However, if the first
	argument is a row object (previously obtained via getRow() or
	getHeaderRow()), the second one is processed as the column number.
	Before using several cells in the same row, it's a good idea to get
	the row object and then to use it in every cell selection, in order
	to minimize the coordinates calculation.

	In tables including one or more header rows, the best way to get a
	header cell is to use a header row (previously obtained using
	getHeaderRow()) as the first argument. If the first argument is a
	table, getCell() looks in the table body only.

	Alternatively, the user can provide the cell coordinates in a single
	alphanumeric argument, beginning with one or two letters and ending
	with one or more decimal digits, according to the same logic as in a
	spreadsheet. So, for example

		$doc->getTableCell($table, 'B12');

	is equivalent to

		$doc->getTableCell($table, 11, 1);

	(Remember that, with the numeric coordinates, the row number is the
	first argument, while with the alphanumeric, spreadsheet-like ones,
	the column letter(s) come first.)

        Numbers can also be negative, where position -1 is the last. For
        example:

            $cell = $doc->getCell(-1, -1, -1);

        returns the very bottom right cell of the very last table in the
        document $doc.

        Returns a null value if the given cell does not exist or if it's
	covered by the span of another cell.

	Any cellXXX() method in this module uses the same cell addressing
	logic as getTableCell().

        CAUTION: Remember that OODoc works with the XML representation of
	the tables, and not with the tables themselves. The [x,y] direct
	addressing feature works as long as there is a continuous, one-to-one
	mapping between the logical view and the physical XML storage of the
	table. But, according to the OpenDocument specification, several
	contiguous objects (cells or rows) are allowed to be mapped to a
	single XML object when they have the same content and the same
	style, in order to save some storage space. This optimization is
	systematically used, for example, by OpenOffice.org Calc. In addition,
	OODoc can't address a cell that could be displayed through the GUI
	of a typical interactive spreadsheet software but that isn't stored
	because it's not initialized yet. As a consequence, the direct
	addressing logic of getTableCell() may require some preprocessing.
	See normalizeSheet() and/or expandTable() about such preprocessing.

	Remember that the table addressing is zero-based and
	the row comes before the column in OpenOffice::OODoc, so, for
	example:

		$cell1 = $doc->getTableCell($table, 0, 0);
		$cell2 = $doc->getTableCell($table, 31, 25);

	returns respectively the A1 and Z32 cells.

	Note: in a spreadsheet, (0,0) are the coordinates of the "A1" cell,
	and, for example, (16, 25) are the coordinates of the "Z17" cell.


=head3	getTableColumn(table, column)

        See getColumn.

=head3	getTableHeaderRow(table [, row_num])

	Returns the element reference which corresponds to a row in a table
	header, or undef if the given table has no header row.

	The arguments are processes in the same way as with getRow(), but
	the second argument is optional; it's required only if the table
	has more than one header row (the 1st header row is returned by
	default).

	The returned elements can be used with subsequent cell access methods
	in order to process header cells (see getTableCell()).

=head3	getTableList()

        Returns a list of table elements in a document.

=head3	getTableRow(table, row)

        See getRow.

=head3	getTableRows(table)

	Returns the list of the rows contained in the given table.

	When the user needs to process every row in large tables, this method
	allows some performance improvements, because it's less costly than
	a lot of successive getRow() calls.

=head3	getTableSize(table)

        Returns the size of a table as a pair of values which represent the
        number of rows and columns. The table can be specified either by
        number, logical name or reference.

        Example:

            my ($rows, $columns) = $doc->getTableSize("Table1");

=head3	getTableText(n)

        Returns the content of a table, if found, whose number or reference
        is given as an argument. If not found, returns undef.

        The content of each cell is extracted according to the rules of
        getCellValue.

        In a list context, the returned value is a 2D table with each
        element containing the corresponding cell in the document.

        In a scalar context, the content is returned as a single string in
        CSV format. In this case, the rows are separated by a delimiter set
        by the instance variable 'line_separator' and the fields by the
        variable 'field_separator' in the OODoc::Text object. (These
        delimiters are by default "\n" and ";" respectively.)

=head3	getText(path, position)

=head3	getText(element)

        Exports the text contained in the given element according to the
        means appropriate to that type of element.

        If the 'use_delimiters' flag is set to 'on' (default), the content
	of each element (others than ordinary paragraphs, table cell,
	headers) is preceded and/or followed by a character string depending
	on the type of the element. This also depends on the settings given
	to the delimiter values 'begin' and 'end' by the 'delimiters' hash.
	In a default configuration where the application has not provided
	any specific delimiters, the following delimiters are used:

            - '<<' before and '>>' after sections of text highlighted within
            an element (e.g. words in bold or underlined within a paragraph
            of 'standard' font characters).

        footnote citations (in text body) are placed between square
        brackets.

        '{NOTE:' and '}' for the content of footnotes.

	(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.)

        An application can change these delimiters, add more for other types
        of elements (e.g. paragraphs, headers, tables cells, etc.), or
        deactivate them using outputDelimitersOff. This depends on where the
        text is exported to e.g. display in editable "flat" format,
        conversion to non-OpenDocument XML or a markup language other than
        XML, generating code from text, etc..

	A default export (ex: "\n") terminator can be set for any element that
	is not listed in the 'delimiters' hash (see defaultOutputTerminator()
	above).

        If the element is an ordered or unordered list, the text produced is
        a concatenation of all the lines in the list, each separated by a
        line-break in addition to any delimiters. The default line break
	character is "\n", but it can be set to any other string (including
	an empty string) through the 'line_separator' property of the document
	object.

        If the element is a string table cell, getText behaves like
	getCellValue. If the cell contains more than one paragraph, the text
	produced is a concatenation of all the paragraph contents, each
	separated in the same way as list items.

        If the element is a table, getText behaves like getTableText.

=head3	getTextBoxElement(name/number)

	Retrieves a text box element by its unique name or by its order
	number in the document (or in the current context).
	
=head3	getTextContent()

        Returns the text of a document, as "flat" editable text.

        In a list context, the content is returned as a table with one text
        element (header or paragraph) per element.

        In a scalar context, the content is returned as a single character
        string with each text unit (header or paragraph) separated by a
        line-feed ("\n").

        The returned text contains no style or level information, so there
        is nothing to distinguish a header from a paragraph.

        Same as selectTextContent('.*').

=head3	getTextElementList([context])

        Returns the list of all the text elements, including headers,
        paragraphs and item lists, that directly belong to an optional given
        context. Without context argument, the default context is the document
        body.

=head3	getTopParagraph(n)

        Same as getParagraph but only considers top level paragraphs. The
        contents of lists, tables and footnotes are excluded.

=head3	getUnorderedList(n)

        Returns the element which represents the nth+1 unordered list in a
        document, if found.

	WARNING: Ordered lists are possible in the OpenOffice.org 1 format
	only. Don't use it against OpenDocument.

=head3	hyperlinkURL(hyperlink [, url])

	Get/set the URL of an hyperlink element. The first argument may be
	a previously retrieved hyperlink element (see selectHyperlinkElement
	below), or the URL of an existing hyperlink. If a second argument is
	provided, it replaces the URL of the hyperlink element.

	With only one argument, just returns the existing URL of the link,
	or undef if the first argument doesn't match an existing hyperlink
	element.

=head3	inputTextConversion(text)

	Returns the UTF8 conversion of the given text, supposed to be in
	the local character set of the document (see the 'local_encoding'
	property).

=head3	insertColumn(table, col_num [, options])

	Inserts a new column in an existing table at a given position.

	The second argument must be the number of an existing column.
	Caution: this argument must be a column number, and not a column
	element.

	The new column is created as a copy of the column a the given
	position. It's inserted before or after the existing one, according
	to an optional "position" parameter (default 'before').

	Caution: before using insertColumn() against a spreadsheet, the
	application should ensure that the whole rectangular area from the top
	left cell ("A1") to the last used cell of the column at the target
	position is "normalized" (see normalizeSheet() for details about the
	table normalization).

=head3	insertDrawPage(page/pos [, options])

	In a presentation or drawing document, inserts a new page before
	or after an existing page.

	Possible options are the same as for appendDrawPage(), with an
	additional one:

		position	=> 'before' or 'after' (default 'before')

	The new page is inserted before or after the reference page, according
	to the 'position' option.

	The first argument can be a draw page element reference (recommended)
	previously returned, for example, by a previous page retrieval or
	creation method call. Alternatively, it can be a page position or
	visible name, so it's regarded in the same way as in getDrawPage().

	Returns the new page element, or undef in case of failure.

=head3	insertHeading(path, position, options)

=head3	insertHeading(element, options)

        Same as appendHeading, but inserts the new heading before or after
	another element.

        Position is that of an existing element which can be another heading
        or a paragraph. Can be given by [path, position] or by element
        reference.

        Possible options are the same as for appendHeading, with the
        additional option 'position' which determines if the heading is
        inserted before or after the element at the given position. Possible
        values for this option are 'before' and 'after'. By default, the new
        element is inserted before the given element.

=head3	insertItemList(path, position [, options])

=head3	insertItemList(element [, options])

        Same as appendItemList, but a new list is inserted at the given
        position. The point of insertion can be given either by the pair
        [path, position] or by element reference. Options are the same as
        for insertParagraph.

=head3	insertParagraph(path, position [, options])

=head3	insertParagraph(element [, options])

        Same as appendParagraph, but a new paragraph is inserted at the
        given position.

        Position is that of an existing element which can be another
        paragraph or a header. Can be given by [path, position] or by
        element reference.

        Options are the same as for appendParagraph, with the additional
        option 'position' which determines whether the paragraph is inserted
        before or after the element at the given position. Possible values
        for this options are 'before' and 'after'. By default, the element
        is inserted before the given element.

=head3	insertRow(table, row [, options])

=head3	insertRow(row_element [, options])

        Inserts a new row into a table. In its first form, pass the table
        (reference, logical name or number) and the position number in the
        table. In its second form, pass the element reference of the
        existing row which is directly before or after the position where
        you want to make the insertion.

        By default, the new row is inserted at the position of the
        referenced row, which displaces it and the rest of the table down by
        one row position. However, you can insert it after by using the
        'position => after' option. By default, the new row is an exact copy
        of the referenced row, but you can assign particular attributes to
        it in the same manner as the insertElement method of OODoc::XPath.

=head3	insertSection(path, position, name [, options])

=head3	insertSection(element, name [, options])

	Creates a new section and inserts it immediately before or after
	an existing element (paragraph, header, table). The referenced element
        can be indicated as in insertParagraph.

	There is a "position" option which works in the same way as with
	insertParagraph() or insertRow().

	For other options, see appendSection(). For example, insertSection()
	may be used in order to insert a subdocument in a master document.

=head3	insertString(path, position, text, offset)

=head3	insertString(element, text, offset)

	Inserts a flat character string in a given element (whatever the type
	of element) at the given offset. If the offset is not defined, the
	text is appended to the end of the element (however, if the offset is
	provided and set to zero, the string is inserted at the beginning).

=head3	insertTable(path, position, name, rows, columns [, options])

=head3	insertTable(element, name, rows, columns [, options])

        Creates a new table and inserts it immediately before or after
        another element (paragraph, header, table). The referenced element
        can be indicated as in insertParagraph. The other arguments and
        options are the same as for appendTable with the additional option
        'position' as in insertParagraph.

=head3	insertTableColumn(table, col_num [, options])

	See insertColumn().

=head3	insertTableRow(table, row [, options])

=head3	insertTableRow(row_element [, options])

        See insertRow().

=head3	lockSection(section [, key])

	Installs a write protection on the given section.

	If a second argument is provided, it's stored as an encrypted key
	which is associated to the write protection. Caution, it's not the
	key as it should be typed by the OOo end-user.

	Such a write protection works only when the document is edited through
	an OpenOffice.org-compatible desktop software. It doesn't prevent the
	programs using OpenOffice::OODoc from deleting or updating the
	protected sections.

=head3	makeHeading([options])

	Creates a new heading element, or marks as a heading an existing
	element.

	Options:

		element		=> an arbitrary existing element

	If this option is provided, the given element is converted in place
	to a heading, whatever its original type and position. No element
	is created.

	Without the 'element' option, a new heading element is created and
	returned for later use. This element is free; it's not automatically
	attached somewhere in the document. For direct heading creation and
	attachment, you should prefer appendHeading() or insertHeading().

		level		=> a numeric, positive integer value

	Sets the hierarchical level of the heading (remember 1 is the top
	heading level). Caution: no default value.

		style		=> the name of a convenient heading style

	While it's not mandatory, the 'style' option and a properly defined
	heading style are generally required in order to allow the office
	software to really process and display the element as a heading with
	the right hierarchical level. Of course, any previously existing
	hierarchical style is reusable here.

	The main purpose of this method is to allow quick heading hierarchy
	creation in a "flat" document. For exemple, an application can select
	a set of flat paragraphs matching a given condition and convert each
	one in place to a heading with a given level.
	
=head3	moveElementsToSection(section, list)

	Moves a list of elements from any place to a section.
	
	The section may be passed by name or by element reference; it must be
	an existing one (no new section is created).
	
	The list is a set of arbitrary elements (including sections). Each one
	is cut from its previous place and appended to the section in the
	order of the list, without document consistency check.

=head3	normalizeSheet(sheet, rows, columns)

=head3	normalizeSheet(sheet, 'full')

	This method preprocesses a given sheet so its components (rows,
	cells) become available for all the table-oriented methods described
	in this chapter. In some situations, this method must be used before
	any attempt to address any individual table component (column, row or
	cell). The return value is the target table object in a scalar context
	and the size (height, width) in an array context.

	This method works with any kind of ODF tables, whatever the containing
	document, and not only with spreadsheets.

	In the first form, the 2nd and 3rd arguments define the size of a
	rectangular area, beginning at the first cell ([0, 0] or "A1"), to
	be processed, in order to save time and CPU resources when the
	application needs to address objects only in the first corner of a huge
	table.

	The second form allows the OODoc to normalize the whole table,
	whatever the size. It's certainly the preferred form, as long as
	the target sheets are reasonably sized or the hardware is powerful
	enough.

	The processed area becomes a workspace which is safely
	addressable by any cell/row/column processing method. This
	preprocessing is sometimes required, sometimes not. For example,
	it's required on present OpenOffice.org Calc spreadsheets, and
	useless on present OpenOffice.org Text tables.

	It's automatically executed when getTable() is called with size
	arguments (or with the "normalize" option); therefore it's not always
	explicitly invoked by the applications. However, it's useful to know
	its purpose.

	The object addressing logic (which, for example, allows a program to
	directly reach a cell using its coordinates) relies on a continuous,
	regular mapping between the user's view and the physical XML storage
	of the tables. However, the OpenDocument specification allows any
	conforming application to map more than one table element to a
	single XML element. When two or more contiguous objects contain
	the same value and have the same style and the same data type, they
	*may* be mapped to a single XML element with a repetition attribute.
	As a consequence, the position of the appropriate XML element can't be
	directly calculated from the logical coordinates of the object, and
	OODoc needs to scan the table in order to get all the repetition
	attributes and calculate the real mapping. In addition, updating an
	object whose the XML corresponding element has a repetition attribute
	would automatically update all the objects mapped to the same element,
	producing unpredictable and generally wrong results.

	OpenOffice.org Calc systematically uses this storage optimization in
	spreadsheets, while OpenOffice.org Writer doesn't use it for tables in
	text documents. In Calc (sxc/ods) documents, the XML mapping of the
	whole content is "denormalized" in order to save memory: several table
	components can be mapped to a single XML element, so the XML address
	of each one can't be simply calculated from its logical coordinates.

	In order to allow the spreadsheet components to be addressed with the
	same methods as the Writer table components, normalizeSheet()
	reorganizes the XML mapping of the given sheet.

	Caution: The OpenDocument specification doesn't make any difference
	about this point between tables included in text documents and tables
	in spreadsheet-only documents. So any ODF-compliant application
	*could* denormalize the XML storage of any table and use the
	repetition attributes. As a consequence, normalizeSheet() *could* be
	required in the future for other documents than OOo Calc ones.

	This method is not (presently) always needed for tables included
	in OpenOffice.org Writer (odt/sxw) documents, because their storage is
	"normalized" (i.e. each component is mapped to an exclusive XML
	element), with the exception of the column objects. So,
	normalizeSheet() is required with these tables when the application
	needs to use a column-focused method such as getColumn(),
	insertColumn() or deleteColumn().

	In the other hand, normalizeSheet() is not required to address a sheet
	which has been created through the OODoc methods (provided that the
	document has not been edited with another application software in the
	meantime). These methods, i.e. appendTable() and insertTable(), create
	normalized tables, whatever the document class.

	Because this method is time and memory consuming, it should never
	be used to reorganize the largest possible area of a sheet (meaning
	thousands of rows and hundreds of columns that will probably never be
	used). So it's action is limited to a given area, controlled by the
	rows, columns arguments. When these arguments are not provided, the
	method uses the 'max_rows' and 'max_cols' properties instead (see the
	Properties section for other explanations). The processed area should
	be sized in order to cover all the cells to be reached by the program,
	and nothing more.

	The first argument can be either the logical name of the sheet (as
	it's shown in the bottom tab by OOo Calc), the sheet number, or a
	table object reference, previously returned by getTable(). The return
	value is the table object (or undef in case of failure).

	Example:

		$doc = odfDocument(file => 'report.ods');
		my $sheet = $doc->normalizeSheet('Sheet1', 7, 9);
		my $result = $doc->cellValue($sheet, 5, 6);

	In the sequence above, a top left area of 7 rows by 8 columns is
	pre-processed, so the cells from A1 to H6 of this sheet can be
	reached according to the same addressing scheme as in Writer tables.
	The last instruction gets the content of G6. Note that the second line
	of this example could be replaced by

		my sheet = $doc->getTable('Sheet1', 7, 9);

	knowing that, when called with size arguments, getTable() automatically
	executes normalizeSheet().

	The following code normalizes the whole table, whatever its size (but
	I don't recommend this option for tables containing thousands of rows
	by hundred of columns):

		$doc->normalizeSheet('Sheet1', 'full');

	This last instruction could be automatically and silently executed
	through the following one:

		$doc->getTable('Sheet1', 'normalize');

	The transformed sheets, of course, are readable by OOo Calc.
	They simply take some more disk space when the processed spreadsheet
	is saved. If the document is later read then written by OOo Calc,
	the storage is optimized again, so the effects of normalizeSheet()
	disappear.

	normalizeSheet() is neutral against already normalized tables.

	An explicit call to this method can be replaced by getTable() with the
	additional length and width parameters. In addition, normalizeSheet()
	is automatically executed before resizing each time a table is
	processed by expandTable().

=head3	normalizeTable(table [, rows [, columns]])

	See normalizeSheet().

=head3	outputDelimitersOn()

=head3	outputDelimitersOff()

        Turns delimiters on or off. Used to mark up text exported by certain
        methods like getText or selectTextContent.

        The delimiters actually used depends on the table loaded into the
        OODoc::Text instance via the 'delimiters' property.

=head3	outputTextConversion(text)

	Returns the conversion in local character set of the given text,
	supposed to be in UTF8. The local character set of the document
	is used (see the 'local_encoding' property).

=head3	removeBookmark(id)

	See deleteBookmark().

=head3	removeHeading(position [, level => level_no])

=head3	removeHeading(element)

        Removes the given heading element.

        Example:

            $doc->removeHeading(4);

        removes the 5th heading (whatever its level) counted from the
        beginning of the document.

	See getHeading() for the argument and option.

	If the argument is an element reference (second form), the type is
	not checked and this method becomes the equivalent of removeElement()
	(which is documented with OpenOffice::OODoc::XPath generic methods).

=head3	removeHyperlink(path, position)

=head3	removeHyperlink(element)

	Removes any hyperlink contained in the given element, leaving
	in place the previously hyperlinked text.

=head3	removeParagraph(position)

=head3	removeParagraph(element)

        Removes the paragraph at the given position (first form).

        The paragraph to be removed can be indicated by element reference
        (second form). In this case, the type of element is not checked and
        this method becomes the equivalent of removeElement.

=head3	removeCellSpan($cell)

	Removes the multi-column, multi-row span of a table cell. The width
	and height of the cell are reduced to one column and one row.The
	uncovered cells take the same style and data type as the reduced cell.
	
	Caution: This method works with cells that heve been expanded using
	the "number-rows-spanned" and "number-columns-spanned" OpenDocument
	attributes. The cell expansion is done this way by the cellSpan()
	method, as well as with the present version of OpenOffice.org Calc.
	But other applications (including the present version of
	OpenOffice.org Writer) can implement the cell merge using subtables
	instead of span attributes.

=head3  removeSpan()

        See removeTextStyleChanges().
	
=head3	removeTextStyleChanges(path, position)

=head3	removeTextStyleChanges(element)

        Removes all the text style that apply to particular text spans in the
        paragraph or a heading provided as argument, so all the content will be
        displayed according to the text style that is defined at the paragraph
        level (font, colors, etc).
        
        Works with paragraphs or headings only.

	For a more drastic result, see flatten() in OpenOffice::OODoc::XPath.

        See also setTextSpan(). Caution: there is no symmetry between
        setTextSpan() and removeTextStyleChanges(). The first one creates one
        styled text span at a time in a given context that may be larger than
        a single paragraph. The second one removes all the styled text spans
        in the given context, but the context is a paragraph or a heading only.

=head3	renameSection(section, newname)

	Renames an existing section using the second argument.

=head3	renameTable(table, newname)

	Renames an existing table using the second argument.

=head3	replaceText(path, position, filter, replacement)

=head3	replaceText(element, filter, replacement)

        Replaces all sub-strings which match "filter" with "replacement" in
        the text of an element (and its descendants) indicated by
	[path, position] or by reference and returns the modified text. The
	"filter" string can be an "exact" literal or a regular expression.

        Example:

            $doc->replaceText($p, "C(LIENT|USTOMER)", $contact);

        replaces each occurrence of "CLIENT" and "CUSTOMER" with the content
        of the $contact variable in the paragraph $p of document $doc.

        The "replacement" argument can be a function reference. In which
        case, the function is called each time the string is matched, and
        the value returned by the function is used as the replacement value.

        	sub action	{
        		my $arg = shift;
        		my $text = shift;
        		print "$arg : $text\n";
        		return "OK";
        		}
		$doc->replaceText($p, $expression, \&action, "Found");

        displays "Found: <text>" (where <text> is the text retrieved) each
        time a string matches $expression and replaces this string with
        "OK". If $expression contains an "exact" string (not a regexp), then
	clearly the text displayed will always be the same string. However,
	if it happens to be a regular expression, it is in effect the text
        retrieved which will be displayed.
	
        Generally speaking, if the replacement value is a function
        reference, the called function receives the remainder of the
        arguments which follow it, in this order:
	
	1) all the arguments following the function reference in the
	replaceText() call, in the same order;
	
	2) the string that matches the filter argument.
	
	See also substituteText(), which should be preferred in most
	situations.

=head3	rowStyle(row_element [, style])

=head3	rowStyle(table, row [, style])

        Reads or modifies a table row's style, in the same way as
        columnStyle does for columns.

=head3	sectionProtectionKey(section)

	Returns the encrypted key which is associated to the given section,
	if the section is write-protected by key.

	This method can't provide the real key (as it should be typed by
	the end-user to unlock the section), but the returned value may be
	reused in order to protect more than one section with the same
	password.

	See also unlockSection().

=head3	sectionStyle(section, [newstylename])

	Without argument, returns the current style of a given section.

	If an argument is provided, it becomes the new style of the section.

=head3	selectDrawPageByName(name)

	In a presentation or drawing document, returns the page element
	identified by the given name, or undef if the name is unknown.

	The names to be used correspond to the displayed page names in
	OpenOffice.org Impress.

=head3	selectElementByBookmark(name)

	Returns the element containing the given bookmark.

	Caution: this method works with position bookmarks only, not with
	range bookmarks (a range bookmark can be spread over several text
	elements).

=head3	selectElementByContent([context,] filter [...])

	Returns the first text element whose content matches the 'filter'
	(which can be an exact string or a regular expression), or undef
	if no matching content is found.

	With additional arguments after the filter, this method can be used for
	replacement operations, or user-defined function triggering, in the same
	conditions as selectElementsByContent().

	The retrieval functionality of selectElementByContent() is the same
	as selectElementsByContent(). See selectElementsByContent() for
	limits.

=head3	selectElementsByContent([context,] filter)

=head3	selectElementsByContent([context,] filter, replacement)

=head3	selectElementsByContent([context,] filter, action [, other_arguments])

        This method returns the text elements whose content matches the search
        criteria contained in 'filter' (a string that may be a regexp).
        Note that this method can be used with a "non-filtering" regular
        expression (".*") for unconditional movement through all text elements.
	
	The default scope is the current context (practically it's the whole
	document unless it has been changed using the currentContext() method).
	However a context element may provided before the filter argument in
	order to restrict the search space.

        Be careful: if the search is successful, the returned elements may be
        of various kinds; they are not always paragraphs or headings. They
        may be, for example lower level text elements contained in paragraphs,
        such as text spans or text hyperlinks.

        The first form simply returns the given list without modifying the
        text.

        The second form returns the same list, but replaces all strings
        which match the search criteria with the 'replacement' string as it
        goes.

        The third form, where the 'action' argument is a program function
        reference, launches the given function each time the filter string
        is matched. If defined, the value returned by the function is used
        as the replacement value. If the function returns a null value
        (undef) then no replacement is made. If it returns an empty string,
        the retrieved text is deleted. The called function receives the rest
        of the arguments, in this order:

	1) all remaining arguments after 'action' ('other_arguments'), if any.

	2) the element containing the retrieved text.

	3) the string actually selected. If the filter is an exact string,
	it is equal to the filter. If the filter is a regular expression,
	it matches the "real" text retrieved.

	The returned text (if any) must be encoded in UTF8.

        The returned list is the same one returned by the first two forms.

        Example:

            sub action
            	{
            	my ($d, $element, $value) = @_;
            	if ($value < 100)
            		{
            		$d->removeElement($element);
            		return undef;
            		}
            	else
            		{
            		return $value * 2;
            		}
            	}
                        @list =
             $doc->selectElementsByContent("[0-9]+", \&action, $doc);

        In the above code, the subroutine "action" is called each time an
        integer (one or more digits) is found. The subroutine receives the
        document reference itself as its first argument (an OODoc::Text
        object given by the application). Next, it automatically receives
        the reference of the element in which the search string was found
        (i.e. an integer) and, finally, it receives the exact number found
        as its second-last and last arguments respectively. If this number
        is less than 100, the element is removed. This is why the subroutine
        needed the $doc object, used to invoke the removeElement method. If
        more than 100, the number is multiplied by two and the result
        replaces the original value in the element. The list returned by
        selectElementsByContent contains all elements which contain the
        search string, including any which might have been removed by the
        called function while it was running.

        It is the "main" elements containing strings which matched the
        filter which are returned and not any of their sub-elements. For
        example, if the returned string is found in one of the items in an
        unordered list, the list element is selected and not the item.
        Similarly, the table is selected when one of its cells matches the
        filter, and the paragraph which is selected when the search string
        is found in an attached footnote.

	Important limit: This method can't retrieve elements whose display
	content apparently matches the given filter but whose internal
	storage doesn't. For example, a paragraph containing "foo bar" will
	never be selected through selectElementByContent() if "foo" and "bar"
	have different text styles. In the same way, a substring containing
	multiple successive whitespaces will never match, because, according
	to the ODF standard, multiple spaces (like tabs or line breaks) are
	stored as special XML element instead of flat text. A character string
	cannot be considered to match the filter unless it is entirely within
	the same sub-element and all its characters have the same style. More
	generally, a substring can match the filter if and only if it's
	represented with only one style and if it doesn't contain multiple
	spaces, tab stops or line breaks.

=head3	selectHyperlinkElement(url_filter)

	Retrieves the first hyperlink element (if any) whose the URL matches
	the argument. Example:

		my $e = $doc->selectHyperlinkElement("cpan");

	could return an hyperlink element containing "www.cpan.org" as
	well as "search.cpan.org", etc. The URL filter is processed as
	a regexp.

	Note: In order to get the text container (ex: paragraph) where the
	hyperlink is located, the application can use the parent() element
	method. Example:

		 my $e = $doc->selectHyperlinkElement("www.cpan.org");
		 my $p = $e->parent if $e;

=head3	selectHyperlinkElements(url_filter)

	Returns the list of the hyperlink elements whose the URL matches
	the argument (and not only the first one).

=head3	selectParagraphByStyle(stylename)

        Returns the first paragraph (if any) using the given style.

=head3	selectParagraphsByStyle(stylename)

        Returns the list of the paragraphs using the given style.

=head3	selectTextContent(filter)

=head3	selectTextContent(filter, replacement)

=head3	selectTextContent(filter, action [, other_arguments])

        Returns a list of header texts and/or paragraphs (in the document's
        own order) which match the given search criteria.

        The filter can be an exact string or a regular expression. A filter
        set to ".*" (no selection) will result in an export of the entire
        text.

        In all three forms, this method behaves like
        selectElementsByContent, except that it returns text instead of a
        list of elements.

        Depending on the context (list or scalar), the result is returned in
        the form of a list of rows or in the form of a single character
        string where the elements are separated by a line-feed ("\n").

        Note: called with a "non-filtering" regular expression, this method
        will result in a "flat" export of the document:

            print $doc->selectTextContent('.*');


=head3	setAnnotation(element [, options])

	Creates and inserts an annotation in a given element.

	The possible options are:

	'date' => the date/time of the annotation (ISO-8601 format); the default
	is the current system date/time

	'author' => the name of the author of the annotation; unless this
	option is provided; the default is the current system user name
	
	'text' => the text content of the annotation (no default)

	'style' => a paragraph style for the annotation (no default)

	'offset' => an integer value that specifies the position of the
	insertion point of the annotation (default=0); a negative value means
	that the position is counted backward from the end
	
	'before' => a regular expression; specifies that the insertion point
	should be before the first match
	
	'after' => same as 'before' but the insertion point should be after the
	first match
	
	'replace' => same as 'before', but the matching substring is deleted
	and replaced by the annotation
	
	If 'before', 'after' or 'replace' (which are mutually exclusive) is set,
	the 'offset' option, if provided too, specifies a search space
	restriction and a search way. If 'offset' is positive, the search space
	runs from 'offset' to the end; if 'offset' is negative, the search space
	runs from the end and its size is the absolute value of 'offset'.
	
	If 'offset' is 0, then it's possible to force the search backward from
	the end to the beginning using an additional 'way' parameter whose
	possible values are 'backward' and 'forward' (if 'way' is 'backward',
	then 'offset' is regarded as negative whatever its sign).
	
	Note that the 'capture' option doesn't work with annotations.
	
	Returns the reference of the annotation element. Note that this
	reference could be used later as a context for additional insertions
	(for example in order to append several paragraphs to the content of
	the annotation).

=head3	setBibliographyMark(element, [, position_options][attributes])

	Creates a new bibliography mark within a given text element.
	
	The content of the new bibliography entry may be initialized through
	a 'attributes' parameter whose value is a hash.
	
	All the possible attributes of an ODF-compliant bibliography entry, 
	such as author, editor, isbn, title, year, and many others, are
	allowed. A 'identifier' parameter is mandatory in order to get a
	visible mark; note that this identifier is bibliography-specific and
	is not the same as the generic identifier that could be get or set
	using getIdentifier() and setIdentifier(). Other attributes are optional
	(but, of course, an entry with nothing more than an identifier would not
	be very useful in a final document).
	
	By default, the object is inserted at the beginning of the target text
	element. But, thanks to the optional position parameters, it can be put
	anywhere within the text of the bookmarked element. The position
	parameters are 'offset', 'before', 'after', 'replace', and 'way' and
	they work like with setAnnotation().        

		$para = $doc->selectElementByContent("ODF-related book");
		$doc->setBibliographyMark (
			$para,
			offset     => -20,
			replace    => "reference needed",
			attributes => { 
			    identifier	=> "JDE",
			    title	=> "OASIS OpenDocument Essentials",
			    author	=> "J. David Eisenberg",
			    year	=> 2005,
			    isbn	=> "1-4116-6832-4"
			    }
			);

        This sequence replaces a "reference needed" substring in a given
        paragraph by a bibliography mark that will be displayed by default as
        "[JDE" and that contains various attributes. The 'replace' option means
        that the given substring will be deleted and replaced by the mark. The
        given (negative) offset means that the substring must be searched
        backward and that the last 20 characters of the paragraph must be
        excluded from the search space.

=head3	setBookmark(element, name [, position_options])

	According to the structure of the optional parameters, this method may
	be used either to set a position bookmark (i.e. a named place holder
	at some point of the text content in a pararaph) or to set a range
	bookmark (i.e. a range of text that may spread across paragraph
	boundaries and that is delimited by a bookmark start and a bookmark end
	elements).
	
	The first form is illustrated by the following example:

		$doc->setBookmark(
		        $paragraph, "BM001",
		        offset  => -20
		        before  => "xyz"
		        );

	This sequence puts a bookmark identified by "BM001" in a given
	paragraph, immediately before the first "xyz" substring found in a
	backward search among the last 20 characters.
	
	The mandatory arguments are the target text element and the name of the
	new bookmark (that should be unique).

	By default, the object is inserted at the beginning of the text. But,
	thanks to the optional position parameters, it can be put anywhere
	within the text of the bookmarked element. The position parameters
	are 'offset', 'before', 'after', 'replace', and 'way', and they work
	like with setAnnotation(). See also setChildElement() in OODoc::XPath.
	However, the 'text' option is ignored, knowing that a bookmark has no
	text content. If the 'replace' option is used, the matching substring
	is deleted and replaced by the bookmark, but the deleted text is not
	reused.

        The second form requires a bookmark name as the 1st argument, then
        a 'start' and a 'end' parameters are required; each one is a hash of
        parameters that specifies the position of one mark according to the same
        options as for a position bookmark (namely with 'offset', 'before',
        'after', 'replace', and 'way'). In addition, each of the 'start' and
        'end hashes may contain an additional 'context' parameter that specifies
        the elements that will contain the start and end marks, respectively.
        
        The following example creates a range bookmark that starts after the
        15th character of $p1 and ends before the "xyz" substring in $p2,
        assuming that $p1 and $p2 are previously selected paragraphs in the
        right order:
        
                $doc->setBookmark(
                        "BM002",
                        start   => {
                                context => $p1,
                                offset  => 15
                                },
                        end     => {
                                context => $p2,
                                before  => "xyz"
                                }
                        );
                        
        The user is not prevented by default from creating a range bookmark
        whose start point is after the end point of a range bookmark. However,
        it's possible to force an order check using a boolean 'check' option.
        If 'check' is 'true' while the order is wrong, the bookmark is not
        created.
        
        Note that the second form of setBookmark() is the same as
        setRangeBookmark().

=head3	setHyperlink(path, position, [context,] expression, url)

=head3	setHyperlink(element, expression, url [, options])

	Puts an hyperlink on a text area in a given text element.
	The first substring matching the given "expression" argument in the
	text element (if any) will become the hyperlinked text. The "url"
	argument is, of course, the URL of the hyperlink. If successful, the
	method returns the new hyperlink element, or undef otherwise.

	This short example illustrates the simplest use:

	    $doc->setHyperlink($para, "CPAN", "http://www.cpan.org");

	This method works in the same way as setTextSpan(), described below,
	but the text span is hyperlinked, and not only presented according to
	a particular style. So, the third argument must be an URL instead
	of a style. 
	
	A set of hyperlink attributes may be optionally provided as a hash
	through an optional 'attributes' parameter. For example, the application
	can provide a 'style-name' and a 'visited-style-name' as shown below:
	
	    $doc->setHyperlink (
			$para, "CPAN", "http://www.cpan.org",
			attributes      => {
			        'style-name' => "ToBeVisited",
			        'visited-style-name' => "Visited"
			        }
			);
			
	'style-name' selects the style which applies to the text of the
	hyperlink, as long as the URL is not visited, while
	'visited-style-name' indicates, of course, the style in use if the
	link location was already visited. These styles must belong to the
	'text' family. 
	
	Other allowed hyperlink attributes are listed in the §5.1.4 of the
	OASIS OpenDocument specification. They may be set through the
	'attributes' options or later through the common setAttributes() method
	(that may apply to the object returned by setHyperlink).

	Note: The hyperlink is not always a remote URL, such as in the
	example above. Internal references ere allowed as well. An
	internal reference is prefixed by "#". If an internal reference
	is a heading, it's prefixed by "#" and suffixed by "|outline".
	An hyperlink may be aimed at a location inside another document;
	such a link is the concatenation of a file path, a "#", and a local
	name that makes sense in the target document (bookmark, heading...).

=head3  setIndexMark(element, id [, options][, start =>{}, end =>{}])

        Creates an alphabetical index entry in a given element. The first
        arguments are the target element (generally a paragraph) and a
        mandatory identifier (that should be unique).
        
        A 'type' parameter allows one to select the type of index; possible
        values are 'alphabetical-index' or 'toc' (the last one stands for
        "table of contents index mark"). The default is 'alphabetical-index'
        (it may be wrote 'alphabetical index', knowing that every space is
        automatically interpreted as a '-').
        
        A 'content' parameter allows one to specify an expression; the first
        substring in the element that matches this expression will become the
        indexed substring. It's possible to restrict the search area using a
        'offset' option, a positive or negative integer; a positive value means
        that the search space runs from the beginning to the given offset; a
        negative value means that it runs backward from the end to the given
        offset. In addition, a 'way' option whose legal values are 'forward' or
        'backward' may control the search way: if 'way' is 'backward' then the
        search is done backward even if 'offset' is not provided, and 'offset'
        is regarded as negative even if it's provided without the minus sign.
        Unless 'offset' is defined and negative, the default way is 'forward'.
        
        The code below puts an index entry, identified by "idx001" and related
        to the first match of a "xyz" expression:
        
                setIndexMark(
                        $paragraph, "idx001",
                        type    => 'alphabetical index',
                        content => "xyz"
                        );
        
        Note that the 'type' option is provided for clarity only, knowing that
        'alphabetical-index' is the default.

        The following variant puts a TOC mark, searched backward from the end
        of a given paragraph, within a 20-character-long area:
        
                setIndexMark(
                        $paragraph, "idx001",
                        type    => 'toc',
                        content => "xyz",
                        offset  => 20,
                        way     => 'backward'
                        );
        
        The same result in this second example could be obtained without the
        'way' option, with -20 instead of 20 as the 'offset' value.
        
        A more sophisticated set or parameters may be provided in order to
        specify the beginning and the end of the index mark separately. To do
        so, 'content' must be omitted and replaced by the 'start' and 'end'
        parameters, each one being a hash, just like with the second form of
        setBookmark() that created a range bookmark, with a restriction: 

        The 'start' and 'end' optional parameters allows one to specify the start
        and the end positions of the index mark. Each one is a hash that may
        contain the same options as with setBookmark() described below, namely
        'offset', 'before', 'after', 'replace', and 'way', with the exception
        of 'context', because (unlike a bookmark) an index mark is entirely
        included in a single paragraph; its start and its end belong to the same
        context, that is specified by the first argument.
        
        The following example creates an alphabetical index mark that is
        associated to a text range running from the "xyz" substring to the end
        of the given paragraph:
        
                $doc->setIndexMark(
                        $paragraph, "idx002",
                        type    => 'alphabetical index',
                        start   => {
                                before  => "xyz"
                                },
                        end     => {
                                offset  => 'end'
                                }
                        );

=head3  setNote(path, position, text [, options])

=head3  setNote(element [, options])

        Creates and inserts a footnote or an endnote in the given element with
        the given text as the note content. Returns the new note element in
        case of success, or undef if the target element doesn't exist.
        
        Supported options are:
        
        'text' => the text content of the note
        
        'class' => specifies the display class of the now note; may be 'footnote'
        or 'endnote', default is 'footnote';
        
        'id' => a note identifier, must be provided by the application and must
        be unique for the class (be careful, the uniqueness is not automatically
        checked and no default is provided);
        
        'citation' => specifies the character string to display as note citation
        (at the place in the host element where the note is anchored);
        
        'label' => this option, if provided, means that the note should not be
        processed as automatically numbered by the printing/editing applications
        and that it should be represented by the given (arbitrary) string; if
        'label' is defined, it becomes the default value of 'citation';
        
        'style' => specifies the style of the note content (should be a regular
        paragraph style).
        
	By default, the object is inserted at the beginning of the text. But,
	thanks to the optional position parameters, it can be put anywhere
	within the text of the bookmarked element. The position parameters
	are 'offset', 'before', 'after', 'replace', and 'way' and they work
	like with setAnnotation().

=head3  setRangeBookmark(name, start => {options}, end => {options}, ...)

        Like the second form of setBookmark(): creates a range bookmark
        according to a mandatory name (1st argument) and position options
        provided through 'start' and 'end' parameters, each one being a hash
        of options. See setBookmark() above for details.

=head3  setSpan()

        Deprecated.
        
        See textStyle(), setTextSpan() and setTextSpans(), more powerful but
        using different options.

=head3	setStyle(path, position, style_name)

=head3	setStyle(element, style_name)

        Obsolete. See textStyle().

=head3	setText(element, text ,[text, ...])

        Alters the setText method of OODoc::XPath, so that it can handle
        complex text elements. Please read the setText() entry in
	OpenOffice::OODoc::XPath before the present entry.

        If the element is a paragraph, a header or a list item (ordered or
        unordered), its content is replaced by the 'text' argument. Caution:
        setText() deletes and replaces the previous content of the paragraph.

        If the element is a table cell, this method is the same as
        updateCell.

        If the element is a list (ordered or unordered), the content of each
        'text' argument (however many) forces the creation of a new item
        which is appended to the list (existing items remain unchanged).
        Example:

            $doc->setText($element, "Peter", "Paul", "John")

        adds three items to the list if $element is a list. If $element is,
        for example, a paragraph, then the second argument ("Peter") becomes
        the content of the paragraph and the other arguments are ignored.

	If the element is a note element or a note body, the given text
	becomes the content of the note body.

	If the element is a section, the whole content of the section is
	deleted and replaced by a single paragraph containing the given text.

        For all other types of $element, setText() behaves normally as defined
        in OODoc::XPath.

	Note: setText(), as any other text input method, doesn't properly
	process repeated spaces by default. So, a sequence of spaces, whatever
	its length, is replaced by a single space. See setText() and
	extendText() in OpenOffice::OODoc::XPath.
	
=head3	setTextBoxContent(text_box, content)

	Fills the given text box according to the given content.
	
	The first argument may be the unique name, the order number or the
	reference of a text box. The content is processed in the same way
	as the content option in createTextBox().

=head3  setTextField(element, field-type [, options])

        Puts a variable text field in a given text element.
        
        The 2nd argument specifies the type of field. The offical types are
        described in §6.2 and §6.4 in the OpenDocument 1.1 specification,
        corresponding to the so-called "document fields" and "metadata fields".
        
        Examples of possible field type arguments are 'page number', 'chapter',
        'paragraph count', 'time', 'file name', 'creator', 'creation date', etc.
        The full syntax of the ODF field tags is not mandatory; the right
        namespace prefix is automatically added if the given type indicator
        doesn't contain a semicolon, and every space is replaced by a '-'. So,
        a field type like, say "text:word-count" may be specified as
        "word count".
        
        This method may be used in order to display a declared user field. To
        do so, the field type must be 'variable' instead of a regular ODF
        text field, and a 'name' parameter must be provided with the name of an
        existing (ot to be created) user field declaration.
        
        While the content of a text field is often computed and displayed
        dynamically by ODF-compliant viewers, it's possible to provide an
        alternative text that will be persistently stored in the field and
        available for applications which are note able to compute the content
        and/or for users who need to know the last displayed value. Such an
        alternative content is provided through a 'text' option.
        
        It's possible to provide the new text field with one or more attributes
        as a hash through a 'attributes' parameter. The most common attributes
        are 'fixed' and 'style'; the first one is a boolean, the
        second one is the name of a display format. The 'fixed' attribute, if
        'true', prevents the ODF-compliant editors and viewers from refreshing
        the content of the field (for example a fixed date field displays the
        same date forever instead of the current date). The 'style' attribute
        is the name of a display format (it's recommended to associate every
        date, time or numeric field to a display format, while the default
        display format of some ODF editors may be convenient for some needs).
        Here the 'style' attribute is a shorcut for 'style:data-style-name';
        see the ODF 1.1 specification §6.7.7 for a full description of this
        kind of styles.
        
        Other attributes depend on the kind of content. The following example
        creates a fixed time field; the time value is stored as standard
        (ISO 8601) date format and the alternative text is an arbitrary local
        representation of the same; the presentation style (for applications
        that can deal with ODF number styles) is "MyTimeStyle" (that is supposed
        to be the name of a time style defined as an automatic style in the
        document):
        
                $doc->setTextField (
                        $paragraph, 'time',
                        text            => "17:03:25",
                        attributes      => {
                                fixed           => 'true',
                                'time value'    => "2010-02-25T17:03:25",
                                style           => "MyTimeStyle"
                        );
         
         Note that in this example, if 'fixed' was 'false' or undef, a fully
         functional ODF editor could dynamically update the 'time value'
         according to the current date and the text content according to the
         current time and the given style. Here the internal value is a
         'time value'; it would be the same for any field type containing a
         time value (such as, say, a 'print time' or a 'creation time' field).
         For other field types, the corresponding attribute would be
         'date value', 'string value', 'boolean value', or just 'value'. For
         any detailed information about the possible attribute combinations
         according to the field types, have a look at the chapter 6 of ODF 1.1.
         
        By default, the field is inserted at the beginning of the given text
        element. But, thanks to the optional position parameters, it can be put
        anywhere within the text of the element. The position parameters
	are 'offset', 'before', 'after', 'replace', and 'way', and they work
	like with setBookmark() and other methods. See also setChildElement()
	in OODoc::XPath. If the 'replace' option is used, the matching substring
	is deleted and replaced by the text field. The next example inserts
	the name of the author of the last change (i.e. the 'creator', according
	to the ODF vocabulary) as a replacement of a "AUTHOR HERE" substring
	searched backward somewhere in a 50-character-long area at the end of
	the target element:
	
	        $doc->setTextField (
	                $paragraph, 'creator',
	                replace         => "AUTHOR HERE",
	                offset          => 50,
	                way             => 'backward'
	                );
	                
	and the code below appends after the last character of the paragraph a
	'file name' field that will display the full path of the file:
	
	        $doc->setTextField (
	                $paragraph, 'file name',
	                offset          => 'end',
	                attributes      => {
	                        display         => 'full'
	                        }
                        );

        The last example creates a display area in a given paragraph after a
        given substring for a declared variable whose name is "Amount" (see
        setUserFieldDeclaration() in OpenOffice::OODoc::XPath to see how such
        a variable may be declared):
        
                $doc->setTextField (
                        $paragraph, 'variable',
                        name            => "Amount",
                        replace         => "AMOUNT HERE"
                        );

=head3	setTextFields(element, expression, field-type [, options])

	Replaces every substring that matches the given expression in the given
	text element by a variable text field. See textField() in the present
	manual chapter for some information about text fields.
	
	This method works the same way as setTextSpans() to retrieve the strings
	to be replaced. However, each matching string becomes invisible and
	is replaced by the variable field.
	
	Optional field attributes are allowed after the field type in the same
	conditions as for textField().
	
	The following example replaces every occurrence of "TIMESTAMP" in a
	given section by a variable field displaying a time which is 2 hours
	later than the current time:
	
		$section = $doc->getSection("Variables");
		$doc->setTextFields
			(
			$section, "TIMESTAMP", 'time',
			'time-adjust' => 'PT02H'
			);
	
	This method returns the text field elements as a list.
	
	See also setTextField().

=head3  setTextSpan(path, position, style [, options])

=head3  setTextSpan(element, style [, options])

        Inserts a substring with a special text style in a selected position
        within the content of an existing text element (namely a paragraph or
        a heading). Unlike setTextSpans() and the 3-argument use of textStyle(),
        inserts only one span (or nothing if the conditions are not met).
        
        A "text span" is a substring whose presentation style differs from the
        style of the text element to which it belongs. For example, a given
        "span" could be in italics while the rest of the paragraph is in normal
        characters. A text span is a special element that contains text but that
        must be included in a paragraph or a heading. Caution: the same word has
        a different meaning when it's used about table cells (see cellSpan()).
	The properties of a text span can be related to any kind of character
	string presentation, such as font, font size, font weight, font
	style, and colors (background and foreground). Whatever these
	properties, they apply through a style.

	setTextSpan() works on any kind of text container, whatever its
	hierarchical level. For example, if the given element is a table,
	the span style attribution applies to every cell of the table. And
	the same change can be done in all the displayable content not
	including page headers, page footers, and page backgrounds through
	a single setTextSpans() call, if the given element is the document body
	itself (see getBody() in OpenOffice::OODoc::XPath).

        The first argument is the target element, the second one is the name of
        a text style (existing of to be defined). The optional parameters that
        follow specify how and where the text span should be inserted.
        
        The method returns the new text span object, or undef in case of
        failure.
        
        The location of the text span may be specified using the same options as
        the setChildElement() which is described in the OODoc::XPath manual.
        
        A 'capture' parameter, whose value is a string, means that the first
        substring that matches it should become the content of the new text
        span. The following instruction replaces the first appearance of the
        "ODF" substring in a given paragraph by a text span whose content will
        be "ODF" and whose style will be "Standout"; in other words, it tells
        that the style "Standout" will apply to the first "ODF" substring:
        
            $doc->setTextSpan($paragraph, 'Standout', capture => "ODF");

        It's possible to apply a text style and to change the text content in
        a single operation using both the 'replace' and the 'text' options.
        If 'text' is set, its value is used as the text of the new span element.
        In the next example, the "ODF" substring will be removed and replaced
        by a text span whose style will be "Standout" and content will be
        "OpenDocument" instead of "ODF":
        
            $doc->setTextSpan(
                $paragraph, "Standout",
                replace => "ODF",
                text    => "OpenDocument"
                );
        
        Note that there is no default text, so if 'replace' is set while 'text'
        is not set, the matching substring is deleted and replaced by a text
        span with a style but without content, resulting in useless markup
        (there are more convenient ways to just delete a substring).
        
        Practically, if both 'text' and 'capture' are set, the result is the
        same as with 'replace'; however, as soon as the aim is to replace a
        substring by a text span and not to capture the content of the substring
        in the text span, I encourage the use of 'replace' in order to get a
        more self-documented code.  
        
        It's possible to provide a search string with a 'after' or 'before'
        option instead of 'replace'. If so, the new text span is inserted
        after of before the first match, and no text is removed or moved into
        the text span element, that may receive the value of 'text' (if set).
        The example below creates a text span with the "Standout" style and
        whose content is "OpenDocument" immediately after a the substring "the
        best document format is ":
        
            $doc->setTextSpan(
                $paragraph, "Standout",
                after   => "the best document format is ",
                text    => "OpenDocument"
                );

        While the 'replace', 'after' or 'before' parameter automatically selects
        the first match, it's possible to reverse the search, thanks to the
        'way' option, whose possible values are 'forward' and 'backward'
        (default='forward').
        
        Caution: A substring located partly in a "span" and partly outside it
        will never match. In addition, while a text span is allowed inside
        another text span, a text span can not be spread across element
        boundaries.
        
        The 'offset' parameter is a positive or negative integer that specifies
        the start position of the span in the text. So, this parameter allows
        to insert a text span at an arbitrary position (counted forward from the
        start or backward from the end).
        
	If 'before', 'after' or 'replace' (which are mutually exclusive) is set,
	the 'offset' option, if provided too, specifies a search space
	restriction and a search way. If 'offset' is positive, the search space
	runs from 'offset' to the end; if 'offset' is negative, the start
	position is counted from the end and the search space runs backward
	from the given position and the beginning of the context.
	
	More generally, this method uses the logic and the search options of
	setChildElement() to compute the insert point, like setAnnotation() and
	other special intra-paragraph markup insertion methods;
	setChildElement() is described in the OODoc::XPath manual page.

        Remember that setTextSpan() creates only one text span with various
        options; if the aim is to automatically create a text span for every
        match of a given substring, see setTextSpans() or textStyle().

=head3	setTextSpans(element, style [, options])

        Applies a special text style to all the substrings of a given text
	element that match a given expression. See setTextSpan() for
	explanations about the meaning of "text span". The main difference
	with setTextSpan() is that setTextSpans() operates repeatedly so it
	may apply the given style to every substring that matches the given
	conditions.

        The context element and the style to apply are provided as mandatory
        arguments. They are followed by the named search parameters. These
        parameters are the same as for setTextSpan(). Warning: the user must
        ensure that the provided search parameters make sense and can't result
        in an infinite loop. For example, the following instruction will
        attempt to create an infinite sequence of continuous bookmarks before
        the first occurrence of "xyz" substring, if this substring exists:
        
                $doc->setTextSpans(     # Wrong !
                        $paragraph, "SomeStyle",
                        before  => "xyz"
                        );

        Taking the following paragraph as an example:

	"OpenOffice.org includes Writer, Calc, Draw and Impress"

	Assuming this text is contained in a $p element, the following
	instruction gives the "Highlight" style to the "OpenOffice.org",
	"Writer", "Calc", "Draw", and "Impress" substrings:

		$doc->setTextSpans(
		    $p, "HighLight",
		    capture => 'OpenOffice\.org|Writer|Draw|Calc|Impress'
		    );

        Note that the instruction above produces the same result as:
        
                $doc->textStyle(
                        $p, "HighLight",
                        'OpenOffice\.org|Writer|Draw|Calc|Impress'
                        );

        While the 3-argument use of textStyle() is appropriate as long as the
        aim is to unconditionally apply the given style to every matching string
        in the context, setTextSpans() allows much more selective operations.

        The given context may be any element, including the whole document,
        and not only a paragraph. This last example produces the same effect
        as the previous one, but it operates between two given arbitrary text
        bookmarks that may be in different paragraphs in the document, while
        the context is the document body:
        
                $doc->setTextSpans(
                    $doc->getBody(), "HighLight",
                    capture => 'OpenOffice\.org|Writer|Draw|Calc|Impress',
                    start_mark => $doc->getBookmark("BM1"),
                    end_mark   => $doc->getBookmark("BM2")
                    ); 

        See also setTextSpan(), removeStyleChanges(), textStyle() and
        setHyperlink().

=head3  setUserFieldDeclaration(name [, options])

        Creates a user field declaration for the document. Allowed options
        are:
        
                'type'  => the data type (default=string)
                'value' => the initial value (default="")
        
        Returns the new variable element if successful. Does nothing and
        returns undef if the variable already exists. The example below creates
        a declaration for a variable whose name="Amount", type=float and
        value=1234.56
        
                $doc->setUserFieldDeclaration(
                        "Amount",
                        type    => 'float',
                        value   => 1234.56
                        ); 
        
        See also getUserField(), userFieldValue(), setTextField().

=head3	substituteText(element, filter, replacement)

	Replaces any substring in a given element and its descendants,
	matching a given filter (regexp) by a given replacement string.
	
	It "replacement" is a string, this method produces the same result as
	replaceText(), and it should be preferred.
	
	If "replacement" is a function reference, the replacement value is the
	return value of the function. But, unlike replaceText(), any argument
	after "replacement" is ignored.
	
	This method is a wrapper for the subs_text() method provided by the
	XML::Twig::Elt class. See the XML::Twig documentation for advanced
	details.

=head3	tableName(table [, newname])

	Returns the current name of a given table, or replaces it with a new
	name given as the second argument. The table can be indicated
        by number, logical name or reference.

	Returns undef unless the given table is defined.

	If the new name is the name of an existing table, the table is not
	renamed and an error message is produced.

=head3	tableStyle(table [, style])

        Returns the current style of a given table, or replaces it with a
        new style given as the second argument. The table can be indicated
        by number, logical name or reference.

=head3	textBoxCoordinates(text_box [, new_coord])

	Gets or sets the position of a text box. The new coordinates, if
	any, must be provided using the same syntax and units as with
	the "position" option in createTextBox().
	
=head3	textBoxDescription(text_box, [, new_desc])

	Gets or sets the optional description (long label) of the given
	text box.
	
=head3	textBoxName(text_box [, new_name])

	Allows the applications to get the name of the given text box
	(which makes sense if the name is unknown, i.e. if the first
	argument is the element reference or the order number and not
	the name itself, of course). If a literal is passed as a second
	argument, the text box is renamed accordingly.
	
=head3	textId(element [, text_id])

	This accessor gets or sets the "text identifier", an optional
	attribute of any text container. This attribute is presently used
	for a few elements by OpenOffice.org (ex: the notes).

	With one argument only, returns the existing identifier of the given
	element, or undef if the element doesn't own a text identifier.
	If a second argument is provided, its value replaces any previous
	value of the identifier, and the text identifier is created if needed.
	The new value is not checked, so the application should take care of
	its uniqueness.

	The text identifier can be used as a bookmark, knowing that, unlike a
	bookmark, this attribute is not visible for the end user.

	See also selectElementByTextId().

	Caution: The text identifiers created or changed by other applications
	are presently *not* preserved when the document is edited through
	OpenOffice.org.

=head3	textField(type [, options])

	Creates and returns a variable field to be inserted within a text
	element.
	
	Such a field doesn't contain any static text by itself. When
	included in a text container, it tells the editing/printing software
	to display dynamic context data, such as date, time, file name,
	page number, page count, author, etc. Variable text fields are mainly
	used in page headers or footers, but they are allowed in the page
	bodies as well. Remember that a text field must be attached as a child
	element of a text container (paragraph or heading) in order to be
	displayed. However, the text container itself may be attached to
	anything anywhere (ex: a page header, a table cell, a list item, etc).
	
	The first argument (mandatory) is the field type. Many field types
	are allowed, so they are not all listed here. For some of them,
	options are allowed or required.
	
	To get the full list of field types, and their possible options,
	look at the chapter 6 "Text fields" in the OpenDocument 1.0
	specification. However, a few ones are presented below as examples.

	The field type, as well as each field option, must be provided as it
	appears in the OpenDocument specification, without the "text:" prefix
	(this prefix is automatically added). However, the application can
	force any arbitrary field name and/or field option such as 'xxx:yyy'
	(any name or option including a ':' is accepted as is).
	
	Caution: textField() allows the user to create any kind of field,
	without OpenDocument compliance check. So it can be used to insert
	application-specific markup in any place. This feature could prove
	useful in some situations, but remember that a typo in a field type
	or option will not be automatically detected. In the other hand, every
	non-OpenDocument field is silently removed if the document is later
	edited and saved through OpenOffice.org.
	
	Knowing that the created element is not attached to a text container,
	it must be inserted or appended through another method. For example,
	the following sequence creates a paragraph displaying "This document
	contains <page-count> pages and we are in the page <page-number>":
	
		$para = $doc->appendParagraph
			(
			text => "This document contains ",
			style => "Standard"
			);
		$pg = $doc->textField('page-count');
		$doc->appendElement($para, $pg);
		$doc->extendText($para, " pages and we are in the page ");
		$pg = $doc->textField('page-number');
		$doc->appendElement($para, $pg);	
		
	The 'page-number' field type, introduced above, could be adjusted in
	order to display the page number of any following or preceding page.
	To do so, a 'page-adjust' option, set with a positive or negative
	integer value, should be provided to createField():
	
		$pg = $doc->textField
			('page-number', 'page-adjust' => -2);
			
	Note that, if the arithmetic sum of the real page number and the
	'page-adjust' value doesn't match an existing page, the editing
	application should display nothing.
			
	As another example, a 'chapter' field displays the current chapter
	number or title. It requires 2 options: 'outline-level', an integer
	which selects the hierarchical heading level to be regarded as the
	chapter level, and 'display' which controls the value to display
	(chapter number, chapter name or both). The following instruction
	creates a field displaying the number and the name of the current
	level 1 heading:
	
		$chapter_field = $doc->textField
			(
			'chapter',
			'outline-level'	=> 1,
			'display'	=> 'number-and-name'
			);
			
	Other possible fields display the current date or time (see the
	setTextField() example about a time field with an optional ajustment),
	the author's name, the file path or name, and many other variable or
	fixed values, according to many options.

=head3	textStyle(path, position [, style [, expression]])

=head3	textStyle(element [, style [, expression]])

        Reads the name of a text element's style or, if a 'style' argument is
	given, changes it. The text element may be a section, paragraph, a
	heading, or a text span included in a paragraph or a heading.

        The element can be indicated by the pair [path, position] or by
        reference.

        If a style is provided as the second argument, it's applied to the text
        element (and it replaces the previously set style, if any).
        
        If a text string is provided as the third argument, the given style
        applies to every matching substring in the element, and not to the
        element itself. In this case, the given style must be a text style,
        while it must be a paragraph style otherwise.

        The returned value is a literal style identifier, i.e. the value
        of the element's 'text:style-name' attribute. This identifier could
	be used to retrieve the style element itself, through another method
	such as getStyleElement() (see OpenOffice::OODoc::Styles).
	
	In the following example, the 1st instruction just returns the current
	style of a given paragraph, the 2nd one sets the style of the given
	paragraph to "New Paragraph Style", and the 3rd applies the "New Text
	Style" to every substring matching "foo" in the given paragraph:
	
	        $current_style = $doc->textStyle($paragraph);
	        $doc->textStyle($paragraph, "New Paragraph Style");
	        $doc->textStyle($paragraph, "New Text Style", "foo");
	
	For more selective ways to apply a text style to a portion of paragraph,
	see setTextSpan().

=head3	unlockSection(section)

	Removes the write protection (if any) of the given section. If the
	section was key-protected, the key is removed and provides the return
	value of the method.

	Example:

		my $key = $doc->unlockSection("Section1");
		$doc->lockSection("Section2", $key);

	The two lines above remove the protection of "Section1" and protect
	"Section2" with the password which previously protected "Section1".

=head3	unlockSections()

	Removes the write protection of every section in the document.

=head3	updateCell(table, row, column, value [, text])

=head3	updateCell(element, value [, text])

        Modifies the content of a table cell.

        In its first form, indicates a cell by its 3D coordinates, as with
        getTableCell(). In its second form, indicates a cell by its element
        reference.

        If the cell is set to literal, its content is limited to its text.
        In this case, the optional argument "text" is of no use (the text
        equals the value).

        If the cell is set to numeric (float, currency, date, etc.), you
        should generally pass a literal argument as well as the value.

        This method can be replaced by cellValue() which allows reads and
	writes.

=head3  updateText(element [, options])
        
        Changes some text content in the given element or its descendants,
        according to the given options:
        
        'text': a text string that will be inserted somewhere within the
        element, at a position which depends on other options, by default at
        the beginning.
        
        Alternatively, the 'text' option may be a reference to a user-provided
        function whose return value will be used as the text to be inserted;
        this function will be called with the document object as its first
        argument (so it can use document-based methods), the current text node
        as its second argument and optionally with a text string (that depends
        on other options, see below) as its third argument. (Be careful, a
        "text run", or "text node", is not always an element; it may be a local
        text segment within an element.) The user-provided function is not
        supposed to update the text node by itself. If the return value is
        undef, or an empty string, nothing is inserted.
        
        'replace': a search string (regex) whose first match will be deleted
        (and, of course, replaced by the value of the 'text' option , if any).
        
        'after': a search string (regex) whose first match will be followed by
        the new inserted text.
        
        'before': a search string (regex) whose first march will be preceded by
        the new inserted text.
        
        Note that 'replace', 'before' and 'after' are mutually exclusive. If
        'text' is set with a function reference, the corresponding function
        will be called with the matching substring as its second argument; if
        none of the allowed search string options is set, this function will be
        called with the document argument only.

        'way': an indicator, whose allowed values are 'forward' and 'backward'
        (default 'forward'), that specifies the search way. If 'way' is
        'backward', the provided search string (if any) is searched backward
        from the end (i.e. the first match is the last match in the order of the
        document), and the 'offset' is counted back from the end (note that a
        negative offset automatically switches the 'way' to 'backward'). If the
        result doesn't depend on the search way, the 'way' option should be
        omitted or set to 'forward'.
        
        'offset': a numeric position that specifies the point where the content
        of the 'text' option will be inserted; if 'offset' and one of the
        allowed search strings (after, before or replace) are provided, then
        'offset' specifies the limit of the search area instead of a insertion
        point; if 'offset' is positive and 'way' is 'forward' (or not set), the
        search is done from 'offset' to the end; if 'offset' is negative or
        'way' is 'backward', the search is done backward from the given offset
        to the beginning; a negative 'offset' means a backward 'way' (but if
        'way' is 'backward', the sign of 'offset' is ignored, in order to avoid
        useless complications).

        'repeat': if set to 'true', specifies that the action must be done
        repeatedly in a way that depends on the other options. If 'repeat' is
        set to 'true' while none of the search string options (after, before or
        replace) is set, the result depends on the 'offset'. If 'offset' is 0
        or undef, then the 'repeat' option is ignored (avoiding an infinite
        loop!). If only 'offset' and 'text' are provided, the new text is
        repeatedly inserted with 'offset' as the interval.
        
        Note: for repetitive and unconditional text replacements in a given
        context (i.e. when no parameter other than the context, the search
        filter and the replacement string is required), substituteText() should
        be preferred (see substituteText() in OODoc::XPath).
        
        The following example replaces the last match of "old" by "new" in a
        given paragraph:
        
                $doc->updateText(
                        $paragraph,
                        replace         => "old",
                        text            => "new",
                        way             => 'backward'
                        );
        
        The same, but the replacement is done for the whole paragraph (note that
        the 'way' option is omitted, knowing that in such situation the result
        will be the same whatever the search way, so 'forward' is OK):
        
                $doc->updateText(
                        $paragraph,
                        replace         => "old",
                        text            => "new",
                        repeat          => 'true'
                        );
        
        The next instruction makes sure that "Smith" becomes "Mr. Smith"
        everywhere between the bookmarks "BM1" and "BM2" (because such a space
        may spread over various and multiple elements, the whole document body
        is specified as the search context instead of a paragraph):
        
                $doc->updateText(
                        $doc->getBody,
                        before          => "Smith",
                        text            => "Mr. ",
                        start_mark      => $doc->getBookmark("BM1"),
                        end_mark        => $doc->getBookmark("BM2"),
                        repeat          => 'true' 
                        );
        
=head3	updateUserFieldReferences(user_field [, context])

	Forces an immediate update of the display representation(s) of
	a given user field, according to the actual value of the field.
	
	It's possible to restrict the scope to a particular context, that
	may be provided as an optional argument.

=head2	OpenOffice::OODoc::Element methods

	While all the methods above belong to the document object, some
	additional methods are defined for individual text containers. These
	methods belong to the OpenOffice::OODoc::Element class. The most
	general of them are described in the OpenOffice::OODoc::XPath manual.
	Some of them (listed below) are simple read-only accessors allowing
	the user to check the type of any element.

=head3	isXXX() methods

        A set of "isXXX" methods, returning true or false, allow to check
	the type of a given element. Caution, this methods belong to the
	elements, not to the document.

        Example:

            print "This is a list" if $element->isItemList;

        Here is the list of element type indicators:

            isBibliographyMark		bibliography mark (in the doc. body)

	    isCovered			covered (invisible) table cell

	    isDrawPage			presentation or drawing page

	    isEndnote			endnote main element

	    isEndnoteBody		endnote body element

            isEndnoteCitation		endnote citation element

	    isFootnote			footnote main element

	    isFootnoteBody		footnote body element

	    isFootnoteCitation		footnote citation element

            isHeading			heading

            isItemList			list (ordered or unordered)

            isListItem			list item

	    isNote			main note element (end- or footnote)

	    isNoteBody			note body (in end- or footnote)

            isOrderedList		ordered list (OOo only)

            isParagraph			paragraph

	    isSection			section

            isSequenceDeclarations	set of sequence declarations

	    isSpan			span element (see setTextSpan)

            isTable			table

            isTableCell			table cell

	    isTableRow			table row

            isUnorderedList		unordered list (OOo only)

=head3	Other element methods

        For a neater and more direct access to element types, see the
        getName method of XML::Twig::Elt. 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 table
	row. Remember that all the features of XML::Twig::Elt are
	available for any text container.

=head2	Properties

        No class variables are exported.

        Instance properties are the same as for OODoc::XPath, plus:

            'delimiters'	=> delimiter table

        hash giving the relation between element types and the delimiters to
        use when exporting text (see getText).

            'use_delimiters'	=> delimiter usage (see getText)

        indicates whether delimiters are to be used by getText or not when
        exporting text. Set to 'on' by default. Can be set to 'off' or
        another value to stop or limit use of delimiters.

            'heading_style'	=> default header style

        indicates the default header style to be used by element creation
        methods when no style is specified. Set to 'Heading 1' by default.

            'paragraph_style'	=> default paragraph style

        indicates the default paragraph style to be used by element creation
        methods when no style is specified. Set to 'Standard' by default.

            'field_separator'	=> field separator

        contains the character string to be used as the field separator when
        exporting tables. By default it is ";".

            'line_separator'	=> line separator

        contains the string to be used to separate lines when exporting
        "flat" text. By default, it is a line-feed ("\n").

	    'max_rows'		=> max table length (default 32)
	    'max_cols'		=> max table width (default 26)

	these 2 properties control the size of the "managed area" in a
	spreadsheet; the default "managed area" is the A1:Z31 rectangle,
	corresponding to the (0,0)-(31,25) coordinates; see getTable() and
	getTableCell() and normalizeSheet() for more explanations.

	    'expand_tables'	=> table transformation usage

	indicates whether the XML representation of the spreadsheets are to
	be expanded in order to allow the same cell/row addressing scheme
	as with the tables belonging to text documents; by default, this
	property is not set. If this property is set to 'on', the first
	access to any sheet will automatically trigger this transformation,
	so the explicit normalizeSheet() method will not be needed.
	However, this automatic (but costly) transformation has a drawback:
	it uses the same 'max_rows' and 'max_cols' values for every targeted
	sheet, whatever the really needed managed area for each one.

=head1	AUTHOR/COPYRIGHT

Developer/Maintainer: Jean-Marie Gouarne L<http://jean.marie.gouarne.online.fr>

Contact: jmgdoc@cpan.org

Copyright 2004-2008 by Genicorp, S.A. L<http://www.genicorp.com>

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

License: GNU Lesser General Public License v2.1

=cut