Topics

Keyref/conkey ref conversion strategy - keyref all the things? #conref

Marsh, Ed
 

Hi all,
We have a help system with 2000+ topics. We're moving to a static site generator (Hugo), and I'm wondering about converting all of our xrefs into conkeyrefs. We have to re-architect our folder structure, so the xref links will be updated
anyway. I'm wondering if it's worth the effort when there are thousands of xrefs to other projects (dita files), as well as external links.

Is this something people have done? Is there an easy/automated way to do this?

Thanks!
Ed Marsh

Radu Coravu
 

Hi Ed,

I don't understand, do you want to convert indirect links (keyrefs) to content references (conkeyrefs)?
Can you give maybe an example with how the DITA content would look like before and after the conversion? And maybe explain why you want that?

Or do you actually want to convert direct links (using href) to indirect links (using keyrefs)?
For the latter I would use a custom XML refactoring XSLT script run with Oxygen XML Editor to change all hrefs to keyrefs:

https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/custom_operation_sample-x-tools.html

As an example an XSLT script which changes topicref hrefs with keyrefs:

https://github.com/oxygenxml/dita-refactoring-examples/tree/master/30%20Topicref%20Href%20to%20Keyrefs

I also did something similar (image hrefs to keyrefs) with a custom ANT build file:

https://github.com/oxygenxml/dita-refactoring-examples/tree/master/6.%20Image%20Href%20to%20Keyref

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/22/2020 9:53 PM, Marsh, Ed wrote:
Hi all,
We have a help system with 2000+ topics. We're moving to a static site generator (Hugo), and I'm wondering about converting all of our xrefs into conkeyrefs. We have to re-architect our folder structure, so the xref links will be updated
anyway. I'm wondering if it's worth the effort when there are thousands of xrefs to other projects (dita files), as well as external links.
Is this something people have done? Is there an easy/automated way to do this?
Thanks!
Ed Marsh

Marsh, Ed
 

Thanks, Radu. 

I want to convert direct links to indirect links using keyrefs. I'll try out your scripts today!

Ed.

Chris Papademetrious
 

Hi Ed,

I posted a similar question awhile back:


We are relatively new to DITA. Our writers have been adding cross-book links to their content (which is calling our bluff on finding a PDF/OLH solution to publish them properly!). As a result, we decided to use keyref cross-references for all topic references, both within-book and cross-book.

The easiest part has been the creation of the topic cross-references in Oxygen XML Author. Notably,

  • If you drag-and-drop a topic from the DITA Maps Manager into your editing window, Oxygen creates a keyref-based reference (if possible).
    • If the topic isn't reachable by keyref, Oxygen is smart enough to insert an href-based reference instead.
  • If you copy a topic (or other) element, then do a Paste Special > Paste as link (keyref), then Oxygen inserts a keyref-based reference to that element.
    • If the element isn't reachable by keyref, the tool issues an error dialog.
In both cases, Oxygen creates the scoped keyref properly if the reference is in another book's keyscope.

The hardest part has been getting writers to remember to create key values for new topics. If they don't, there's nothing to reference. I've filed an Oxygen enhancement request to automatically populate the key values of new topics, similar to how the topic filename and @id values are pre-set.

I wish there were a "Paste as link (keyref/href)" that would prefer keyrefs but fall back to hrefs. Then I would keep only that in the right-click context menu to guide writers to the best practice by construction.

 - Chris

Marsh, Ed
 

Thanks, Chris, this is exactly the discussion I'm looking for (though I wasn't quite looking for it then!).

We're moving from a bespoke DITA-to-Confluence system to a static site generator (Hugo). We have to refactor our links (and our file structure) and I'm hoping to take this opportunity to Keyref All The Things, just wasn't sure if this was the 'right' way to go.

I may be reaching out offline :)

I should also add a huge thanks to Radu who sent over an XSL solution.

Ed.

ekimber@contrext.com
 

If you can manage it, replacing all references from topics to other things (so conrefs, cross references, etc.) to use keys is the best way to go. Within maps it may or may not make sense to use keys, for example, from navigation topicrefs to separate resource-only keys for the topics, depending on your re-use patterns.

I've made a number of presentations over the years about using keys and you can find them all on SlideShare, including:

* https://www.slideshare.net/drmacro/ki-qi-key-the-way-of-dita-harmony-with-keys-and-key-references
* https://www.slideshare.net/drmacro/dita-reuse-challenges-and-response
* https://www.slideshare.net/drmacro/they-worked-before-what-happened-understanding-dita-crossbook-links

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 1/28/20, 9:18 AM, "Marsh, Ed" <dita-users@groups.io on behalf of Ed.Marsh@...> wrote:

Thanks, Chris, this is exactly the discussion I'm looking for (though I wasn't quite looking for it then!).

We're moving from a bespoke DITA-to-Confluence system to a static site generator (Hugo). We have to refactor our links (and our file structure) and I'm hoping to take this opportunity to Keyref All The Things, just wasn't sure if this was the 'right' way to go.

I may be reaching out offline :)

I should also add a huge thanks to Radu who sent over an XSL solution.

Ed.

Marsh, Ed
 

Hi Eliot,
I was studying your first link yesterday :) Will check out the remainder tonight.
Ed.

ekimber@contrext.com
 

Feel free to ask questions here.

An older paper I presented on key best practices suggests that you should always have resource-only topicrefs for your topics and then use those from the navigation topicrefs.

I've since refined that approach such that it's only really necessary when you have either a high degree of re-use of your topics or, for whatever reason, it's better for you to implement this pattern everywhere.

Otherwise, if you have relatively little reuse of topics within or across maps, the extra overhead of resource-only topicrefs just to then use navigation (normal-role) topicrefs to put those topics into the navigation tree is not justified. Just be sure that all your navigation topicrefs also have appropriate keys.

For topics that serve as resources for content reference, you should always use resource-only keys.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 1/29/20, 8:55 AM, "Marsh, Ed" <dita-users@groups.io on behalf of Ed.Marsh@...> wrote:

Hi Eliot,
I was studying your first link yesterday :) Will check out the remainder tonight.
Ed.

Marsh, Ed
 

Thanks, Eliot. 

We're moving to a static site generator (Hugo) where the folder/file structure determines the structure of the site. Because all of our links are currently xrefs, I thought this would be a good time to visit keyrefs, since the link paths will be different in this new configuration. It's going to be messy, but I'm guessing this is probably the way to move forward.

Appreciate input!
Ed.

Chris Papademetrious
 

Hi Ed, all,

Our writers use nested <topic> elements in some topic files to keep tightly-related content together. One pain point with "keyref-all-the-things" is that subtopics nested within topic files also require key definitions to reference them or their contents:

      <topicref href="fcdm/preface/about_this_user_guide.dita" keys="about_this_user_guide">
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id1" keys="audience"/>
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id2" keys="related_publications"/>
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id3" keys="release_notes"/>
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id4" keys="conventions"/>
      </topicref>

It's impractical for authors to keep their map up-to-date as they create and modify subtopic structure and content. We have a "map-fixer" utility, written in perl and compiled to a Windows .exe with Strawberry Perl, that is configured as an external tool in Oxygen. Users can run this "Map Updater" utility from the menu and it will scan their DITA files and update their bookmap as needed. (It also populates the text content of cross-book <xref keyref> elements with the target text.)

The utility has a couple specific references to our directory structure and specializations, but I can point those areas out. This whole approach is admittedly a quick-and-dirty hack to keep our writers writing, I'm happy to share it if anyone's interested.

 - Chris

Chris Papademetrious
 

I tripped across a complication with the keyref-all-the-things approach. :(

In DITA, a glossary is implemented as a specialized topic (<glossgroup>) that contains terms as nested specialized subtopics (<glossentry>). Unfortunately this means that the map must define @keys values for all glossary terms. :(  It's impractical to expect a writer to do this.

I'll ask our writers to use hrefs when referencing glossary terms, but I expect some pushback adding rules about requiring them to remember what kind of links to use where.

I wish DITA allowed ID-based references to subtopic elements nested within a topic, such as

<xref keyref="topic_key/subtopic_id"/>

as this still provides indirection value via the parent's key.

I found some discussion on this topic (hah!) in the comments section of


 - Chris

ekimber@contrext.com
 

Iit should be easy enough to generate the necessary map structure if the glossary already exists or have whoever is responsible for the glossary to do it as they add glossary entries.

Once you have created the topicref pattern for pointing to glossary entries, it shouldn't matter whether those glossary entry topics are managed as a standalone files or are subtopics within a larger glossgroup topic--the actual markup creation effort is the same (or at least it should be since the only difference is whether or not the href on the key-defining topicref has a fragment identifier pointing to the specific topic).

It is certainly the case that a lot of DITA design and tool implementation is predicated on managing topics as individual XML documents but that should never be a requirement.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/19/20, 10:21 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@...> wrote:

I tripped across a complication with the keyref-all-the-things approach. :(

In DITA, a glossary is implemented as a specialized topic (<glossgroup>) that contains terms as nested specialized subtopics (<glossentry>). Unfortunately this means that the map must define @keys values for all glossary terms. :( It's impractical to expect a writer to do this.

I'll ask our writers to use hrefs when referencing glossary terms, but I expect some pushback adding rules about requiring them to remember what kind of links to use where.

I wish DITA allowed ID-based references to subtopic elements nested within a topic, such as

<xref keyref="topic_key/subtopic_id"/>

as this still provides indirection value via the parent's key.

I found some discussion on this topic (hah!) in the comments section of

https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Cross_Referencing/c_Links_to_Glossary_Terms.html

- Chris

Chris Papademetrious
 

Hi Eliot,

It's "easy enough" to write a lot of scripts, but we're starting to accumulate a number of such scripts. I'm not trying to be negative, and I understand why the $key/$elt_id reference structure imposes this constraint. But many of my writers are nontechnical; if I switch from the WYSIWYG view to the XML view in Oxygen, you'd think I'm giving them a sneak peek into The Matrix! And as the champion of our move to DITA, I'm responsible for all automation to hide these sorts of details from them.

In my opinion, having keys map to files is handy, but requiring keys for subtopics in those files is a bit limiting. It would be nice to have the option to use a $key/$subtopic_id reference structure as well.

Enough wishful thinking. It's <glossentry> hrefs for now. Back to work!

 - Chris

ekimber@contrext.com
 

The problem I see with the convenience feature you're requesting is that it makes your key references dependent on the particular file (storage) organization of the topics, not on the map structure, which provides a layer of indirection between references from topics to keys and the storage details of the target resources. It would also result in ambiguity about the intended target of the key reference.

That is, a keyref like "my-gloss-group/gloss-entry-one" (where " gloss-entry-one" is the ID of a topic) would only work as long as the target topic (the one with the ID "gloss-entry-one") is a literal child of the topic bound to the key "my-gloss-group".

It would also be ambiguous with a keyref to an element *within* the topic with the ID "gloss-entry-one" (which would be valid per the DITA spec if otherwise ill advised). But there would be no way for a processor to know, from the keyref itself, whether the intended target was a topic with the ID "gloss-entry-one" or a non-topic element with that ID within the topic bound to the "my-gloss-group".

Likewise, if the individual glossary entry topics were broken out to their own XML documents, then the keyref would break, which largely undoes one of the values of keyrefs from topics, namely making the reference insensitive to storage details.

As a contributor to the DITA architecture I think I would have to object to the feature request on these grounds alone: it would violate a basic principle of the key mechanism simply to provide a convenience feature that is largely limited to this particular use case.

I'm sympathetic to the need for convenience but it feels like something better handled in the editor rather than at the DITA addressing level.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/19/20, 11:26 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@...> wrote:

Hi Eliot,

It's "easy enough" to write a lot of scripts, but we're starting to accumulate a number of such scripts. I'm not trying to be negative, and I understand why the $key/$elt_id reference structure imposes this constraint. But many of my writers are nontechnical; if I switch from the WYSIWYG view to the XML view in Oxygen, you'd think I'm giving them a sneak peek into The Matrix! And as the champion of our move to DITA, I'm responsible for all automation to hide these sorts of details from them.

In my opinion, having keys map to files is handy, but requiring keys for subtopics in those files is a bit limiting. It would be nice to have the option to use a $key/$subtopic_id reference structure as well.

Enough wishful thinking. It's <glossentry> hrefs for now. Back to work!

- Chris

Chris Papademetrious
 

Hi Eliot,

Describing it in terms of "conveniences" has helped my thinking along, thank you!

Would a DITA CMS update a map with glossterm keys? Maybe the problem is that I'm expecting CMS-like conveniences from a DITA editor or from DITA itself.

 - Chris

Joe Williams
 

At a previous job, we were doing content management without a CMS, and we relied on simple, consistent practices and enforcement to take care of things like naming files and @id's. Tony Self's book and the IBM DITA Best Practices book suggest a lot of simple things you can do that can save you a lot of effort. The writers might have some ideas about the best way to go about it, too, which might give them a greater sense of ownership over the process. Also, I have heard of organizations that caused themselves problems that could have been avoided because of a lack of clear, consistent practices even with a CMS. As Hackos and Rockley used to say, content management is about processes, not tools.