proposal for new reference formats for reference fields of typebookmark and reference

[Oliver-Rainer Wittmann - Software Engineer - Sun Microsystems<Oliver-Rainer.Wittmann@Sun.COM>]

Dear TC members,

this is a proposal for three new values for attribute
text:reference-format for reference fields of type bookmark and reference:

The new reference formats are:
- number-no-superior
- number-all-superior
- number

<define name="text-bookmark-ref-content" combine="interleave">
	<optional>
		<attribute name="text:reference-format">
			<choice>
				<value>page</value>
				<value>chapter</value>
				<value>direction</value>
				<value>text</value>
				<value>number-no-superior</value>
				<value>number-all-superior</value>
				<value>number</value>
			</choice>
		</attribute>
	</optional>
</define>


Thus, the following define - see sub-chapter "Reference fields" in the
ODF specification

<define name="paragraph-content" combine="choice">
	<element>
		<choice>
			<name>text:reference-ref</name>
			<name>text:bookmark-ref</name>
		</choice>
		<interleave>
			<ref name="text-common-ref-content"/>
			<ref name="text-ref-content"/>
		</interleave>
	</element>
</define>

will change to

<define name="paragraph-content" combine="choice">
	<element>
		<choice>
			<name>text:reference-ref</name>
			<name>text:bookmark-ref</name>
		</choice>
		<interleave>
			<ref name="text-common-ref-content"/>
			<ref name="text-bookmark-ref-content"/>
		</interleave>
	</element>
</define>


These new reference formats are used to display the content of the list
label of the referenced item, which is numbered, of a bookmark
respectively reference. If the bookmark/reference contains more than one
paragraph, the content of the list label of the paragraph, at which the
bookmark/reference starts, is taken.
[ Note:
   The list label of a paragraph, 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 new reference formats have the following meaning:

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


- number-all-superior: Displays the contents of the list label of
the referenced item and adds the contents of the list labels of
superior levels in front of it.
The list labels of a superior level is only added, if the number of this
certain superior level and the numbers of its superior levels aren't
already included in the list label of the referenced item. Thus, if the
list label of numbered paragraph on list level 3 equals <number of list
level 2>+"."+<number of list level 3>+".", the list label of superior
list level 2 *isn't* added in front, but the list label of superior
level 1 *is* added.


- number: Displays the contents of the list label of the
referenced item. Depending on the context, the reference field is in,
the contents of the list labels of superior list levels are added in
front, but only if the number of the certain superior list level and
the numbers of its superior list levels aren't already included in the
list label of the referenced item. Thus, if a numbered paragraph on list
level 3 is referenced, the list label of its superior list level 2 is
added, if the reference field is outside the block of this superior list
item.
E.g. Imagine you have the bookmarked a paragraph in your text document,
which is on the list level 3 of a certain list. The bookmarked paragraph
is numbered this the list label "ii.". Its superior paragraph on the
list level 2 is numbered this the list label "B." and the superior of
this paragraph is numbered with the list label "1."
It's paragraph Para_5, which is bookmarked in this example:
1. Para_1
	A. Para_2
	B. Para_3
		i. Para_4
		ii. Para_5
		iii. Para_6
	C. Para_7
2. Para_8
The reference field to the bookmarked paragraph Para_5 with new
reference format "number" could be now in several contexts (positions
in the text document):
(a) It's in paragraph Para_6. Then it will display "ii."
(b) If it's in paragraph Para_2, it will display "B.ii."
(c) And in paragraph Para_8 it will display "1.B.ii."

If the given example would be changed in a way, that the list
label of Para_5 would contain "(B)-ii." then we will got for context
(a) the display "(B)-ii.", for (b) "(B)-ii." and for (c) "1.(B)-ii."


If the referenced item isn't numbered, such a reference field will
display nothing.


Regards, Oliver.