Introduction

This page collects information about how the OpenDocument text file format records structure in the document. Also included is information about how structural information is displayed. Much has been filtered out, but it is my belief that this subset represents the core of document structure in the OpenDocument text format.

This information is found in the first comittee draft of the OpenDocument v1.2 specification, released on February 16, 2009. The purpose of this page is to provide background information relevant to how sequences work in OpenDocument.

Basic Concepts

An OpenDocument text file embodies a linear document structure. Content is "flat".  There is no "containment" mechanism by which a superior unit of organization contains its subordinates.  Division of the document into units of organization is accomplished by markers which indicate breakpoints.  

The breakpoints in an OpenDocument text file increment an implicit, multilevel counter which indicates the current section.  The value of this counter may be referenced in the document by a predetermined field.  This outline counter defines the current "chapter" and "subchapter" within the document. 

The number of levels present in the outline counter is arbitrary.  Breakpoints declare which level of the counter they increment.  At the "top level" of the document is level one.  Level one represents the most granular unit of organization present in the document.  Level two represents the unit of organization immediately subordinate to level one.  Likewise, level three is the immediate subordinate to level two, and so on. 

Whenever a given level is incremented by a breakpoint, all counters for subordinate levels are reset to zero.   Thus, a unit of organization is normally bounded by two breakpoints, where the second breakpoint increments a level less than or equal to the level incremented by the first.  Alternatively, a unit of organization may be terminated by the end of the document.

The value of the outline counter may be displayed in a variety of ways. Some common displays: letters of the alphabet (capital or lowercase), roman numerals, arabic numerals, etc. 

Breakpoint definition

Element <text:h>

The <text:h> element represents a heading in a document. Headings define the division structure for a document. A chapter or subchapter begins with a heading and extends to the next heading at the same or higher level.

Relevant Attributes

text:outline-level

The text:outline-level attribute specifies the level of the heading, starting with 1. Headings without a level attribute are assumed to be at level 1.

text:restart-numbering

The text:restart-numbering attribute specifies whether or not to restart the numbering of headings.

The default value for this attribute is false.

text:start-value

The text:start-value attribute specifies a value that restarts numbering at the current heading.

text:style-name

The text:style-name attribute specifies a style that must have the family paragraph. If a conditional style is applied, this attribute has the name of the style that was the result of the conditional style evaluation.

Bryce's note: This is how you override whether and how the chapter number is displayed: Reference a style with the appropriate settings. Failure to override means that the default is used.

Emitting the current outline counter value

To explicitly output the current value of the outline counter, a predefined field is used. 

Field: <text:chapter>

The <text:chapter> element represents a field that displays one of the following:

• The name of the current chapter

• The number of the current chapter

• Both the name and number of the current chapter

If this element is placed inside a header or footer, it displays the current chapter name or number on every page.

The <text:chapter> element has no child elements.

The <text:chapter> element may have text content.

Bryce note: It is unclear what the text content of <text:chapter> means or how it appears in the document.

Relevant attributes

text:display

The text:display attribute specifies the information that a chapter field should display. Supported values are:

• name

• number

• number-and-name

• plain-number

• plain-number-and-name.

text:outline-level

The text:outline-level attribute specifies the outline level to use. The <text:chapter> element displays the chapter number or title up to the specified outline level.

Global Specification of Outline Numbering

A special list style may be defined in an OpenDocument text file to control the numbering applied to all headings if those headings are not linked with styles which override the global setting.  As with all list styles in OpenDocument, a list style represents an aggregation of styles defined for every level in the list.

Element: <text:outline-style>

The <text:outline-style> element contains the elements that specify a style for each outline level.

An outline style is a list style that is applied to all headings within a text document where the heading's paragraph style does not define a list style to use itself.

The <text:outline-style> element may have the following child element: <text:outline-level-style>

Element: <text:outline-level-style>

The <text:outline-level-style> element specifies a style for each outline level.

The <text:outline-level-style> element may have the following child elements: <style:list-level-properties> 16.11 and <style:text-properties> 15.14.12.

style:num-format

The style:num-format attribute specifies a numbering sequence. The supported number sequences:

• Alphabetic: a, b, c, ... or A, B, C, ...

• Numeric: 1, 2, 3, ...

• Roman: i, ii, iii, iv, ... or I, II, III, IV,...

The value of this attribute can be "1", "a", "A", "i", or "I". For some elements, the attribute value also can be empty. In that case, no number is displayed.

If no value is given, no number sequence is displayed.

style:num-prefix

The style:num-prefix attribute specifies what to display before a number.

If the style:num-prefix and style:num-suffix values do not contain any character that has a Unicode category of Nd, Nl, No, Lu, Ll, Lt, Lm or Lo, an [XSLT] format attribute can be created from the OpenDocument attributes by concatenating the values of the style:num-prefix, style:num-format, and style:num-suffix attributes.

The style:num-prefix attribute can also specify a character before the value of a text:bullet-char attribute.

style:num-suffix

The style:num-prefix and style:num-suffix attributes specify what to display before and after the number.

If the style:num-prefix and style:num-suffix values do not contain any character that has a Unicode category of Nd, Nl, No, Lu, Ll, Lt, Lm or Lo, an [XSLT] format attribute can be created from the OpenDocument attributes by concatenating the values of the style:num-prefix, style:num-format, and style:num-suffix attributes.

The style:num-suffix attribute can also specify a character after the value of a text:bullet-char attribute.

text:display-levels

The text:display-levels attribute specifies the number of levels whose numbers are displayed at the current level.

The default value for this attribute is 1.

text:level

The text:level attribute specifies the level of an outline or number list style.

text:start-value

The text:start-value attribute specifies the first number of a heading item at the current level.

Element: <style:list-level-properties>

The <style:list-level-properties> element specifies the formatting properties for a list level.

The <style:list-level-properties> element may have the following child element: <style:list-level-label-alignment> 16.12.

See Also

• Top level: http://dita.xml.org/wiki/workspace-to-enhance-cross-referencing
• ODF Sequences: http://dita.xml.org/wiki/research-sequences-in-odf