Please use new spec.: http://specs.openoffice.org/writer/numbering/Direct_Cross_References_to_Headings_and_Numberings.odt

Insert Direct Cross References to
Headings and Numberings in Writer

OpenOffice.org 2.0 and StarOffice 8

Document - ID	Specification Owner	Last Change	Status
	Frank Loehmann	06/04/2004	Final
Conforms to	
Applies to	Writer
Task ID(s)	25072
Category	Feature

Abstract

Inserting a cross reference to a heading or a paragraph of a numbering in Writer is improved. Now a reference can be inserted directly by choosing the target heading or numbering from a list of all headings or numbered paragraphs of the current document.

i-Team Members (The specification owner is part of the i-Team)

	Name	E-mail Address
User Experience	Frank Loehmann	Frank.loehmann@sun.com
Development	Henning Brinkmann	Henning.brinkmann@sun.com
Quality Assurance	Éric Savary	Eric.savary@sun.com
Documentation	Uwe Fischer	Uwe.fischer@sun.com

Approved for Implementation

	Approved by	Date
User Experience	Frank Loehmann	03/08/04
Development	Henning Brinkmann	03/08/04
Quality Assurance	Éric Savary	05/06/04
Documentation	Uwe Fischer	05/03/04
String Review	Elizabeth Matthis	03.06.04

Document Change History

Rev. Level	Change	Initials	Date
1.0	First Draft	FL	02/06/04
1.1	Work on UFI's comments	FL	02/110/04
1.2	Move Hyper/Sel section into Forms spec. http://specs.openoffice.org/appwide/xforms/GUI_spec_part1.sxw	FL	02/11/04
1.3	Finalisation and Master Document cross references	FL	02/12/04
1.4	Move link to master document to future section	FL	02/18/04
1.5	Finalize Dialog Mockups	FL	03/08/04

Contents

1	Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	2

4	Requirements and Dependencies	2

4.1	Requirements	2

4.2	Technical Dependencies	2

5	Competitive Analyses	3

5.1	OpenOffice.org 1.1	3

5.2	Microsoft Word XP (2002)	4

6	Detailed Specification	5

6.1	Insert Direct Cross References	5

6.2	G11n	7

6.3	Error Conditions	7

7	Future Tasks	7

8	References	8

Glossary

Term	Description
Cross reference	A cross reference is a link to a certain point in a document. This link consists of a target anchor and the cross reference link itself somewhere in the text. The user can choose the link's representation from the following list: Page (number where the link target is) Chapter (number where the link target is) Reference Above/below As page style Category and number Caption text Numbering
Manual cross reference	The manual cross reference consists of a link target that has to be defined first and then linked in the text.
Direct cross reference	Direct link means that all possible link targets (illustrations, headings and numbered items) are listed and the user can directly create a cross reference in the text without defining the target before.
Master (or global) document	A master document consists of a master and one or more child documents. A child document contains text content and hard text formatting only. This content is linked as a section into the master document. The master document is used to format the content provided by the child documents and to insert indexes, define page, paragraph and text styles.

Motivation

Cross references to headings or paragraphs of numberings in OpenOffice.org 1.1 and below, could only be created manually in separate steps . Now cross references to headings and numberings can be set directly by selecting them from a list of all headings and numbered items of the current document and insert the reference in a single step. This is a usability improvement of this frequently used functionality.

User Scenarios

User A works on a long document. He frequently has to enter references to other sections, which are related to the current context in his text. To insert a reference, he chooses Insert - Cross Reference, but he could not choose the reference target in the Fields - References dialog directly. This is only possible for an illustration or bookmark in OO.org 1.1.

First he has to scroll thru his document to find the target section for his cross reference, if this is the first time he want to put a reference on it. Then he has to mark the heading text itself, name it in the dialog and choose Set Reference to define the new cross reference target. Then he has to scroll back to the position, were he wants to insert the cross reference and selects Insert Reference in the Fields dialog, choose the previously named reference target and insert the reference into his text.

Solution: Offer two new reference types: Headings and Numbered items. These new types show a complete list of all headings or numberings in the selection list box (like in the navigator). The user can choose the target and insert the reference to it into the text. OO.org sets the target automatically. The name field is obsolete for these two new types.

(Not OO.org 2.0) User B works with Master Documents. He want's to enter cross references into his child document, but the link target is not within the current child document. He tries to insert the reference like he is used to within normal Writer documents, but he failed.

(Not OO.org 2.0) Solution: OO.org Writer 1.1 is not able to set references across document borders. In OO.org 2.0 cross references can be set between child/master documents like normal cross references within a single document.

This raises a technical problem, because currently child documents do not know about their master document, nor do they know about other child documents. Furthermore the inserted references have to work in two different contexts because sometimes the text is a part of the child document and sometimes it is displayed as a part of the master document.

(Not OO.org 2.0) User C uses the Navigator to work on the document outline. He assumes that he can also insert a cross reference directly via drag & drop of a heading, but every time he tries it, a hyperlink or a copy is inserted into his document.

(Not OO.org 2.0) Solution: The solution of this issue is not that easy, because cross references can not be created for all types of objects shown in the navigator (i.e. graphics and tables without a caption). So this requirement is only a future task.

Goals

Improve usability and reduce amount of time needed to insert a new cross reference into a Writer document. Furthermore the cross references have to be used within master and child documents to improve the master document functionality.

Requirements and Dependencies

Requirements

Please see user scenario section for details.

Technical Dependencies

none

Competitive Analyses

OpenOffice.org 1.1

OO.org 1.1 offers many different types of cross references, but headings and numbered items are missing. References to those targets can only be set by creating the reference target manually.

Illustration 1 Insert – Cross Reference in OO.org 1.1

Furthermore the number of a numbered item or document outline from the link target can not be shown as a reference in the text.

Illustration 2 Editing a Cross Reference in OO.org 1.1

Microsoft Word XP (2002)

MS Word offers a possibility to insert cross references to headings and numbered items directly. Numbering is only shown if used in document.

Illustration 3	Illustration 4 Numbered item

Illustration 5 Heading	Illustration 6

Detailed Specification

Insert Direct Cross References

The new direct linking possibility allows to set a cross reference directly to every heading or numbering in the current document without marking the cross reference target before.For Headings

Now the Selection list box shows a list of all paragraphs which are formatted with an outline paragraph style or attribute (level 1-10) of the current document . The width of the selection list box has been increased and the width of Format/Name/Value has been decreased instead. This helps to see a bigger part of the paragraph to be referenced. The scrollbars are shown on demand and a tool tip with the heading text is shown, if the list box item is not fully visible.

Illustration 7 New Fields dialog tab page for References - Headings

The outline numbering shown in the Selection list box is only shown if it is also activated in the document itself.

String List

Item	English	German	Comments
Tab page	Cross-references	Querverweise	Was “References”; changed to match the menu item that calls this page and terminology of other products.
LIst box label	Insert reference to	Verweisen auf	Was “Format” under Insert - Cross-reference - References (list on the right); changed to similar terminology as used by other products

For Numbered Paragraphs

The Selection list box shows a list of all numberings in the current document. The scrollbars are shown on demand. A tool tip is shown, if the an list box item is not fully visible.

Illustration 8 New Fields dialog tab page for References – Numbered items

The numbering in the Selection list box is only shown if it is also shown in the document itself.

String list

Item	English	German	Comments
List box item	Headings	Überschriften	
List box item	Numbered items	Nummerierte Elemente	
Format List box item	Number	Nummer	
Format List box item	Number (no context)	Nummer (kein Kontext)	
Format List box item	Number (full context)	Nummer (voller Kontext)	
Format List box item	Reference text	Verweistext	

New Reference Formats

The following formats have been added to the numbered items, headings, normal insert reference and bookmarks:

Number

This format displays the paragraph number like its relative position in a numbered list.

A reference to paragraph 2.(b)(iii) from 2.(b)(ii) is shown as "iii" because both paragraphs are subordinate to paragraph 2.(b).

If the referenced paragraph is not subordinated to the one where the reference is inserted, the full numbering context is shown (i.e. “1.(c)(i)”).

Number (no context)

Shows only the number of the current paragraph without its relative position in the numbered list.

A reference to paragraph 2.(b)(iii) is shown as "(iii)," regardless of the context of the reference.

Number (full context)

Always displays the complete paragraph number i.e. “2.(b)(iii)”

For example, a reference to paragraph 1.(a)(ii) from anywhere in the document appears as "1.(a)(ii)". (If you're using LISTNUM fields, you can add the \w switch to set the Paragraph number (full context) option.)

G11n

There are no special requirements for CJK and CTL text.

Error Conditions

If a source of a reference could not be found (i.e. on updating the whole document), those fields display the following error messages.

String list

Item	English	German	Comments
Field text	Error: Reference source not found	Fehler: Referenzenquelle nicht gefunden	For cross references
Field text	Error: Bookmark not defined	Fehler: Textmarke nicht definiert	For bookmarks

Future Tasks

Open Issues

Cross reference “line number” as reference format??!

The following is not part of this current specification but could be used in the future.

Insert cross references via the navigator

Predefined Cross references like “see chapter # on page #” and the like

Cross References Between Master / Child Documents

In OO.org 2.0 cross references to Master Documents or other child documents are possible. The Fields – References dialog has a possibility to choose a Master Document. After choosing the Master Document,a tree view is generated displaying the master document and all his childs in hierarchical tree.

Illustration 9 Master and child document are displayed in a tree.

All documents are represented by their filename. ##FL: Do we need new doc icons?

If the global document also contains an outline this outline is also shown in the tree. ##FL: before the child documents or after?

##FL->HB: We need to describe the technical solution at this point. Link must be valid in child document and in the master document.

String list

Item	English	German	Comments
List box item	Master document	Globaldokument	

Notes

Tool tip in list box: ##FL: Do we want to show a tip help if a heading is longer than the view? ###UFI: Yes please, in all dialogs. Second step: make all dialogs resizable. FL: This feature already has a task ID: 88642. List boxes will optionally offer this feature, so we can use it here.

Done

References

none

First set the reference target and insert the reference to it in the text

Please see Type list box in screenshot for list of different types

This change is being implemented for OO.org 1.1. Please see following specification for more details:
http://specs.openoffice.org/writer/numbering/NumberingBullet2.sxw

Insert Direct Cross References to Headings and Numberings in Writer

Page 1

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

Frank Loehmann

2004-02-06T11:10:41