topicsetref support in relationship tables?

[tomjohnson1492]

Are topicsetref elements allowed in relationship tables? I'm getting processing errors when I do this. Here's what I'm doing. In a ditamap, I have the following:

Code: Select all

  <topicset id="topicset_time_interval_

rewards" href="time_interval_rewards_overview.dita" chunk="to-content">

        <topicref href="time_interval_rewards.dita"  toc="no"/>

        <topicref href="time_interval_player_criteria_rewards.dita"  toc="no"/>

      </topicset>

Then in a relcell in a relationship table, I refer to the topicset like this:

Code: Select all

   <topicsetref href="#topicset_time_interval_rewards"/>

The XHTML output shows this in the related information at the bottom:

Code: Select all

<a class="navheader_parent_path" href="#topicset_time_interval_rewards" title="#topicset_time_interval_rewards">#topicset_time_interval_rewards</a>

As you can see, the reference to the topicset never gets rendered into an HTML file at all. Is this a known issue, or am I configuring something wrong?

[tomjohnson1492]

In your documentation, I saw this:

Relationship tables can technically contain nested topicref elements (that form a hierarchy) within a relcell. However, you should avoid using this sort of construct.

http://www.oxygenxml.com/dita/styleguid ... ables.html

Can you expand on why this construct should be avoided? And how is it technically possible? Should I use something other than topicset?

[tomjohnson1492]

After researching this issue, I'm leaning towards the conclusion that relationship tables don't support nested content when the nested content has the chunk="to-content" attribute. Relationship tables like to work with individual units of content (i.e., discrete files).

One workaround might be to *abandon* the chunk="to-content" attribute in maps and instead pull together content through a ditabase topic, like this:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">

<dita>



  <concept conref="time_interval_rewards_overview.dita#concept_srl_2rj_xn" id="concept_3989_iuiuj"><title>Overview</title></concept>

 

  <task conref="time_interval_player_criteria_rewards.dita#points_reward" id="task_333_99"><title>Rewards that look at points at regular intervals</title></task>

  

    <task conref="time_interval_rewards.dita#rewards_repeatable" id="task_3399898"><title>Time interval rewards</title></task>



</dita>

The relationship table processes the ditabase file correctly. The only problem is that Oxygen inserts the related links after the first topic on the page (in this case, after "Overview"), so it looks funny.
I've also read that ditabase topic types are discouraged and should not be used, though I'm not sure why. It seems that chunking through maps is just another way of doing the same with conrefs in ditabase topics.

Can you comment on this workaround? Is there a way to have the related links section appear at the end of the last topic, rather than after the first?

[tomjohnson1492]

I've been told that the way to achieve what I want is by doing the following:

Code: Select all

    <topicref chunk="to-content" navtitle="Changing the tire">

      <topicref href=“changing_tire_overview.dita">

      <topicref href=“remove_the_tire"  toc="no"/>

      <topicref href=“inspect_the_tube"  toc="no"/>

      <topicref href=“insert_a_new_tube.dita"  toc="no"/>

      <topicref href=“reinstall_the_tire.dita"  toc="no"/>

    </topicref>

Then in the relationship table, link to the changing_the_tire_overview.dita topic rather than trying to link to a topicset ID. The only problem is that method inserts the related links element right after that first topic, like this: http://www.screencast.com/t/Vvp4jLJ6S

Apparently the only fix is to integrate an XSLT override so that the related links element comes after the last element in the merged topic.

I know you have a new version of Oxygen coming out. Is there any way you could squeeze in this override fix?

[Dan]

In fact any of the aggregated topics may be in relation with other topics from the map. This is why at the end of each topic content may be shown the "related links" section.

In your case only the first topic is in relation with others, so only this one will have the "related links" section after its content.

Unfortunately we cannot alter this behavior since it may affect other cases. Also, pay attention to what happens if you move all the related links into a single section. It may prove difficult for the reader to understand the relations if you merge all the related links from let say "insert_a_new_tube" and "reinstall_the_tire" in a single section at the end of the merged topic.

[tomjohnson1492]

Dan, thanks for your reply. I see that referring to the individual topics works all right, and it gives you more granular control in the reltable. However, DITA does have an element that is supposed to be used to refer to sets of topics. Topicset is used in the table of contents to refer to a set of topics that should be treated as one topic. The topicsetref element (which refers to topicset) works fine in the map when structuring the navigation, so why shouldn't it also be available in the reltable? The DITA spec says it can be used in reltables.

I'm guessing this is a bug with the way the DITA Open Toolkit processes DITA files, but it would be awesome if Oxygen provided a fix for it.

If you provided a fix for topicsetref in reltables, it wouldn't affect the processing for other files at all, right? Any chance you might do this?

[Radu]

Hi Tom,

Oxygen uses the open source DITA Open Toolkit project to publish DITA content to various output formats.

The DITA 1.2 specs about topicset:

http://docs.oasis-open.org/dita/v1.2/os ... l#topicset

states something like:

A <topicset> is similar to a source file that contains nested topics, in that the combination of topics constitutes a complete self-contained unit.

so it should and does behave in the output as if you refer to a single topic file which has nested topics inside. But those nested topics still exist and they may or may not have independent related links to other topics in the map.

So we are reluctant to make changes for this in the publishing engine's stylesheets. If you consider this a bug you can add it on the DITA OT bugs list:

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

along with a precise small example of how the DITA Map looks like and what precisely you want to obtain.

Regards,
Radu