15.5.1.2 Making cross references active and updatable

For Word output, by default DITA2Go converts cross references to hypertext links, then makes them act like cross references implemented as Word bookmarks:

[WordOptions]
; Xrefs = Standard (default, working), or None (plain text)
Xrefs=Standard
; XrefHyper = Yes (default, make xrefs work as hyperlinks) or No
XrefHyper=Yes
; LockXrefs = Yes (default, faster load)
;  or No (allow updating of xrefs)
LockXrefs=Yes

The default values for these settings have the following effects:

Xrefs=Standard

Changing the source text in Word, then updating the cross-reference field, changes the text in the reference.

XrefHyper=Yes

Clicking the reference in Word (Ctrl-clicking in Word 2003) takes you to the source of the reference.

LockXrefs=Yes

Updating a cross reference to reflect changes to the source text requires unlocking the reference first.

When Xrefs=None, cross references are converted to text, and are not updatable; but if XrefHyper=Yes, they work as clickable links.

When XrefHyper=No, cross references do not work as links; but if Xrefs=Standard, they can be updated to match the source text.

When LockXrefs=No, you can update all cross references in Word without unlocking them first. However, what you lose is accurate page numbers in references. If your cross references do not include page numbers, this does not matter. If your cross references do include page numbers, there is little to gain by setting LockXrefs=No, because all you save in Word is a single click to unlock a reference for updating.

Table 15-2 summarizes the effects of these settings.

Table 15-2 Effects of cross-reference settings in Word

Configuration settings

Cross references in Word

Xrefs=

XrefHyper=

LockXrefs=

Updatable?

Active link?

Page #s OK?

Standard
Yes
Yes

Unlock first

Yes

Yes

No

Yes

Yes

No

No
Yes

Unlock first

No

Yes

No

Yes

No

No

None
Yes
Yes

No

Yes

Yes

No

No

Yes

No

No
Yes

No

No

Yes

No

No

No

No

Note:  The former FieldHyper setting is deprecated (and is replaced by XrefHyper), but still works; the former Xrefs=Fields is replaced by Xrefs=Standard.

Referencing page numbers in different files

Word does not support page references for cross-reference destinations in a different file, so DITA2Go produces a workaround in Word output. If you display hidden text in Word after converting cross references, immediately following each heading you will see a (hidden) page number; this is a Word PAGEREF field that points to the main bookmark for the heading. The PAGEREF field is bookmarked also. This way, references to the heading from other files can include dynamically updated page numbers.

Previous Topic:  15.5.1.1 Understanding how DITA2Go converts cross references

Next Topic:  15.5.1.3 Weighing cross-reference behavior trade-offs

Parent Topic:  15.5.1 Converting cross references to Word

Sibling Topics:

15.5.1.1 Understanding how DITA2Go converts cross references

15.5.1.3 Weighing cross-reference behavior trade-offs

15.5.1.4 Omitting cross references from RTF output