Re: [dita] Attempt to boil down the <titlealt> and <keytext> proposal discussion

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Excellent summary. One correction; for DITA 2.0, we already approved 
issue #21: Resolve inconsistent class values for shortdesc, linktext, 
searchtitle

https://github.com/oasis-tcs/dita/issues/21

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/10/2019 2:18 PM, Chris Nitchie wrote:
> Given some of the comments on today's TC call about these changes being confusing, I thought I'd try to boil things down. I hope this helps.
>
> DITA 1.x has two alternate title elements:
>
> - <navtitle> - the title to use for navigation (e.g. tables of contents, indexes)
> - <searchtitle> - the title to use for search results.
>
> These elements occur in two places. Inside topics, they appear inside <titlealts>; inside maps, they appear inside <topicmeta>.
>
> Those are the only alternative titles allowed. If you want to add others, you have to hack them into your grammar structure somehow using some other element as a specialization base. In Bookmap, <mainbooktitle> and <booktitlealt> are specialized from <ph>, which works for authors but is a headache for tools, which generally operate on the base vocabulary. To many tools, a bookmap title looks like a single long title with a bunch of phrases, not a main title and series of alternate/sub-titles.
>
> So the initial proposal was really quite simple.
>
> 1. Introduce a new <titlealt> element with a title-role attribute identifying the role of the alternate title. This new element would be legal in the two places <navtitle> and <searchtitle> are legal.
> 2. Make <navtitle> and <searchtitle> specializations of <titlealt>.
>
> But as I got into the grammar files, I ran into a problem. The content model for <topicmeta> is, in part, "navtitle?, linktext?, searchtitle?", meaning <linktext> is allowed between our two alternate titles. To be backwards-compatible with that, we'd have to either make the new content model "titlealt*, linktext, titlealt*" (so that <navtitle> and <searchtitle> could appear before and after <linktext>), OR make <linktext> another specialization of <titlealt>. I decided, after conferring with some on the TC (and, honestly, without thinking through all the implications), to go with the latter.
>
> And this is where things start to go off the rails, because <linktext> is kind of a mess in DITA 1.x. For starters, it's actually two separate elements, with two separate @class attributes, one for maps ("- map/linktext ") and one for topics ("- topic/linktext ").
>
> The "topic" version is used as the label for manually-authored related-link elements.
>
>      <link href="whatever.dita">
>        <linktext>Text of the link</linktext>
>      </link>
>
> The "map" version actually does two separate jobs.
>
> 1. It provides the text (or the "alternate title") to use in generated <related-link> content, as in from parent/child/sibling links, or reltable links.
> 2. It is one of several ways a map author can specify variable text to insert inside empty key references to the keys defined on the enclosing <topicref>.
>
> The first problem is the name. The "alternate link title" element ("- map/linktext ") will be available inside topics, and so must have a separate element name from the "link label" element ("- topic/linktext "). That's relatively simple; we'll just call it <linktitle> ("- topic/titlealt altTitles-d/linktitle ").
>
> The second problem is what to do about the dual nature of "- map/linktext " as part of this change. While its first usage - "text for generated links" - is pretty clearly an alternate title, "text for key references" really isn't. So I decided, again in consultation with others, to create one more new base element, <keytext>, to serve that secondary role from <linktext>.
>
> Unfortunately, in DITA 1.x, <linktext> is only one of several mechanisms by which map authors can specify key text. One impact of adding the new <keytext> element is that those other means - never all that great - can and should be factored down to a much simpler algorithm, namly: use <keytext> if present, then use <linktitle> (actually <titlealt title-role="linktitle">) if present, then use normal title determination (usually the title of the referenced topic).
>
> And that's how a simple proposal for extensible alternate titles wound up changing how keys work.
>
> Based on today's discussion, the following questions remain under discussion:
>
> - If there is no <linktitle>, should processors use <keytext> for link titles?
> - Do we need <linktitle> if we have <navtitle>? Is it realistic that a content architect would want different titles for ToCs and related links?
>
> I may be missing some other discussion points but those are the ones that stick in my mind. I hope this helps explain where we are and how we got here.
>
> 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.