Running Heads and Feet

(Chapter Field Improvements)

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Éric Savary	2004-05-19	Draft
Conforms to	N/a
Applies to	Writer
Task ID(s)	I20200, i16211
Category	Feature and bug fix

Abstract

The former “Chapter” field has been replaced by a new “(Reference to) Styles” field which improves the use of running heads and feet, provides more flexibility and customization options and insures a high compatibility level with the corresponding MS-Word field.

i-Team Members

	Name	E-mail Address
Specification Owner	Éric Savary	Eric.Savary@sun.com
User Experience	Frank Loehman	Frank.Loehmann@sun.com
Development	Henning Brinkman Andreas Martens Oliver Specht	Henning.Brinkman@sun.com Andreas.Martens@sun.com Oliver.Specht@sun.com
Quality Assurance	Éric Savary	Eric.Savary@sun.com
Documentation	Frank Thomas Peter	Frank.Thomas.Peters@sun.com

Approved for Implementation

	Approved by	Date
User Experience	Frank Loehmann	18.05.04
Development	Oliver Specht	18.05.04
Quality Assurance	Éric Savary	18.05.04
Documentation	Uwe Fischer	18.05.04
String Review	Pending	

Document Change History

Rev. Level	Change	Initials	Date
1.0	First draft	ES	2003-12-11
1.1	Submission for approval	ES	2004-04-21

Contents

Glossary	1

1	Motivation	2

2	User Scenarios	2

2.1	Scenario A	2

2.2	Scenario B	5

2.3	Scenario C	6

3	Goals.	6

4	Requirements and Dependencies	6

4.1	Requirements	6

4.2	Technical Dependencies	6

5	Competitive Analyzes	6

6	Detailed Specification	8

6.1	New “Reference to style” field	8

6.1.1	Dialog Description.	12

6.1.2	Behavior of the Styles field depending on its location and options	12

6.1.3	Special Cases	14

6.2	Import of the old OOo Chapter field	14

6.3	MS-Word STYLEREF field Import - limitations	15

6.4	Error Conditions	16

6.4.1	Description	16

6.4.2	Strings list	16

7	Future Tasks	17

8	Legal Issues	17

9	Notes	17

10	References	17

Glossary

Term	Description
"Chapter" field	Refers to the former OOo field which could be inserted from "Insert – Fields – Other – [Document]"
Running heads	Different headers for each page showing chapter information. They are normally used for 2 page book layouts.
"STYLEREF"	Refers to the MS-Word fields which inserts a reference to a style applied in the document (Insert - Fields)
"Reference to Style" or “Styles” field	Refers to the OOo field located in Insert – Fields – Other – [References] - Styles.

Motivation

The behavior of the "Chapter" field in headers and footer needed to be improved to meet user's expectations. It has been replaced by a new field “Styles” that improves compatibility and interoperability with MS-Word.

User Scenarios

Scenario A

Frank writes a documentation for an Open Source software.

In the header of the odd pages (left) he would like to see the chapter number and name which starts on the current page or which has started on the previous pages and continues on the current page.

In the header of the even pages (right) he would like to see the section (which is a sub-level of chapters) number and name which starts on the current page or which has started on the previous pages and continues on the current page.

To achieve this, he is using two different page styles ("Left" and "Right") with two different headers. He insert over "Insert – Fields – Other – [Document] – Chapter" a reference to the "Chapter" level ("layer 1" in the fields dialog) in the header of the left pages. The same way, he inserts a reference to the "Section" level ("layer 2" in the fields dialog) in the header of the right pages.

The Illustration 1 represents what he expects:

Illustration 1 Expected -The right page shows the section beginning on the current page

Unfortunately, OpenOffice.org shows a reference to the current chapter on the right page (Illustration 2).

Illustration 2 The current chapter is displayed instead of the beginning section

Frank is very disappointed but goes on writing and formatting his document until he finds out that the field of the right page only behaves correctly when the section starts at the first paragraph of the current page (Illustration 3)

Illustration 3 The reference is correct only when the section starts the current page

What happened?

The Chapter field did only retrieve the current chapter but couldn't get the chapter starting at the current page unless it was placed on the first paragraph of the page.

Scenario B

Liz has to review and complete Frank's work. She would like to be able to choose which section has to be displayed in the header: the first section or the last section on the page. For this documentation, she needs to retrieve the last section (Illustration 4).

Unfortunately, only the first one can be displayed (Illustration 5).

Illustration 4 Expected - Reference to the last starting section Illustration 5 Result - Reference to the first starting section

But she finds a workaround for this problem. She notices that the chapter fields can display the last starting section when placed in the footer (Illustration 6).

Illustration 6 Workaround - The Chapter field displays the correct section when placed in the footer

Liz can now display the expected information on each page but the layout of the document does not follow the writing guidelines (show the current section in the header)

What happened?

The chapter field only displayed the chapter/section they are placed in. In other word: the chapter field always "looks back" and cannot get any information about the following chapters.

Scenario C

Derek gets a Word document which has to be integrated to Liz' and Frank's documentation. This document also contains references to the current chapters/sections in the header. As he opens this Word document with OpenOffice.org, he notices that those chapter references disappeared. The header only contains contains the chapter name as plain text so, that "Chapter 1. ..." is displayed on every page of the document.

What happened?

Openoffice.org couldn't import the MS-Word fields (STYLEREF) which is a reference to a specific style.

Goals.

The first goal of this specification is to give more flexibility to running heads and feet which should be able to display a reference to an outline level starting anywhere on the current page (addresses Scenario A).

The second goal is to increase the flexibility running headers/feet (Scenario B) and improve the compatibility and interoperability with MS-Word (Scenario C).

Both goals have been reached introducing a new field type: Reference to styles (called “Styles”) which replaced the old Chapter field.

Requirements and Dependencies

Requirements

- MSInteroperability-MIB-07 (i20200)

Technical Dependencies

- MSInteroperability-MIB-07 (i20200)

- Cross-References Specification

Competitive Analyzes

Microsoft Word 2002/2003

Pros

Microsoft Word does not have a specific field for chapters but a field called STYLEREF which displays a reference to any specified style. Thus it can be use in header and footers to display the current chapter as a running head.

Illustration 7 MS-Word's STYLREF field can display the first sub section found on the current page... Illustration 8 ...or the last sub section.

Illustration 7 shows that the STYLEREF field can retrieve information about styles which are located anywhere on the current and not only at the very first paragraph (See Scenario A)

Illustration 8 demonstrates that the STYLEREF field can also search for the first occurrence of the referenced style starting from the bottom of the page.

Cons

Illustration 9 The first chapter only starts on page 3 but is already referenced on the previous pages.

The STYLEREF looks for the specified style throughout the document, which may lead to non sense situations when used as running heads. Here an example (Illustration 9): though the first chapter only starts on page 3, the field displays it already on the previous pages.

Illustration 10 MS-Word's Fields dialog, tab page 'StyleRef' – powerful but illogical UI

The StyleRef field knows a lot more useful options than the former OOo Chapter field. Unfortunately the use of check boxes (i.e. possible multiple choices) for very different options leads sometimes to non senses:

- it is possible to insert a paragraph number in a relative AND full context at the same time. Result: the relative context option overrides the full context option.

- it is possible to check both “paragraph number” AND “position of paragraph”. Result: a not very useful string gets displayed -> Ex: “Section 2.below”

Detailed Specification

New “Reference to style” field

The OpenOffice.org Chapter field looked for the next (in the header) or current (in the footer) specified Outline level. The new Reference to Styles field offers more flexibility and use comfort, allowing the user to choose between 3 types of reference displays, 2 number formats and 2 possible reference directions.

Illustration 11 Reference to Styles Dialog mock up - Paragraph, character and list styles are mixed in the same list box but can still be be identified

Illustration 12 Options of the "Style group" listbox Illustration 13 Options of the “Display” listbox Illustration 14 Options of the “Context” listbox

String list for Reference to Styles dialog mock up

Item	English	German	Comments
Listbox entry	Styles	Vorlagen	
Listbox entry	~Styles	~Vorlagen	
Listbox entry	Style ~group	Vor~lagengruppe	
Listbox entry	All styles	Alle Vorlagen	
Listbox entry	Applied styles	Verwendete Vorlagen	See Illustration 12
Listbox entry	Custom styles	Benutzte Vorlagen	See Illustration 12
Group label	Options	Optionen	
Label	Displa~y	~Dartellung	
Listbox entry	Paragraph text	Absatztext	
Listbox entry	Paragraph number	Absatznummer	See Illustration 13
Listbox entry	Paragraph position	Absatzposition	See Illustration 13
Label	~Context	~Kontext	
Listbox entry	No context	Kein Kontext	
Listbox entry	Relative context	Relativer Kontext	See Illustration 14
Listbox entry	Full context	Vollständiger Kontext	See Illustration 14
Check box	Suppress all non-~delimiter characters	Alle Nicht-~Trennzeichen unterdrücken	
Check box	Search from ~bottom of the page	Seite von ~unten nach oben durchsuchen	
Check box	Preserve formatting during ~update	~Formatierung bei Aktualisierung beibehalten	ES: maybe will not be supported

Item	English	German	Comments
Field content	above	oben	field content when the option "insert position of paragraph" is chosen
Field content	below	unten	field content when the option "insert position of paragraph" is chosen

Dialog Description.

A "Styles" entry has been added to the "Type" list box

The "Styles" listbox collates styles corresponding to the category defined in the Style group listbox . Style types (paragraphs, characters, lists) are identified using a bitmap in front of each entry (Illustration 11). The sort order of the entries is as following:
1. paragraph styles
2. character styles
3. list styles
It is for each type an alphabetical, ascending, not case-sensitive order.

A Style group (Illustration 12) listbox allows to filter the content of the Styles listbox with 3 options:
- All styles
- Applied styles
- Custom styles

The last part of the dialog offers display options:

The explanation of theses options will refer to a document sample containing following styles:

-------------------------

Header

-------------------------

Chapter 1. The First Chapter (-> Style "Heading 1", outline level 1, )

Section 1. The First Section (-> Style "Heading 2", outline level 2, )

Section 2. The Second Section

-------------------------

Footer

-------------------------

3 reference displays: insert paragraph text, number or position (Illustration 13)

Paragraph text (default): inserts the text of the reference.
Ex: “The First Section”

Paragraph number: inserts the paragraph number and delimiters
Ex: “Section 2.”
This display support 3 context options (Illustration 14) :

No context

Relative context

Full context

Those options define how the reference to the paragraph number is displayed depending of where the field has been inserted. See below

Paragraph position: the reference will display “below” or “above” relative to the paragraph.

Suppress all non-delimiter characters: this option trims the character before and after the numbering.
Ex: “Section 1” will become “1”

Search from bottom of page: looks for the referenced style starting from the bottom of the page. This option only works when the field is placed in a header.
Ex: the field is inserted in the header of the sample document. If this option is activated, field will show “Section 2” instead of “Section 1”.

Preserve formatting during update: retains character formatting applied to a field when this field is updated. ES: not sure we will support this....

Behavior of the Styles field depending on its location and options

The information displayed by the Styles field depends on its relative position to the referenced style but also on its location in the document. The sample document shows four possible locations: the header (A), the footer (B), on the document before the style (C) and in the document after the style (D).

-------------------------

Header (A)

-------------------------

(C)

Chapter 1. The First Chapter

Section 1. The First Section

Section 2. The Second Section

(D)

-------------------------

Footer (B)

-------------------------

The following table describes which information the Styles field shows in each one of those cases and depending on the options activated in the dialog. Provided, the referenced style is Heading 2:

Field location Option	Header (A)	Footer (B)	Before style (C)	After style (D)
Display: Paragraph text	“The First Section”	“The Second Section”	“The First Section”	“The First Section”
Display: Paragraph text [X] Search from bottom of page	“The Second Section”	“The Second Section”	“The First Section”	“The Second Section”
Display: Paragraph number Context: No context	“Section 1”	“Section 2”	“Section 1”	“Section 2”
Display: Paragraph number Context: Relative context	“Chapter 1.Section 1”	“Chapter 1.Section 1”	“Chapter 1.Section 1”	“Section 2”
Display: Paragraph number Context: Full context	“Chapter 1.Section 1”	“Chapter 1.Section 2”	“Chapter 1.Section 1”	“Chapter 1.Section 2”
Display: Paragraph number Context: Full context [X] Search from bottom of page	“Chapter 1.Section 2”	“Chapter 1.Section 2”	“Chapter 1.Section 1”	“Chapter 1.Section 2”
Display: Paragraph number Context: Full context [X] Suppress all non-delimiter characters [X] Search from bottom of page	“1.2”	“1.2”	“1.1”	“1.2”
Display: Paragraph position	“The First Section”	“The Second Section”	“below”	“above”

Table 1 - Display option depending on the context.

Special Cases

The Styles field may be used to achieve other tasks than displaying running heads and feet. In some cases the default behavior of the Styles field can conflict with user's expectations.

Ex1: The Style field is located on page 1 (in the text!). It refers to a heading style “Appendix” which only appears on page 7. Result: the field displays the content of the “Appendix” paragraph on page 1 though the reference is on page 7.

Ex2: A document with the same running heads (a reference to the Heading 1) on every page. Heading 1 only starts at page 7 but the field is placed on page 1.

Conflict: if the field of Ex2 would work the same as in Ex1, the document would display “Chapter 1” from page one on, which is not what the user expects. In this case, the OOo Styles field displays nothing.

For this reason, the Styles field – when placed in a header - will search for the specified style only on the current page.

Illustration 15 in header, the Styles field searches for the referenced style ont current page only.

Illustration 15 Shows the default behavior of the Styles field in headers:

The field searches for the corresponding style on the current page only and from top to bottom. If no such a style can be found on the page, the field searches on the previous page(s):

if there is no previous page or not such a style on the previous pages, the field shows nothing (see page 1 and 2 on Illustration 15).

if the style can be found on previous, it shows in the header (see page 4 on Illustration 15).

Ex3:

Illustration 16: inconsistencies may appear if the search for the referenced style does not respect the outline level hierarchy.

Illustration 16: the backward search for a sub style (see here on page 4, the level 2) should stop when reaching a style of higher level (see here on page 3, “Chapter2”) else the header would show inconsistencies (compare page 3 – showing “Chapter 2” - and page 4 - showing “Section 2” actually corresponding to the first chapter). In this case, the field remains empty.

Import of the old OOo Chapter field

The following table shows the field correspondence between the former “Chapter” field and the new “Styles” field:

Old 'Chapter' Field options	New 'Styles' field options
Chapter name	Display: Paragraph text
Chapter number	Display: Paragraph number Context: No context
Chapter number and name	2 fields will have to be inserted. One with following options: Display: Paragraph number Context: No context The other one: Display: Paragraph text
Chapter number without separator	Display: Paragraph number Context: No context [X] Suppress all non-delimiter characters

MS-Word STYLEREF field Import - limitations

Import of Word switches	Result in Ooo UI
no switch {STYLEREF <style_name>}	Display: Paragraph text
\l only {STYLEREF <style_name> \l}	Display: Paragraph text [X] Search from bottom of page
\n has priority on all switches and default is 'not context sensitive' {STYLEREF <style_name> \n}	Display: Paragraph text Context: No context
if \r+\w (doesn't make sense!) together -> keep \r {STYLEREF <style_name> \r \w}	Display: Paragraph number Context: Relative context
if \r + \p (doesn't make sense!) together -> keep first: \r {STYLEREF <style_name> \r \p}	Display: Paragraph number Context: Relative context
if \w + \p (doesn't make sense!) together -> keep \w {STYLEREF <style_name> \w \p}	Display: Paragraph number Context: Full context
If \n + \t {STYLEREF <style_name> \n}	Display: Paragraph number Context: Relative context [X] Suppress all non-delimiter characters
if \p only {STYLEREF <style_name> \p}	Display: Paragraph position

Error Conditions

Strings list

Item	English	German	Comments
Field	Error! Style not defined.	Fehler! Formatvorlage nicht definiert.	
Field	Error! Not a valid bookmark self-reference.	Fehler! Ungültiger Eigenverweis auf Textmarke.	
Field	Error! No text of specified style in document.	Fehler! Es wurde kein Formatvorlagenname vergeben.	

Description

Error! Style not defined

Appears when	Appears where	Disappears when
- Referenced style has been deleted after the field insertion. OR - Referenced style has been renamed after the field insertion.	As field content in the document.	- Style re-created or other style chosen in the field dialog. OR - Style name corrected or other style chosen in the field dialog.

Error! Not a valid bookmark self-reference.

Appears when	Appears where	Disappears when
- Field is formatted with the referenced style AND - The referenced style can't be found anywhere else in the document AND - The field option are one of those: * Insert paragraph text. * Insert position of paragraph.	As field content in the document.	- Other referenced style chosen. OR - style can be found in the document. OR - another display option is chosen.

Error! No text of specified style in document.

Appears when	Appears where	Disappears when
The referenced style is not applied anymore in the document.	As field content in the document.	Apply the style again in the document.

Future Tasks

<If there are features which couldn't be implemented but have to be implemented in the future. State these in here with a description why the feature couldn't be implemented right now.>

Legal Issues

<If there are any legal issues to deal with the should be described here. Legal issues could be for example we have to redistribute third party technology. This section can also contain links the Legal Review Tool.If the Specification will be published on OpenOffice.org this section has to be removed.>

Notes

ES1: Chapter style removed - I propose to remove the “Field – Others – [Document] – Chapter” because it would be redundant with the new “Reference to styles” field and can be “remapped” to this field when importing old documents.

ES2: The option “Preserve formatting during update” - option which can be found for (quite?) all MS-Fields. If we want to have it too, we should ask MIB if he intends to do so (he is owner of the Parent Q-PCD MS-Interoperability-MIB-07 - ”support most important MS fields” )

ES3: FYI DEV!, in Word 97, the STYLEREF field name was localized. So, it was called for instance “Vref” in German, “REFSTYLE” in French etc...

ES3: FYI DEV! STYLREF allows both writings:

{STYLEREF Heading1...} and {STYLEREF “Heading1”...} (“” must be used when style names contain blanks). Proposal: always use “” when exporting even if no blanks exist in the style name.

ES4: FYI DEV! If referenced style names contain a backslash (“\”) - valid name in OOo but not in Word – replace this backslash with a double backslash (“\\”) in the field code when exporting else Word will interpret a single backslash as a switch and will display an error message accordingly (“Style not found”).

References

<Give references to related documentation, such as engineering designs, technical specs, and other sources for related units. Also include links to documents that other sections in this spec need to refer to, such as user opinions usability test reports.>

ES: we could consider that when the option “search from bottom of page” is OFF, this would mean “search from top of the page (even if the field is located in a footer)”. This would allow the user to display the heading the page starts with in the footer.

It does not make any sense to display the position (“above”/”below”) of the referenced style in the header/footer. In this case, the option is ignored and the text of the paragraph is displayed instead. Word does it like that!

Required - Give references to related documentation, such as engineering designs, technical specs, and other sources for related units. Also include links to documents that other sections in this spec need to refer to, such as user opinions usability test reports.

Running Heads and Feet

Page 15

http://specs.openoffice.org/writer/numbering/running_heads_spec.sxw

Running Heads and Feet

Frank Loehmann

2003-12-11T12:25:11