Pulling navtitles via keyrefs: difference in behavior between Author view and DITA-OT HTML output

[tonid]

Forgive me if this question may be simple, but our company only recently decided to go with DITA, and my path in this respect is just beginning. I tried googling, but my understanding of the terminology is still too limited to do it effectively.

I've come across a problem that I can't seem to be able to find an explanation for. It's a difference of behavior between Oxygen's Author mode output, and a generated HTML output (both from Oxygen and manually from DITA-OT).

To avoid inconsistencies in later translation and to manage file locations easily, I use keyrefs extensively in the following fashion (this is of course a simplification):

Code: Select all

=== cut ===

file1.dita

...

Press the <uicontrol keyref="button_submit"/> button to open the <wintitle keyref="window_explosion> window.

=== cut ===

As you can see, I want to avoid having to explicitly provide names of uicontrol and wintitle elements, and instead pull them from navtitles every time. The definitions in the ditamap are:

Code: Select all

=== cut ===

map.ditamap

<keydef format="dita" href="buttons/submit.dita" keys="button_submit" processing-role="normal" type="topic"/>

<keydef format="dita" href="windows/explosion.dita" keys="window_explosion" processing-role="normal" type="topic"/>

=== cut ===

And the files themselves:

Code: Select all

=== cut ===

submit.dita

...

<title>Submit button<title>

...

<navtitle>Submit</navtitle>

<searchtitle>Submit (button)</searchtitle>

=== cut ===

In the Author view in Oxygen everything is perfect. Names are pulled from navtitles and displayed. There are no errors or warnings when performing any verification. So I get:

Press the [button_submit]Submit button to open the [window_explosion]Explosion window.

However, in resulting HTML, I get:

Press the button to open the window.

whilst of course I would be expecting to get:

Press the Submit button to open the Explosion window.

Why? Is it something I'm doing wrong? Do I have to provide the navtitle in keydef itself? Can't it be pulled from the topic file? I would definitely rather avoid it due to translation and consistency reasons. We sometimes change labels in our software and I would then have to make sure the label is changed everywhere in every case, instead of just changing it in one location.

Your help would be greatly appreciated. I reckon I could of course try and get our developers to help me out and change the XSLT used for transformation, but I would think this shouldn't require a hack...

[Radu]

Hi,

Somehow in this case I would agree with the publishing.
There are two types of DITA elements which can use the @keyref attribute, some of them are link type elements like <xref> and <link> and some of them are not link type elements like <ph> or <uicontrol>.
The DITA 1.3 specs:

https://www.oxygenxml.com/dita/1.3/spec ... -text.html

your case is situation number (3) described there:

For elements that do not allow the @href attribute, content is taken from the first <keyword> element inside of <keywords> inside of the <topicmeta>.

So for your case with the <uicontrol keyref="button_submit"/> being a non-linking element I would expect the "button_submit" to be referenced like this in the DITA Map:

Code: Select all

<keydef keys="button_submit" >

    <topicmeta>

      <keywords>

        <keyword>Submit</keyword>

      </keywords>

    </topicmeta>

  </keydef>

This way of defining the reusable content directly in the DITA Map should work also when publishing.

I will add an internal issue, maybe we can modify the way in which we compute links in the Author editing mode to better reflect the publishing in this case.

Regards,
Radu

[tonid]

Thank you, Radu. Well, I guess since this is the way DITA defines it, I will be forced to have the actual name stored in several places.

Just a question however. The same document states

Otherwise, if <linktext> is specified inside of <topicmeta>, the contents of <linktext> are used as the effective content.
Note: Because all elements that get effective content will eventually look for content in the <linktext> element, using <linktext> for effective content is a best practice for cases where all elements getting text from a key definition should result in the same value.

Do I understand correctly, that if I use <topicmeta><linktext>Name</linktext></topicmeta> in my keydef, I should have the same result, because linktext is considered fallback independent of whether href is allowed?

[Radu]

Hi Tomasz,

Well, I guess since this is the way DITA defines it, I will be forced to have the actual name stored in several places.

There is nothing stopping you for reusing that key also from the topic title. So in the topic title you can have a <ph keyref="button_submit""/> instead of duplicating content in the title.

Do I understand correctly, that if I use <topicmeta><linktext>Name</linktext></topicmeta> in my keydef, I should have the same result, because linktext is considered fallback independent of whether href is allowed?

You should if the DITA Open Toolkit publishing engine worked properly. Unfortunately it does not, there is an opened issue for this:

https://github.com/dita-ot/dita-ot/issues/2014

We plan to release Oxygen 19 in a couple of weeks and Oxygen 19 should have a patch included with its DITA Open Toolkit publishing engine in order to remove this bug.

Regards,
Radu

[tonid]

Thank you again, Radu, for the tips!

However, an important suggestion to the Author mode. For less experienced writers, like me, I think it may be a good idea to not include any links in the author mode if these are not indeed links in the text.

See, due to my lack of experience with DITA, I assumed, that <uicontrol keyref="something"/> will result not only in pulling the title Something, but also in making it linkable in the output text (equivalent to <xref keyref="something"><uicontrol keyref="something"/></xref> or <uicontrol>).

Unfortunately, it does not seem to be the case, noob me . And now I will have to refactor a lot of pages to change this .

What lead me on was the fact that in the Author mode, the link next to uicontrol was clickable. I have no idea how to resolve this... Perhaps introduce an extra mode, similar to Author, call it Preview mode, and then have the output more like it would be after transformation?

[Radu]

Hi Tomasz,

The decision whether a @keyref becomes or not a link is covered here in the specs:

https://www.oxygenxml.com/dita/1.3/spec ... links.html

When a key definition is bound to a resource that is addressed by the @href or @keyref attributes, and does not specify "none" for the @linking attribute, all references to that key definition become links to the bound resource. When a key definition is not bound to a resource or specifies "none" for the @linking attribute, references to that key definition do not become links.

So what you expected was correct, as your keydef had an @href on it, you should have ended up with the uicontrol replaced with a link.
Unfortunately the DITA OT publishing engine has problems with this, for example I added a similar issue here:

https://github.com/dita-ot/dita-ot/issues/2025

so until then you should explicitly link with keyrefs using xref or link.

Indeed Oxygen always presents the keyref as a link (even when the keydef has no @href set on it). We do this usually to allow end users to navigate to the place where the key is defined but I understand the confusion. I will also add an issue on our side to reconsider this.

Regards,
Radu