Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OODoc::Text(3)	      User Contributed Perl Documentation	OODoc::Text(3)

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

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.

   Methods
       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.

       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.

       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.

       appendItem(list [, text =_ text ,style =_ style ,[other_options]])

	       See appendListItem().

       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.

       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.

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

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

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

       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'
				       );

       appendTableRow(table)

	       See appendRow.

       autoSheetNormalizationOff()

	       Deactivates the automatic sheet normalization.

	       See autoSheetNormalizationOn().

       autoSheetNormalizationOn('full')

       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.

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

       bookmarkElement(element,	name [,	offset])

	       See setBookmark().

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

       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'.

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

       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.

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

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

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

       cellStyle(cell [, stylename])

	       Get or set the style of a table cell.

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

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

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

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

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

       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);

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

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

       columnStyle(column_element [, style])

       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.

       copyRowToHeader(table, rownum)

       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.

       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".

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

       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.

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

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

       deleteColumn(table, col_num)

       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.

       deleteHeading()

	       See removeHeading().

       deleteRow(table,	row_num)

       deleteRow(row_elt)

	       Deletes a given row in a	table.

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

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

       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.

       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");

       deleteTableColumn(table,	col_num)

	       See deleteColumn().

       deleteTableRow(table, row_num)

	       See deleteRow().

       expandSheet()

	       Synonym of expandTable().

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

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

       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".

       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.

       getCell()

	       Synonym of getTableCell().

       getCellParagraph(table, row, column)

       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.

       getCellParagraphs(table,	row, column)

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

       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.

       getCellValue(table, row,	column)

       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.

       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.

       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.

       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.

       getEndnoteCitationList()

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

       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".

       getFootnoteCitationList()

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

       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".

       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.

       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.

       getHeaderRow(table [, row_number])

	       See getTableHeaderRow().

       getHeadingText(n)

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

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

       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.

       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.

       getLevel(element)

	       See getOutlineLevel().

       getList(n)

	       See getItemList().

       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.

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

       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.

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

       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.

       getNoteElementList()

	       Returns the list	of the endnote and footnote main elements.

       getNoteList()

	       Returns the list	of the endnote and footnote body elements.

       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.

       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";
			       }

       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.

       getParagraphList()

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

       getParagraphText(n)

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

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

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

       getRowCells(table, row)

       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.

       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.

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

       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.

       getStyle(path, position)

       getStyle(element)

	       Obsolete. See textStyle().

       getTable(number_or_name [, 'normalize'])

       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.

       getTableByName(name [, 'normalize'])

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

       getTableCell(table, row,	column)

       getTableCell(table, coord)

       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.

       getTableColumn(table, column)

	       See getColumn.

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

       getTableList()

	       Returns a list of table elements	in a document.

       getTableRow(table, row)

	       See getRow.

       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.

       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");

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

       getText(path, position)

       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.

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

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

       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.

       getTopParagraph(n)

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

       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.

       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.

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

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

       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.

       insertHeading(path, position, options)

       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.

       insertItemList(path, position [,	options])

       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.

       insertParagraph(path, position [, options])

       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.

       insertRow(table,	row [, options])

       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.

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

       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.

       insertString(path, position, text, offset)

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

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

       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.

       insertTableColumn(table,	col_num	[, options])

	       See insertColumn().

       insertTableRow(table, row [, options])

       insertTableRow(row_element [, options])

	       See insertRow().

       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.

       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.

       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.

       normalizeSheet(sheet, rows, columns)

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

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

	       See normalizeSheet().

       outputDelimitersOn()

       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.

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

       removeBookmark(id)

	       See deleteBookmark().

       removeHeading(position [, level =_ level_no])

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

       removeHyperlink(path, position)

       removeHyperlink(element)

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

       removeParagraph(position)

       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.

       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.

       removeSpan()

	       See removeTextStyleChanges().

       removeTextStyleChanges(path, position)

       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.

       renameSection(section, newname)

	       Renames an existing section using the second argument.

       renameTable(table, newname)

	       Renames an existing table using the second argument.

       replaceText(path, position, filter, replacement)

       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.

       rowStyle(row_element [, style])

       rowStyle(table, row [, style])

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

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

       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.

       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.

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

       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.

       selectElementsByContent([context,] filter)

       selectElementsByContent([context,] filter, replacement)

       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.

       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;

       selectHyperlinkElements(url_filter)

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

       selectParagraphByStyle(stylename)

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

       selectParagraphsByStyle(stylename)

	       Returns the list	of the paragraphs using	the given style.

       selectTextContent(filter)

       selectTextContent(filter, replacement)

       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('.*');

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

       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.

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

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

       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 A<section>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...).

       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 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 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	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'
				       }
			       );

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

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

       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.

       setSpan()

	       Deprecated.

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

       setStyle(path, position,	style_name)

       setStyle(element, style_name)

	       Obsolete. See textStyle().

       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.

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

       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 A<section>6.2 and A<section>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 A<section>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"
			       );

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

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

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

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

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

       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.

       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.

       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.

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

       textBoxDescription(text_box, [, new_desc])

	       Gets or sets the	optional description (long label) of the given
	       text box.

       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.

       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.

       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.

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

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

       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".

       unlockSections()

	       Removes the write protection of every section in	the document.

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

       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.

       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'
			       );

       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.

   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.

       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)

       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.

   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.

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

       Contact:	jmgdoc@cpan.org

       Copyright 2004-2008 by Genicorp,	S.A. <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

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 2672:
	   Non-ASCII character seen before =encoding in	'A<section>5.1.4'.
	   Assuming CP1252

perl v5.24.1			  2010-04-02			OODoc::Text(3)

NAME | DESCRIPTION | AUTHOR/COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OpenOffice::OODoc::Text&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help