Adding a topicref with the topicID

[rdelong]

When I add a new topic reference (from the Insert Reference [topic reference] dialog) and select my file, I can't figure out how to also grab the target topicID of the file. The results in the topicref, look like this:

Code: Select all

<topicref format="dita" type="task" href="taskCreateNewUser.dita"/>

What I want to do is this:

Code: Select all

<topicref format="dita" type="task" href="taskCreateNewUser.dita#topicID"/>

I can see this target value in the dialog, but I can't select it to obtain the results that I want. How do I get this elusive topicID in my @href?

[Radu]

Hi Rick,

If in the target combo box you select the topic ID defined on the root topic element, Oxygen will not add the anchor to the @href value because according to the specification, both forms are equivalent:

http://docs.oasis-open.org/dita/v1.2/os ... ibute.html

so an @href without an anchor part will automatically point to the topic root element.

Regards,
Radu

[jerrypope]

I'm very new to oxygen and am only just now beginning to learn this tool. I've been messing with XML since the '98 and with DITA in particular since 2005. I have to admit, though, that not providing the option to add the ID seems a little presumptuous (if not arrogant) on the part of the oxygen creators. It should be an option IMO.

As a side note, many yrs ago, we would occasionally run into a rendering issue with the ToolKit if the ID was omitted. The solution to that issue was to include an ID in the topicref's @href for all maps. Including the ID became a standard practice on our team.

[Radu]

Hi Jerry,

This is the first time since we implemented DITA support in Oxygen (about 7 years ago) we have a complaint about this so we'll probably leave the default behavior as it is.
But I also understand your point of view. How about if we try to change the behavior of the dialog so that after an URL is selected, the ID targets combo box will initially select an empty entry and thus the default behavior will be kept but if as an end user you expand the drop down and explicitly select the target topic ID, we set that to the @href attribute value?

Regards,
Radu

[jerrypope]

Being able to select the topic @id, if desired, would be a good thing
Thanks Radu.

Jerry

[Radu]

Hi Jerry,

Ok, I will add an issue for this and when it gets resolved we'll update this forum post.
At some point you may want to reconsider your best practice of also adding the topic ID in the topicref. In this way, when you want to change the ID of an existing topic you also need to hunt for it in the entire DITA Map and change it in all references to that particular topic.

Regards,
Radu

[sorin_carbunaru]

Hello Jerry,

In version 18.0 we have implemented the possibility to add the topic ID to the topicref "href". There is a separate entry in the combo box that allows you to do this.

Regards,
Sorin Carbunaru
oXygen developer

[jerrypope]

Thank you!

FYI
In my earlier post, I should've included the following info as part of the rationale for us including @ids in all references:

We very likely will not be changing our "best practice" of including topic ids, even though (as Radu states) omitting topic ids in a reference makes it easier for authors to change @id values in the future. That's true. However, the business value of that freedom is tiny IMO.

The DITA spec says including the ID is optional. Because it's optional, it appears to be up to tool vendors whether the presence of an id is required. Over the years, we've run into several instances where not having an id causes errors--the tool vendor in those instances apparently says the ID is required.

If you stay fixed to just one vendor, I suppose a business rule of omitting topic ids would be fine. But, it you want to remain somewhat independent of a single vendor, my recommendation is to always include the topic id, even though the spec says it's optional.

My two cents.


At any rate, giving us the freedom to add a topic id is greatly appreciated.

Jerry Pope