Automatically switch root map based on open ditamap

[Carl]

I am working with different ditamaps in the Map Manager and I have different topics open. One annoying thing I've encountered is when I switch between ditamaps, I must also constantly remember to change the root map. If I don't, my open topics suddenly start showing a slew of "Key not found" as the references break.

Now, this is annoying enough for regular topics, but it's doubly worse when I also have my entire document open in the editor with resolved topics: when it shows all the "Key not found", it changes the pagination! Suddenly the page that I was viewing is no longer there--the pagination has jumped so that I am now looking at a different part of the document! At that point, changing the root map to the correct one doesn't help. While it restores the references and gets rid of the "Key not found" messages, it remains at the new point of the document. I must then manually page up to return to the point where I was viewing before.

While these actions alone are fairly minor, it really adds up if I'm jumping back and forth between multiple topics and multiple ditamaps. If OxygenXML had the ability to change the root map automatically when I select a different ditamap, that would really help.

[chrispitude]

Hi Carl,

Radu and I have had some conversations about "sticky" DITA map contexts. Here is the text from an enhancement request that I filed.

We actively employ Eliot Kimber's DITA "best practice" of defining a key for every topic, then using only keyrefs for within-book and cross-book references. With Oxygen's latest fixes to keyref-based reference insertion, this works much better!

However, Oxygen's global approach to map context presents some challenges.

• Because everything is now key-based instead of href-based, everything in the editing window gets flagged as unresolved (variables, cross-references, conkeyrefs, etc.) if the global map context is not correct for the currently edited topic.
• When working with topics from multiple books simultaneously, it is cumbersome to constantly switch the map context so that key-based resources resolve properly in the writer's current editing window of interest. More importantly, if you have two topics from different books open side-by-side, it is impossible for both topics to resolve their keys correctly.
• When we create cross-book references, we drag a topic from the source's bookmap (in the DITA Maps Manager) to the destination book's topic editing window. However, if the global map context is not set correctly, the new key reference is incorrectly scoped with regards to the destination.
• A Git commit can include updates from an arbitrary set of books. When doing a "compare differences" to see what's in someone's commit, the odds are that the global context will be incorrect for rendering the differences.

I would like to collectively come up with a solution to these difficulties.

My current thinking is as follows:

• Each topic editing window SHOULD have its own map context.
• When you open a topic from a particular map, that map SHOULD become the context for that editing window ("sticky" map context).
• Each editing window SHOULD provide a context drop-down that (1) shows the current context and (2) allows it to be changed.
• New topic windows opened by following a cross-book link with Ctrl-Enter SHOULD have the destination map as the context.
• When you "Copy" a topic or other resource in a source topic, then "Paste special > Paste as link (keyref)" in a destination topic, the keyref SHOULD be constructed considering the per-topic context+scope of each topic window.

This could be a feature that is disabled by default, thus preserving backward compatibility and preventing additional context UI from appearing in the topic editing window.

[Radu]

Hi Carl,

Thanks for the feedback, I added it on the same issue on which I added Chris's ideas. If we manage to improve on this in a future version we'll update this forum thread.

Regards,
Radu

[Carl]

Thanks, Radu. Chris has summarized the enhancement request well. Right now, it's unfeasible to work with ditamaps with different root maps simultaneously.

On a related issue, I never really understood keyrefs and the advantages of using them. Seems a lot more hassle to me when they keep breaking because of different root maps. In my project, I converted most of them to hrefs. Can you point me to a good resource that explains the benefits of using keyrefs? Oxygen's documentation on this is not very helpful, IMO. I checked YouTube and there are only a couple of videos on this.

[Radu]

Hi Carl,

I think there have been discussions in the past on the DITA Users List about keys versus direct linking, you can also start another discussion if you want by posting directly there.

If I were to describe this in one paragraph:
The advantage with keys is indirection, if in a topic I have a reference like this <xref keyref="targetkey"/> I can change the target reference to point to various resources depending on how the key named targetkey is defined in the DITA root map. So for each DITA root map my link can point to various places.

For the example above, if I would not use keys, I would need to have two links:
<xref href="target1.dita" audience="A1"/><xref href="target2.dita" audience="A2/>
and then use profiling/filters to show either one link or another.

So up to a certain point using profiling you can obtain similar results as using keys but the DITA topic's content is more complex to maintain.
But you can use key scoping only with keys and with key scopes you can reuse a single DITA topic with variable content in multiple places in a DITA Map:

https://blog.oxygenxml.com/presentation ... copes.html

Regards,
Radu

[Carl]

That is a good, concise explanation, Radu! It makes sense to me.

Ironically, it's much easier for me to comprehend your "if not using keys" example. Sounds natural to me. Maybe it's because this is how I did this before, prior to DITA!

[chrispitude]

I see in the DITA 3.5 release notes at

https://www.dita-ot.org/3.5/release-notes/

that

Code: Select all

dita

now allows additional resources, such as key-providing maps, to be provided on the command line. This would enable Oxygen to transform individual topics with the sticky context!

We've had many writers wanting to publish PDF Chemistry PDFs for individual topics, but they don't like that all the keyrefs become unresolved.

[Radu]

Hi Chris,

We'll probably integrate DITA OT 3.5 with Oxygen 23 (Autumn this year).
Actually if your writers already have Oxygen 22.0 installed, if the main DITA Map is already opened in the DITA Maps Manager and they open a DITA topic in the main editor area, the "Configure Transformation Scenarios" button from the main toolbar should have a preconfigured transformation scenario to publish the topic to PDF using CSS. That transformation scenario should also take into account the root map keys when resolving the topic contents. So with a couple of patches in the DITA OT bundled with Oxygen we did something similar with what's included in the stock DITA OT 3.5 distribution.

Regards,
Radu

[brohan]

Hi Carl,

Radu and I have had some conversations about "sticky" DITA map contexts. Here is the text from an enhancement request that I filed.

We actively employ Eliot Kimber's DITA "best practice" of defining a key for every topic, then using only keyrefs for within-book and cross-book references. With Oxygen's latest fixes to keyref-based reference insertion, this works much better!

However, Oxygen's global approach to map context presents some challenges.

• Because everything is now key-based instead of href-based, everything in the editing window gets flagged as unresolved (variables, cross-references, conkeyrefs, etc.) if the global map context is not correct for the currently edited topic.
• When working with topics from multiple books simultaneously, it is cumbersome to constantly switch the map context so that key-based resources resolve properly in the writer's current editing window of interest. More importantly, if you have two topics from different books open side-by-side, it is impossible for both topics to resolve their keys correctly.
• When we create cross-book references, we drag a topic from the source's bookmap (in the DITA Maps Manager) to the destination book's topic editing window. However, if the global map context is not set correctly, the new key reference is incorrectly scoped with regards to the destination.
• A Git commit can include updates from an arbitrary set of books. When doing a "compare differences" to see what's in someone's commit, the odds are that the global context will be incorrect for rendering the differences.

I would like to collectively come up with a solution to these difficulties.

My current thinking is as follows:

• Each topic editing window SHOULD have its own map context.
• When you open a topic from a particular map, that map SHOULD become the context for that editing window ("sticky" map context).
• Each editing window SHOULD provide a context drop-down that (1) shows the current context and (2) allows it to be changed.
• New topic windows opened by following a cross-book link with Ctrl-Enter SHOULD have the destination map as the context.
• When you "Copy" a topic or other resource in a source topic, then "Paste special > Paste as link (keyref)" in a destination topic, the keyref SHOULD be constructed considering the per-topic context+scope of each topic window.

This could be a feature that is disabled by default, thus preserving backward compatibility and preventing additional context UI from appearing in the topic editing window.

I think this is a good feature to have. I am new to Oxygen and my Context was set to a topic was set to something else other than <Current map> by mistake and I had a quite a tough time figuring out what the problem was. The error message that says something about key-based instead of href-based is not very intuitive as well.

[Radu]

Hi,
Thanks for the feedback, can you maybe post the entire error message that you considered to be unhelpful?
Regards,
Radu