Enhance DITA Maps Manager to copy/paste topicrefs using keyref instead of href

[chrispitude]

We are looking at using "warehouse books" in our flow. A warehouse book itself is not published, but instead it uses the full power of DITA map and topic expressiveness to organize reusable content for writers to peruse.

The great things about using a book to provide reusable topics are

• The book map itself provides key values for the reusable topics, and Oxygen defines key values for new topics automatically.
• There is no extra effort required to learn how to create warehouse topics; writers are already familiar with book creation.
• There is no extra effort required to micromanage warehouse topic filenames or directory structures; the DITA Maps Manager provides a logical view into the reusable content instead.

For example, here's a "warehouse book" that provides some reusable dog and cat topics:

image.png (4.34 KiB) Viewed 2236 times

And here's a regular book that references a topic from the warehouse book:

image.png (6.63 KiB) Viewed 2236 times

However, I have not found a writer-friendly method to add warehouse topic refefences in my regular production books. The DITA itself is easy to write by hand:

Code: Select all

<map>
    <title>My Book</title>
    <mapref href="REUSE/warehouse_book.ditamap" format="ditamap" keyscope="warehouse_book"
        processing-role="resource-only"/>
...
    <topicref keyref="warehouse_book.cat_topic_1" keys="cat_topic_1"/>
</map>

but if I copy and paste between books in the DITA Maps Manager, the topic references are pasted in href form instead of keyref form.

My enhancement request is, if topic references are copied/pasted in the DITA Maps Manager from book A to book B, and book A's keys are "reachable" from book B via mapref (scoped or not), then paste the topic references using keyref instead of href.

This is analogous to Oxygen's existing behavior for xrefs where it prefers keyrefs instead of hrefs when possible.

I'm attaching a small testcase.

warehouse_book_test.zip

(7.26 KiB) Downloaded 285 times

[chrispitude]

I should clarify my last statement - this is analogous to the behavior in Oxygen where you drag a topic in the DITA Maps Manager from book A into a topic editing window with a context of book B, and Oxygen automatically creates a keyref-based xref to the topic if the topic's book A key is reachable from the book B context:

warehouse_book_draganddrop.gif (124.83 KiB) Viewed 2232 times

I am basically asking for this "keyref smartness" to be extended to copy/paste of map entries.

[Radu]

Hi Chris,

I added an internal issue "EXM-46560 Drop topicref in another dita map to create keyref to the original" to find some time to look more into your request.
Maybe a special "Paste as reference" action may be needed to disambiguate between use cases, as right now we just copy paste the topicref (and all its descendants) between maps. When the reference is inserted you also seem to want to assign a new "keys" attribute on the topicref keyref, I think this would still need to be manually done.

Regards,
Radu

[chrispitude]

Hi Radu,

Thanks! A "Paste as reference" would be great. In fact, I've been thinking of filing a separate enhancement request for modifier keys for certain drag-and-drop operations, with the pointer changing to reflect copy or reference (similar to copy or shortcut in Windows). What do you think?

And yes, the keyref'ed topicref in book B to the warehouse book topic would also need its own @keys definition, so that cross-references in book B can properly refer to that instance of the topic.

[chrispitude]

Hi Radu,

We are able to insert keyrefs to warehouse book topics using Oxygen's "insert reference", then choosing either of the following to define a key reference:

image.png (21.69 KiB) Viewed 2184 times

then clicking this button to choose the key reference:

image.png (11.77 KiB) Viewed 2184 times

then choosing a key from the available keys:

image.png (13.39 KiB) Viewed 2184 times

This view shows all available keys (including non-topic things like variables), but it gets the job done for now.

Radu, what's the best way to get local-instance keys defined for such keyref'ed topicrefs too, whether drag-and-drop or via insert reference? Would we need a new preference for this besides the one in Preferences > DITA > Maps that says "Use the file name as the value of the 'keys' attribute"? I'm open to any algorithm you think is suitable here (resolving all the way back to the root href, using the topic title, reusing the base key name from a scoped keyref key, etc.). I guess we file a new enhancement request for this?

[Radu]

Hi Chris,

From what I remember on Windows if you drag and drop with the Ctrl-Shift keys pressed, this means "link", so maybe this would be a way to handle on our side the paste as reference.
About automatically creating @keys when a new topicref with keyref is inserted I'm not sure if it's appropriate for most people, maybe you also have cases when you just want to insert a topicref with keyref without creating also the key for it.

Regards,
Radu

[chrispitude]

Hi Radu,

I checked and the Windows convention is:

• Ctrl+Drag to copy (within same filesystem; this is the default across filesystems)
• Shift+Drag to move (across filesystems; this is the default within same filesystem)
• Alt+Drag to create a shortcut

so we could apply similar conventions where appropriate. (A map could be treated like a filesystem for the copy/move semantics.)

I tried an experiment with and without a local key definition for a keyref'ed topic:

Code: Select all

    <topicref keyref="warehouse_book.dog_topic_1"/>
    <topicref keyref="warehouse_book.dog_topic_2" keys="local_dog_topic"/>

When I drag-and-drop this topic into another topic in my book to create a reference, the first uses the scoped original warehouse key and the second uses the local key:

Code: Select all

        <p><xref keyref="warehouse_book.dog_topic_1"/></p>
        <p><xref keyref="local_dog_topic"/></p>

and both PDF and HTML5 publishing work correctly. So unless someone is multiply-instancing the same warehouse topic in their book, I think we should be okay with the current behavior!

[Radu]

Hi Chris,

Thanks for the extra details, I added them on the opened issue.
Have you tried copying a topic file from the Oxygen Project view (Ctrl-C) and then pasting it in a DITA Map opened in the DITA Maps Manager view?

Regards,
Radu

[chrispitude]

Thanks for the extra details, I added them on the opened issue.
Have you tried copying a topic file from the Oxygen Project view (Ctrl-C) and then pasting it in a DITA Map opened in the DITA Maps Manager view?

Hi Radu,

I tried just now. As long as the warehouse book is known via a scoped resource-only mapref, then topic files added from the Project view (via drag-and-drop or Ctrl-C, Ctrl-V) are created as scoped keyref'ed topics! This is good. Now we just need a way to access this logic from the DITA Maps Manager's view of the warehouse book.