DITA parameter onlytopic.in.map not working in Oxygen?

[cg.tw75]

Hi,

I originally posted a question about the parameter not working on the dita users yahoo group but I've done more investigations and I'm wondering if the problem may be Oxygen so I'm posting the question here, slightly differently.

I am using Oxygen 17.0 to produce webhelp and xhtml output. My problem is that changing the value of the "onlytopic.in.map" parameter just does nothing.

Let's say I have <topicref href="source.dita"/> in the ditamap, and the file "source.dita" has <xref href="destination.dita">XXX</xref> in it, but there is no <topicref href="destination.dita"/> in the ditamap. What I understand is :
- if onlytopic.in.map=no, in the output "XXX" will have a link on it, and if I click it destination.dita will be displayed.
- if onlytopic.in.map=yes, destination.dita will not exist in the output (it is not clear to me whether the toolkit is supposed to automatically remove the link formatting).

I thought that maybe there was a problem with my project, so I tested the scenario I'm describing above with the sample "flowers" project (just adding the link and the "destination.dita" file), and it still doesn't work.

Something else baffles me: what are the correct values for this parameter?
In the Oxygen interface, it is "yes/no". The generation log shows that it passes "-Donlytopic.in.map=yes" to the toolkit. The DITA-OT 1.8 documentation states that "yes" is a valid value. But in the OT files (e.g. in build.xml), it looks like the OT is expecting "true/false" instead of "yes/no". Could that be the issue? (And in the DITA-OT 2 documentation, the correct values are "true/false".)

Thank you for your help with this,
C.

[adrian]

Hi,

Oxygen just passes the parameter to the DITA-OT/ANT task, the issue in this case is the correctness of the parameter value.
There seems to have been a mistake in the DITA-OT 1.8 and earlier documentation regarding the onlytopic.in.map parameter:
https://github.com/dita-ot/dita-ot/issues/1488
The actual correct values for onlytopic.in.map seem to be 'true' and 'false'.

Oxygen detects and proposes the values for the onlytopic.in.map parameter as per the DITA-OT documentation/specs.
For DITA 1.8.x and earlier the possible (documented) values are (yes/no). So, since the documentation is incorrect, it won't work with either value.
For DITA-OT 2.x the documentation has been corrected, so the possible values for onlytopic.in.map are (true/false). Setting it to 'true' works.

If you select in Options > Preferences, DITA the Built-in DITA-OT 2.x option (or use a custom DITA-OT 2.x), you will be able to select the correct possible values for onlytopic.in.map (true/false) in a scenario. You can switch back to the Built-in DITA-OT 1.8 (or your custom DITA-OT) afterwards.

Regards,
Adrian

[cg.tw75]

Hi Adrian,

Thank you for your reply. I have made a few tests and I still have a problem, though:
- If I run an xhtml transformation outside of Oxygen (in command line), using a copy of DITA-OT 2.0.1 I downloaded from the internet, the parameter works (with "true/false").
- If I point to the same toolkit and run the transformation from within Oxygen, the parameter does not work. I can see from the log that the value passed is still "yes".

I tried 2 different methods to point to the 2.0.1 toolkit: 1. using the dita.dir parameter in the transformation scenario, 2. using the Options > Preferences command you described. I understood from your post that there was an automatic adaptation mechanism, but maybe it only works for "Oxygen versions" of the OT? I am using Oxygen 17.0: it looks like there is no buit-in version of DITA-OT 2 in it.
Also, pointing to a standard DITA-OT 2 doesn't help me, as I cannot build Webhelp from it with Oxygen 17.0 (as the OT doesn't know the plugin).

There is another point: when the parameter worked using the OT-2 in command line, I could see that it excluded the files I wanted, but also that it left the link formatting where there were links pointing to the excluded files: using the parameter caused dead links to appear). So, the standard OT-2 doesn't remove the formatting - but does Oxygen's version of OT-2 solve this problem? (I mean the built-in one that comes with Oxygen 17.1 or 18.)

I should mention something else. When I said that "with the external OT run from the command line the parameter worked", I meant that what worked was the case I described in my first post, with the <xref> links. However, the OT documentation says that onlytopic.in.map "Specifies whether files that are linked to, or referenced with a @conref attribute, generate output". I don't understand what case "referenced with an @conref attribute" refers to. In one of the files that are referenced in my ditamap I had <p conref="test_conref.dita#topic_hby_dgd_5v/my_id"/>. The file "test_conref.dita" was not referenced in the ditamap. Yet when I ran the successful transform, the contents of the conref did appear in the output. What am I misunderstanding?

Thank you again for your help!
C.

[adrian]

Hi,

The DITA options I mentioned in my previous post apply to v17.1 and later. v17.0 does not bundle DITA OT 2.x, but it supports it and will detect the parameter values from the chosen DITA-OT.

- If I point to the same toolkit and run the transformation from within Oxygen, the parameter does not work. I can see from the log that the value passed is still "yes".

After setting Options > Preferences, DITA, DITA-OT directory to point to your DITA-OT 2.x folder, when you edit (duplicate) a default scenario you should see the correct parameter values (detected). Set/Change the onlytopic.in.map parameter value at least once (to true) and save the scenario.

Also, pointing to a standard DITA-OT 2 doesn't help me, as I cannot build WebHelp from it with Oxygen 17.0 (as the OT doesn't know the plugin).

If you want to use DITA-OT 2.x with Oxygen I would recommend moving on to Oxygen v17.1 or later.

There is another point: when the parameter worked using the OT-2 in command line, I could see that it excluded the files I wanted, but also that it left the link formatting where there were links pointing to the excluded files: using the parameter caused dead links to appear). So, the standard OT-2 doesn't remove the formatting - but does Oxygen's version of OT-2 solve this problem? (I mean the built-in one that comes with Oxygen 17.1 or 18.)

You'll have to test for yourself with v17.1 (or 18), but if there's an issue with the content produced by that version of DITA-OT in the command line, it will most likely also be present in the transformation output produced from Oxygen with the same DITA-OT version. In some cases the WebHelp transformation tries to work around some known issues of the standard XHTML output.

Yet when I ran the successful transform, the contents of the conref did appear in the output. What am I misunderstanding?

I can't really comment on what the DITA-OT documentation means and what it should or shouldn't do in this case. Maybe ask on the DITA-OT users discussion list.

Regards,
Adrian

[cg.tw75]

Hi Adrian,
Thanks, it works now! I didn't realise I had to create a new scenario for the new parameters to be loaded.
You are right, I will post the other question somewhere else.
Thank you again for your help,
C.