9.6.6 Limiting the scope of keydefs by branch

With named branches and branch PIs you can limit the scope of keydefs, and also determine whether global keydefs should be used as a backup to branch keydefs.

To give preference to keydefs in a named branch when resolving keyrefs in that branch:

[KeyOptions]
; UseBranchKeydefs = No (default, standard DITA 1.2 single key space
; for whole map), or Yes (within a branch, search for keydefs in the
; same branch before searching the global key space)
UseBranchKeydefs = Yes

When UseBranchKeydefs=Yes, if a named branch (always in a map) contains keydefs, if possible DITA2Go uses those keydefs to resolve keyrefs in that branch. If it is not possible to do so for a given keyref, or when UseBranchKeydefs=No, DITA2Go uses the normal DITA 1.2 keydef resolution precedence: top down, breadth first from the root map, first instance of the sought key prevails.

To restrict the use of branch keydefs to their named branch:

[KeyOptions]
; KeydefsOnlyWithinBranch = No {always retain keydefs in branches in
; the global key space), or Yes (exclude branch keydefs from the
; global key space when UseBranchKeydefs=Yes).
KeydefsOnlyWithinBranch = Yes

When KeydefsOnlyWithinBranch=Yes, the keydefs in any named branch are used only in that branch. When KeydefsOnlyWithinBranch=No, all keydefs in named branches remain in the global key space; however, they are used preferentially within their named branch, provided UseBranchKeydefs=Yes.

For example:

<chapter id="ditaval1" navtitle="Ditaval Selection and Flagging">
<?dtall branch="Original" ditaval="WindowsProps.ditaval" ?>
<topicref href="DITAProps.ditamap" format="ditamap" />
<keydef keys="OS" ><topicmeta>
  <linktext>Windows</linktext>
</topicmeta></keydef>
</chapter>

<chapter id="ditaval2" 
navtitle="Ditaval Selection and Flagging Revisited">
<?dtall branch="Revisited" ditaval="LinuxProps.ditaval" ?>
<topicref href="DITAProps.ditamap" format="ditamap" />
<keydef keys="OS" ><topicmeta>
  <linktext>Linux</linktext>
</topicmeta></keydef>
</chapter>

When a topic within the referenced map contains:

  <term keyref="OS"/>

that term becomes “Windows” in the first chapter and “Linux” in the second chapter.

Suppose that after the two keydefs in the named branches, the map contains:

<keydef keys="OS" ><topicmeta>
  <linktext>Solaris</linktext>
</topicmeta></keydef>

When KeydefsOnlyWithinBranch=Yes, this code in a topic that is not in a named branch:

<term keyref="OS"/>

yields “Solaris”. However, when KeydefsOnlyWithinBranch=No, the term becomes “Windows” (from the first keydef in the map).

Previous Topic:  9.6.5 Directing a content reference to the correct branch

Next Topic:  9.6.7 Directing a key reference to the correct branch

Parent Topic:  9.6 Scoping and filtering within maps

Sibling Topics:

9.6.1 Understanding the advantages of filtering in maps

9.6.2 Designating map sections as named branches

9.6.3 Reusing the same topics with different conditions

9.6.4 Directing a cross reference to the correct branch

9.6.5 Directing a content reference to the correct branch

9.6.7 Directing a key reference to the correct branch