Problem with key scopes
Post here questions and problems related to editing and publishing DITA content.
Problem with key scopes
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:
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.
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
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 (14.48 KiB) Viewed 648 times
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 (15.81 KiB) Viewed 648 times
I would really appreciate some help. Does anyone know what the problem is?
Thanks, Rosaria
Re: Problem with key scopes
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
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
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Problem with key scopes
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:
you would need to define an extra key also pointing to the reusable topic:
and inside your topics use conkeyref to refer to the note like:
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
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>
Code: Select all
<keydef keys="reusable_notes" href="reusables/reuse_notes.dita"/>
Code: Select all
<note conkeyref="reusable_notes/note_view_or_edit"/>
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
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Problem with key scopes
Dear Radu,
this works beautifully!
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
this works beautifully!

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
Re: Problem with key scopes
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
Regards,
Radu
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
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Problem with key scopes
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
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
Return to “DITA (Editing and Publishing DITA Content)”
Jump to
- Oxygen XML Editor/Author/Developer
- ↳ Feature Request
- ↳ Common Problems
- ↳ DITA (Editing and Publishing DITA Content)
- ↳ SDK-API, Frameworks - Document Types
- ↳ DocBook
- ↳ TEI
- ↳ XHTML
- ↳ Other Issues
- Oxygen XML Web Author
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Content Fusion
- ↳ Feature Request
- ↳ Common Problems
- Oxygen JSON Editor
- ↳ Feature Request
- ↳ Common Problems
- Oxygen PDF Chemistry
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Feedback
- ↳ Feature Request
- ↳ Common Problems
- Oxygen XML WebHelp
- ↳ Feature Request
- ↳ Common Problems
- XML
- ↳ General XML Questions
- ↳ XSLT and FOP
- ↳ XML Schemas
- ↳ XQuery
- NVDL
- ↳ General NVDL Issues
- ↳ oNVDL Related Issues
- XML Services Market
- ↳ Offer a Service