Re: [dita] Variable key text and link titles

["Robert D Anderson" <robander@us.ibm.com>]

I agree that I dislike option 2. I dislike it both as an implementor, and as someone who had to explain / rewrite all of the DITA 1.2 language around key resolution. The final wording in 1.2 was conditional, much like the #2 option below: look for matching element, otherwise if it's a linking element look at X but if not look at Y, and everything can fall back to Z. When presented with anything beyond the most simple examples, few people could reliably tell you how key text was supposed to resolve.

At the moment I prefer option 1 -- it feels simple. I think it makes sense that <keytext> (or whatever the eventual name) should be the first place you look for text that goes in the key reference. That seems intuitive and easy for to understand. Because it's a change from the current setup, it may not be obvious at first to long-time authors, but once they see the new markup it should be clear.

Option 3 really is the "just like today" option, except ... just a tiny bit worse. Just this morning I had to explain to someone that they could use <linktext> to hold text that was going to be pulled into both keyword and cmdname. Admittedly this was through a chat tool but I'm pretty sure there were some blank looks on the other end for a while. The blank looks will probably last a bit longer when you're advocating an element with "title" in the name.

Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3 specification
Marketing Services Center

E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA

Chris Nitchie ---12/04/2019 01:01:04 PM---I'm working through the changes to the alternative title proposal we discussed at this week's TC mee

From: Chris Nitchie <chris.nitchie@oberontech.com>
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Date: 12/04/2019 01:01 PM
Subject: [EXTERNAL] [dita] Variable key text and link titles
Sent by: <dita@lists.oasis-open.org>

---

I'm working through the changes to the alternative title proposal we discussed at this week's TC meeting, and I want to lay out some of the things we discussed and get some feedback.

Today, specifying variable text for text-based keys is done using the <linktext> element, which is being replaced by <linktitle>. Since a 'link title' isn't quite the same as variable text, we decided to split that feature out into its own base element (for now let's just call it <keytext>).

Thus, it would be possible for a topicref to specify both 'key text' and a 'link title'.

<topicref keys="someKey" href="">  <topicmeta>
    <linktitle>Link Title</linktitle>
    <keytext>Key Text</keytext>
  </topicmeta>
</topicref>

So given this topicref, what text should be used for key references?

<xref keyref="someKey"/>
<ph keyref="someKey"/>

I see a few options here:

1. <keytext> is used if present; <linktitle> is used if not. This is clean and relatively straightforward, but it may cause confusion to authors. Since both elements become cross-references to 'x.dita', shouldn't the <linktitle> be used? It also makes me question whether we actually need <keytext>.

2. Key definitions that are also references use <linktitle>; key definitions that are not use <keytext>. This resolves the issues with option 1, and might be more intuitive to users, but would mean that either <keytext> or <linktitle> will be meaningless depending on the presence/absence of @href. It also imposes additional processing complexity for implementors. (As an implementor, I hate this option.)

3. We don't add <keytext> and just use <linktitle>. Admittedly, it's semantically weird for cases where there is no @href. (If we consider a <topicref> with no @href a link to nowhere, as opposed to something that isn't a link, using 'link text' kind of makes sense, but feels like a weak justification.)

Option #3 is essentially the DITA 1.x solution we have now. I know we discussed getting away from that, but given the issues with options 1 and 2, I'm questioning whether we actually should.

Thoughts?

Chris

The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies and all attachments, so that Oberon Technologies can ensure such a mistake does not occur in the future.