Introduction

A sequence is an abstraction used to assign numbers to items of the same or similar type throughout a document.  This page summarizes how sequences are defined by the OpenDocument standard.  Much has been filtered out, but I believe this to represent a reasonably complete synopsis of the role of sequences in terms of both their function and their presence in an OpenDocument file.

The information on this page came from the first committee draft of OpenDocument Format v1.2, released Feb 16, 2009.

Basic Concepts

There are three primary aspects to the use of sequences in an OpenDocument text file:

1. Sequence declaration: Prior to use, a sequence must be declared.  The declaration of a sequence does not produce output in a document and is part of the "prolog".
2. Sequence use: By default, inserting a sequence field into the document increments the sequence variable and displays the result (which may be styled).  A formula may be provided which enables more complex sequences to be constructed.  Sequence fields appear in the caption of the exhibit.
3. Sequence reference: A sequence reference is a field which takes the sequence value from its target.  The sequence value is unaffected.

The OpenDocument implementation offers simple control over if and how the counter is reset.  It offers control over how the sequence value is translated to text (roman numerals, arabic numerals, or alphabetical).  It also allows the user to choose how a sequence reference is rendered to text.

Element <text:sequence-decl>

The <text:sequence-decl> element is used to declare sequence variables used to number items within an OpenDocument text document.

Note: Sequence variables are commonly used for sequential numbering. However, expression formulas can be included in sequence fields to support more advanced sequences.

text:display-outline-level

The text:display-outline-level attribute specifies the numbering of a sequence by chapter. This attribute specifies an outline level that determines which chapters to reference for the chapter-specific numbering. All chapters that are at or below the specified outline level reset the value of the sequence to zero, the default value. The chapter number of the last chapter at or below the specified outline level is prefixed to the sequence number. Choosing an outline level of zero results in a straight sequence of all sequence elements for that sequence variable.

text:name

The text:name attribute specifies unique name of a variable to be declared.

text:separation-character

The text:display-outline-level attribute specifies the character used to separate a chapter number from a sequence number.

If the value of the text:display-outline-level attribute is a non-zero value, a separation character may be specified. The default separation character is ".".If the value of text:display-outline-level is zero, this attribute must be omitted.

Ed. Note I know what is meant but have inserted this note in hopes of finding better language than “sequence number.”

Element <text:sequence>

Once a sequence variable has been declared, it can be used in sequence fields throughout the document. Most sequence fields simply increment and display the sequence variable. However, sequence fields can also assume a new start value at any given position in a document. This start value is computed using a formula which is contained in the sequence field. If a sequence field without a start value is added, the office application software automatically inserts an expression of the type variable+1.

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

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

Bryce Note: The significance of the text content is uncertain.

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.

Ed. Note: We probably need to use regexes here to express the supported schemes. And this should be the only place where they are defined.

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

text:formula

The text:formula attribute specifies the formula or expression used to compute the value of a field.

The formula should start with a namespace prefix that specifies the syntax and semantic of the formula.

Ed: Note: A reference how conforming/extended conforming spreadsheets documents must behave in regards to the formula specification must be added.

text:name

The text:name attribute specifies name of variable to display. Must match name of a sequence variable already declared.

text:ref-name

The text:ref-name attribute specifies the name for a sequence field that is the subject of a reference field. No two sequence fields can have the same reference name.

If the sequence field is not the target of a reference, this attribute can be omitted.

Ed. Note: Note Class has been move to after Reference Format.

Element <text:sequence-ref>

The <text:sequence-ref> element represents a field that represents a reference to a <text:sequence> element in a text.

The <text:sequence-ref> element has no child elements.

The <text:sequence-ref> element may have text content.

text:reference-format

The text:reference-format attribute specifies what information about the reference is displayed. If the reference format is not specified, the page format is used as the default.

All types of reference fields support the following values for this attribute:

• chapter: Displays the number of the chapter in which the referenced item appears.

• direction: Displays whether the referenced item is above or below the reference field.

• page: Displays the number of the page on which the referenced item appears.

• text: Displays the text of the referenced item.

References to sequence fields support the following three additional values:

• caption: Displays the caption in which the sequence is used.

• category-and-value: Displays the name and value of the sequence.

• value: Displays the value of the sequence.

References to bookmarks and other references support additional values, which display the list label of the referenced item. If the referenced item is contained in a list or a numbered paragraph, then the list label is the formatted number of the paragraph which contains the referenced item. If the referenced item is not contained in a list or numbered paragraph, then the list label is empty, and the referenced field therefore displays nothing. If the referenced bookmark or reference contains more than one paragraph, then the list label of the paragraph at which the bookmark or reference starts is taken.

Note: The list label of a paragraph, which is contained in a list or which is numbered, typically contains the number of the corresponding list level. Such a list label could also contain numbers of superior list level inclusive prefix, suffix and separator strings.

The following additional reference formats are supported by references to bookmarks and references:

• number: Displays the list label of the referenced item. To unambiguously identify the referenced item at the document position of the reference field, the list label content for as many superior list levels are added in front as are required to make the reference unambiguous. The required superior levels of the referenced item are the ones, which differ from the superior levels of the document position of the reference field.

  The list label of the referenced item may already contain numbers of superior levels. If this is the case, and if n is the level of the most superior level contained in the list label, then no list label content of superior levels smaller or equal than n are added.

• number-all-superior: Displays the list label of the referenced item and adds the contents of all list labels of superior levels in front of it.

  The list label of the referenced item may already contain numbers of superior levels. If this is the case, and if n is the level of the most superior level contained in the list label, then no list label content of superior levels smaller or equal than n are added.

  Ed. Note: The proposal said for “number” and “number-all-superior” that “no list label content of superior levels greater or equal than n are added.”. Obviously, this must read “smaller or equal”, because superior levels have smaller level numbers than the current one. Example: In “1.2.3”, “1” belingst to level 1, “2” to level 2, and so on.

• number-no-superior: Displays the contents of the list label of the referenced item.

text:ref-name

The text:ref-name attribute specifies the name for a sequence field that is the subject of a reference field. No two sequence fields can have the same reference name.

If the sequence field is not the target of a reference, this attribute can be omitted.

See also

• Top level page: http://dita.xml.org/wiki/workspace-to-enhance-cross-referencing
• Document structure: http://dita.xml.org/wiki/research-document-structure-in-odf