dita — archive

Error in 1.2 / 1.3 key processing topic for link text

From: Robert Anderson <[email protected]>
To: [email protected]
Date: Tue, 20 Jan 2015 21:01:00 -0000

> Since we allow <ph> within <indexterm> in DITA 1.3, the use case of > getting the index term text via keyref is provided for. True - though (it pains me to acknowledge that) this means you can pull text into a phrase within an indexterm, but you can't use @keyref to pull in a term with secondary or tertiary entries. For example, in the key definition for "example": <keywords><indexterm>Primary<indexterm>secondary</indexterm></indexterm></keywords> If somebody uses this: <indexterm keyref="example"/> I'd bet that they expect the full primary/secondary entry to be pulled in. But, that said - if nobody has noticed noticed this before, it's probably not compelling enough for us to add a new rule at this point. You can still use conref or conkeyref for this case, if needed. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) Eliot Kimber <[email protected]> wrote on 01/20/2015 14:40:38: > From: Eliot Kimber <[email protected]> > To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC <[email protected]> > Date: 01/20/2015 14:40 > Subject: Re: [dita] Error in 1.2 / 1.3 key processing topic for link text > > I see that @keyref is allowed on <indexterm> (never occurred to me that it > actually is allowed). > > Since we allow <ph> within <indexterm> in DITA 1.3, the use case of > getting the index term text via keyref is provided for. So it's hard to > see using @keyref for complete index terms would have much value. It would > certainly be an open question as to what the processing effect would be in > the case where the keydef for a key used by <indexterm> pointed to a > topic: what could that possibly mean (since an index entry is already > implicitly a link to the point in the document where the index term > occurs). > > Cheers, > > E. > > ————— > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 1/20/15, 2:26 PM, "Robert D Anderson" <[email protected]> wrote: > > >Amended list of possible resolutions, though I'm not sure about how I > >feel about the new option (#4): > > > > > >1. > >Remove <term> from the language and examples. It can't break anything > >(term was never valid), just cleans up language. > > > > > >2. > >Change the text to read "<keyword> or <indexterm>". I don't think this > >matches the original intent and may give different key resolution results > >in DITA 1.2 processors vs DITA 1.3 processors. > > > > > >3. > >Add <term> as a child of <keywords> - suddenly the text is correct. I > >consider this a no-go, it's too late to modify content models, just > >including for completeness. > > > > > >4. > > > >Add a new rule just for indexterm, allowing indexterm to pull from a > >matching indexterm. This is not allowed today in 1.2 or 1.3 but is > >probably what somebody using @keyref on <indexterm> expects. Remove any > >mention of <term>, and every other non-linking element is left pulling > >from <keyword>. > > > > > >Thanks, > > > >Robert D Anderson > >IBM Authoring Tools Development > >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > > > >Robert D Anderson---01/20/2015 14:17:55---In DITA 1.2 and in the latest > >draft of DITA 1.3, we have text that explains how to pull text into an > > > >From: Robert D Anderson/Rochester/IBM@IBMUS > >To: DITA TC <[email protected]> > >Date: 01/20/2015 14:17 > >Subject: [dita] Error in 1.2 / 1.3 key processing topic for link text > >Sent by: <[email protected]> > >________________________________________ > > > > > > > >In DITA 1.2 and in the latest draft of DITA 1.3, we have text that > >explains how to pull text into an empty, non-linking element that uses > >@keyref. For example, > ><keyword keyref="prodname"/> or <term keyref="widget"/> > > > >The text has been cleaned up but the meaning is the same: > > * DITA 1.2: "For elements on which no @href attribute is available > >(such as cite, dt, keyword, term, ph, indexterm, index-base, and > >indextermref, and their specializations), matching content is taken from > >the <keyword> or <term> elements within <keywords> within <topicmeta>. If > >more than one <keyword> or <term> is present, the matching content is > >taken from the first of them. " > > * DITA 1.3: "If an element does not allow the @href attribute, > >content is taken from the first <keyword> or <term> element inside of > ><keywords> inside of the <topicmeta>. " > > > > > >Jarno just pointed out that <keywords> does not actually allow <term> -- > >so with the language above, replacement text can only come from > ><keyword>. Thus while the normative text is not exactly invalid, it's > >misleading / causing implementations to check for something that can't > >exist. We also examples that are invalid, because they show <term> as a > >child of <keywords>. > > > >The <keywords> element does allow <indexterm> -- but I'm as close to > >certain as I can be that the intent here was actually to match keyword or > >term. I don't think we ever want to pull text from <indexterm> in a key > >definition into <keyword> or <term> in a topic. > > > >I see the following options for cleaning up the language: > >1. > >Remove <term> from the language and examples. It can't break anything > >(term was never valid), just cleans up language. > > > > > >2. > >Change the text to read "<keyword> or <indexterm>". I don't think this > >matches the original intent and may give different key resolution results > >in DITA 1.2 processors vs DITA 1.3 processors. > > > > > >3. > >Add <term> as a child of <keywords> - suddenly the text is correct. I > >consider this a no-go, it's too late to modify content models, just > >including for completeness. > > > > > >Clearly, I favor option #1 as the easiest / only non-disruptive change, > >but I need TC signoff before making the update. > > > >Thanks, > > > >Robert D Anderson > >IBM Authoring Tools Development > >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > >