OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Variable key text and link titles

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="x.dita">
    <linktitle>Link Title</linktitle>
    <keytext>Key Text</keytext>

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.



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.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]