#### 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