Oxygen XML Forum

Posted: **Wed Jan 22, 2025 2:02 pm**

Hello,

we have recently changed most of our xref href references to keyref references. Now we realize that we cannot address the same elements of a topic. It seems that a an href recognizes all IDs within a topic, whereas a keyref is limited to the top level element only.
Example:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
<task id="c_agents_overview">
    <title id="tests">Agents overview</title>
    <shortdesc/>
    <taskbody>
        <context id="context_flk_vlw_psb">
            <note id="note_m2v_tpz_lcc" type="attention">.</note>
        </context>
    </taskbody>
    <task id="task_czk_s2v_c2c">
        <title id="title_hbz_s2v_c2c">Test</title>
    </task>
</task>

I cannot address any ids that are outside the top level task element, meaning the nested task at the bottom is not recognized, the task and title elements cannot be found:

Code: Select all

<xref keyref="keyscope.fileName/task_czk_s2v_c2c"/>

"Referenced ID path "c_agents_overview/task_czk_s2v_c2c" not found."
Why is that happening and how can I solve it? We want to keep addressing sub-contents (nested tasks, concepts or section elements) within a topic to be more precise in our referencing.
Thanks for the help!

Posted: **Wed Jan 22, 2025 2:38 pm**

Hi,
This is correct, according to the DITA 1.3 specification a key is defined to point to a topic and can refer sub elements from that topic, not from inner topics inside that topic. The DITA OT publishing engine may be more relaxed and not follow the specification on this but the Oxygen validation and editing does.
So for inner topics you would need to define separate keydefs like:

Code: Select all

<keydef keys="inner" href="path/to/fileName.dita#INNER_TOPIC_ID"/>

and then use those keys which point directly to the inner topic.

Regards,
Radu

Posted: **Sat Apr 05, 2025 4:49 pm**

Hi jrehahn,

I use the phrase "nested subtopics" to refer to subtopics defined within the same topic file as its parent topic. We are heavy users of these nested subtopics, because we like that the HTML structure seen by the user exactly matches the DITA structure seen by the technical writer.

In our flow, we define keyrefs directly inside map topicrefs, so our map syntax looks like this:

Code: Select all

<topicref href="topic.dita" keys="topic">
  <topicref href="topic.dita#subtopic1" keys="subtopic1"/>
  <topicref href="topic.dita#subtopic2" keys="subtopic2">
    <topicref href="topic.dita#subsubtopic" keys="subsubtopic"/>
  </topicref>
</topic>

Note that for HTML publishing, these explicit nested subtopic references are also needed so that the DITA-OT HTML transformations create TOC entries for them, as described here:

#4463: HTML5: nested topics do not appear in ToC

We have enhancement EXM-48539 filed for Oxygen to create/update these nested subtopic references automatically, as described here:

Update map to reflect nested subtopic structure

If you would find this useful, feel free to add your support in that discussion.

Oxygen XML Forum

Keyref to nested topic elements not working

Keyref to nested topic elements not working

Re: Keyref to nested topic elements not working

Re: Keyref to nested topic elements not working