Problem with key scopes

Post here questions and problems related to editing and publishing DITA content.
LAN101
Posts: 5
Joined: Thu Jun 13, 2024 5:15 pm

Problem with key scopes

Post by LAN101 »

Hello,
In my ditamap submap I have tried to use scoped keys as described in this example: https://www.oxygenxml.com/dita/1.3/spec ... -text.html
As you can see in this screenshot:
image.png
image.png (14.48 KiB) Viewed 649 times
The topics in this map reference reusable notes, which I have created in a reusable map with processing role resource-only. In the notes I have a keyref to "feature" and in the topics of my submap I want this key to be replaced by the keyword as defined in the key scope. For example, feature = notifications.
Even though it is correctly resolved in Oxygen XML Author. That is, I can see the correct word. When I publish the ditamap to webhelp, the words just do not appear.
image.png
image.png (15.81 KiB) Viewed 649 times
I have tried many many things, such as defining the keys in the referenced reuse map, or as part of the submap, or as part of the reusableNote.dita topic. It just doesn't seem to work.
I would really appreciate some help. Does anyone know what the problem is?
Thanks, Rosaria
Radu
Posts: 9343
Joined: Fri Jul 09, 2004 5:18 pm

Re: Problem with key scopes

Post by Radu »

Hi Rosaria,

Could you prepare a small sample DITA project exhibiting the problem and send it over along with steps to reproduce it?
https://www.oxygenxml.com/techSupport.html
We could take a look on our side and try to see what's wrong.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
LAN101
Posts: 5
Joined: Thu Jun 13, 2024 5:15 pm

Re: Problem with key scopes

Post by LAN101 »

Dear Radu,
I will.
In the new year ;-)
Kind regards
Rosaria
Radu
Posts: 9343
Joined: Fri Jul 09, 2004 5:18 pm

Re: Problem with key scopes

Post by Radu »

Hi Rosaria,
That's a good idea :)
All the best from the Oxygen team for the new year!
Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
LAN101
Posts: 5
Joined: Thu Jun 13, 2024 5:15 pm

Re: Problem with key scopes

Post by LAN101 »

Dear Radu,
the just sent the sample project.
Thank you for your help.
Kind regards,
Rosaria
Radu
Posts: 9343
Joined: Fri Jul 09, 2004 5:18 pm

Re: Problem with key scopes

Post by Radu »

Hi Rosaria,

Thanks for the samples!
Right now you are using in your project a mix of keys and direct content references.
I looked a bit over them, the publishing engine has two different stages, one when it resolves key references and one when it resolves content references. Because it first resolves key references and then content references, the key references inside your reusable content topics cannot be properly resolved at that early stage because the keys exist only inside their corresponding key scopes but the reusable topic is outside of that key scope. If the publishing engine would first resolve content references and then key references, this would probably work better for your case but for now the order of these steps is reversed.

As a possible way to make this work, whenever you define this key in your DITA Map:

Code: Select all

                    <keydef keys="feature">
                        <topicmeta>
                            <keywords>
                                <keyword>some value</keyword>
                            </keywords>
                        </topicmeta>
                    </keydef>
you would need to define an extra key also pointing to the reusable topic:

Code: Select all

<keydef keys="reusable_notes" href="reusables/reuse_notes.dita"/>
and inside your topics use conkeyref to refer to the note like:

Code: Select all

<note conkeyref="reusable_notes/note_view_or_edit"/>
Then you would no longer need to refer to the "reuse_notes.dita" separately from the reusables DITA map as it would be referenced in each particular key scope.
So you would need to change all conrefs to the reusable content which uses scoped keyrefs with conkeyrefs and define the key to the reusable topic file in each separate key scope.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
LAN101
Posts: 5
Joined: Thu Jun 13, 2024 5:15 pm

Re: Problem with key scopes

Post by LAN101 »

Dear Radu,
this works beautifully! :D
Just one more question: If I understand correctly, by adding the keyref to the reuse_notes.dita I do not need to include this dita topic in the reusables.ditamap. Correct?

Thank you very much.
Kind regards, Rosaria
Radu
Posts: 9343
Joined: Fri Jul 09, 2004 5:18 pm

Re: Problem with key scopes

Post by Radu »

Hi Rosaria,

One could also imagine two reusable note topics, one "fixed_reusable_notes.dita" referenced in the "reusables.ditamap" which contains notes which do not have keyrefs expanding to various values depending on the keyscope. And one "scoped_reusable_notes.dita" which is referenced with keydef in the various places in the DITA Map where you define the key scopes.
One thing to keep in mind though, such ways of reusing notes with small inline fragments are useful but they are also complicated to properly translate. Because when translating that initial English content to German you will have inside the reusable note a small island of variable content which gets replaced with either certain German words or other German words depending on the key scope. And joining words like this inside a paragraph in a particular order may just not make sense in all translated languages. So by achieving a maximum of content reuse you are decreasing the quality of the translated content.
So a general rule for being able to achieve high quality translations is to avoid having variable inline content (content inside paragraph like blocks) besides names of products:
https://blog.oxygenxml.com/topics/trans ... wt_rkp_rdb
Avoid reusing inline elements other than product names.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
LAN101
Posts: 5
Joined: Thu Jun 13, 2024 5:15 pm

Re: Problem with key scopes

Post by LAN101 »

Hi Radu,
thank you for the tip on having multiple notes topics. That's a great idea.
As for translation, I am aware of the problems the inline elements can cause and will have to be particularly cautious when using these reusable notes.
Kind regards,
Rosaria
Post Reply