Multiple instances of a topic in WebHelp output?

[MichaelDa]

Hi.

I have a use case that I am looking for a solution, but I do not know if it is possible in Oxygen Author. This is regarding WebHelp output in Author.

By default, if I reference the same topic (e.g. topic.xml) multiple times in a Ditamap, and then create WebHelp output, one instance of the output HTML file (topic.html) is created, with multiple parent topic links.

This is a problem in the following use case:

We have product installation instructions that span many topics. However, we have multiple installation scenarios to accommodate various conditions in customers' environments (different O/S versions, database software, etc.) We have one set of DITA topics that we put together in various orders based on the particular installation scenario. So, for example, if you have 10 instructional topics, Installation Scenario A might have Topics 1, 2, 3, 7, and 10, whereas Installation Scenario B might have Topics 2, 4, 5, and 6. These various scenarios are then compiled in one Ditamap and output in one single WebHelp project.

In this example, the problem arises if a user is looking at Topic 2. Topic 2 would have two parent topic links: one for Installation Scenario A, and one for Installation Scenario B. It is not obvious to users which parent topic link to click. (There are breadcrumb links, but we are finding that users do not understand the difference between these intuitively.) If they click the wrong parent topic link, they end up in the wrong Installation Scenario, and they are then lost.

What I want to be able to do is, when there are multiple references to a topic in a Ditamap, create multiple instances of the HTML output file for that topic, so that each HTML topic instance has only one parent topic link.

Is this possible with Oxygen Author?

[Radu]

Hi Michael,

The WebHelp plugin provided by Oxygen to the DITA Open Toolkit is largely based on the classic XHTML transformation.
We have similar problems in our user manual:

http://www.oxygenxml.com/doc/ug-oxygen/ ... ables.html

But there are two valid workarounds:

1) For each reference create a new topic file which makes a conref to the original topic file.

2) When you make the topicref in the DITA Map on the <topicref> element you can set a copy-to attribute which was designed for just such cases, you can read about it more in the DITA 1.2 specs:

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

What we've found out is that in order for the processing to be correct using copy-to, the value of the attribute needs to also contain the same folder path as the original value, like:

Code: Select all

<topicref href="concepts/springFlowers.xml" copy-to="concepts/springFlowers2.xml">

.....

Hope this helps.
Regards,
Radu

[Anuradha]

Hi,

I am using Oxygen XML Author v14.2. I am trying to use a single dita file in multiple instances to create multiple topics in the output using the 'copy-to' attribute. My user guide has multiple ditamaps, one within the other. When I use 'copy-to' attribute in the top-most level ditamap (parent ditamap), it's working fine and I get the desired output. But when I use the attribute in a child ditamap which is referenced in the parent ditamap, the topic with the 'copy-to' attribute shows a blank page in the webhelp output. I also get the error that the file is missing.


Could you let me know if I am missing something here?


Thank you
Anuradha

[sorin_ristache]

I am trying to use a single dita file in multiple instances to create multiple topics in the output using the 'copy-to' attribute. My user guide has multiple ditamaps, one within the other. When I use 'copy-to' attribute in the top-most level ditamap (parent ditamap), it's working fine and I get the desired output. But when I use the attribute in a child ditamap which is referenced in the parent ditamap, the topic with the 'copy-to' attribute shows a blank page in the webhelp output. I also get the error that the file is missing.

Does the value of the copy-to attribute point to the same directory as the href attribute of the topicref that is copied? If yes please send us some sample files for reproducing the problem: a sample parent DITA map, a child map and the topics included in the maps.

[Anuradha]

Hi,

I submitted the sample files in the URL http://www.oxygenxml.com/techSupport.html. This set contains minimum topics and content. Also, this is the folder structure that I need to maintain in my project. There are additional folders, of course, but they are not relevant to this query.

Please note the following:

In this sample set, 'teamforge-testlink-integration.ditamap' is the parent map.
You may notice that all the 'copy-to' attributes I have given in this ditamap work fine in the webhelp output.

Testplan.ditamap is the child map
The 'copy-to' attribute given to 'create-testcase.dita' in the child map doesn't work. If i didn't use 'copy-to', obviously it showed multiple 'Parent topic' links.

I tried giving the path too, that is, '/action/create-testcase.dita' but it didn't work either.

Thank you
Anuradha

[sorin_ristache]

Hi,

It is a bug in the DITA transformation which will probably be fixed in a future version of the DITA-OT toolkit. For avoiding the bug in the current version of DITA-OT and the current version of Oxygen, please use the same directory paths for all references to the topics that you want to copy using the copy-to attribute. That means you should keep both map files (teamforge-testlink-integration.ditamap and Testplan.ditamap) in the same directory (the directory of teamforge-testlink-integration.ditamap) and use the following in the parent map:

Code: Select all

    . . .

    <topicref href="action/create-testcase.dita" copy-to="action/1_create-testcase.dita"/>

    . . .

    <mapref href="Testplan.ditamap" format="ditamap"/>

    . . .

and the following in the child map:

Code: Select all

    . . .

    <topicref href="action/create-testcase.dita"/>

    . . .

    <topicref href="action/create-testcase.dita" copy-to="action/2_create-testcase.dita"/>

    . . .

[Anuradha]

Thank you for your help and suggestions.

Anuradha