2

My goal is to provide a link to the start of a major section of documentation, which begins with a <topichead> element as a section title only.

I could not figure out a way to do this via a conref. In the main map file sequence.ditamap, the <topichead> element is written as follows:

<topichead id="th_adding_usrs">
    <topicmeta>
        <navtitle>Adding a new user to the team</navtitle>
    </topicmeta>
    <topicref href="tasks/requests.dita"/>
    <topicref href="tasks/db_sets.dita"/>
    <topicref href="tasks/user_support.dita"/>
</topichead>
<topicref href="concepts/integration.dita"/>

The reference to the <topichead> th_adding_usrs occurs in the topic integration.dita.

From integration.dita, I tried putting conref="sequencing.ditamap#th_adding_usrs" inside of a <p> element and, then a <ph> element as well, but both still give me an error (I'm using the OxygenXML editor, v20.1) reporting that the Conref was not expanded, because it was unable to find target for conref="sequence.ditamap#th_adding_usrs".

I also tried an <xref> element inside of the <p> element above, with the conref attribute also as above, but get the same error.

Is it even possible to cross-reference (or otherwise provide a clickable link) to a <topichead> element?

And, more broadly, is there an advantage to using the <topichead> element over an actual <topicref> that has a title only and no content? I'm following the convention used within my company, but I'm not required to so. So, if there's no advantage to a <topichead>, I'll just avoid using them in favor of a title-only <topicref>.

EtherealBug
  • 165
  • 11
  • Not sure I understand. I don't think it's legal to or conref to a map element (). You would have to to a topic or part of a topic. You can't conref from a topic to a element because a topic (, , , etc.) cannot contain a element. You have to conref from a

    to a

    , etc. Also, what version of DITA are you using? 1.2? 1.3?

     – markg Sep 24 '18 at 23:36
  • DITA 1.3 and you're right, you can't. The solution I posted below gets around that by assigning a key to the element so when using an elsewhere, you're calling the key and not the directly. – EtherealBug Sep 25 '18 at 14:21

1 Answers1

1

Adding keys to the topichead as well as the topicrefs allows the use of a keyref attribute inside of an xref element to link to the topichead.

So <topichead id="th_adding_usrs"> with a key added is <topichead keys=”adding_usrs” id="th_adding_usrs">, and the topic integration.dita with a key is .

Within integration.dita, using an xref like: <p>Refer to <xref keyref=”adding_usrs”/></p> links correctly.

EtherealBug
  • 165
  • 11
  • 3
    Additionally, I do think it's generally better to avoid topicheads in favor of topicrefs with a title only though, in spite of the convention used within my group previously. Especially because the topichead element may function oddly if publishing to an HTML file instead of a PDF. – EtherealBug Sep 24 '18 at 18:54