Yes, that markup is an edge case, but implementors will need to know what to do in those situations, since it's perfectly legal markup.
Chris
From: <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Monday, December 9, 2019 at 8:11 AM
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: Re: [dita] Variable key text and link titles
I'm coming late to the party. Of the three options that you outlined, I prefer #1 -- especially if we name the new element something more along the lines of <variableText>.
My rationale for the name:
-
Variable text is the term most commonly used in technical writing for text that needs to vary based on context.
-
Keys are a DITA architectural feature.
-
User-centered design tells us to focus on user goals and terminology, rather than features of an application or architecture.
My question about option #1: Do you think the markup sample is representative or an edge case? From a user perspective, it seems an edge case. In the live, I have not yet seen a key definition with both an @href and text specified within <topicmeta.>
While of course we need to cover edge cases, I think it's important to distinguish them as such, and be clear about what we expect to be common, non-edge case usage.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 12/4/2019 2:00 PM, Chris Nitchie wrote:
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.
--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php