[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Question on key resolution for complex <topicmeta> content
I think this is correct, but as seems to often be the case lately, it's not what the spec says WRT elements with @href. From 2.1.3.4.3.3: "For elements that in addition to @keyref or @conkeyref do specify an @href attribute (such as author, data, data-about, image, link, lq, navref, publisher, source, topicref, xref, and their specializations), matching content includes all elements from within the key definition element that are in valid context within the key reference. Elements that are invalid within the key reference element directly or after generalization are not included or are filtered out." I suspect changing the words "key definition element" to "the linktext element within the key definition element's topicmeta element" would line the spec up with what Robert lays out below. I've long been flummoxed by this passage when it comes to processing text replacement for common xrefs, and I'm glad to hear that this isn't how it's supposed to work. The only reason I can think of for the above language is if the intention is for the body of a <topicref> with a @keyref to have its entire contents replaced by those of the key-defining topicref, but that's what conref/conkeyref is for, right? I also don't think mentioning @conkeyref in this context is appropriate, but that's a different, much less serious issue. Chris -----Original Message----- From: Robert D Anderson [mailto:robander@us.ibm.com] Sent: Monday, February 21, 2011 11:34 AM To: Su-Laine Yeo Cc: dita Subject: Re: [dita] Question on key resolution for complex <topicmeta> content Hi Su-Laine, I hear that Michael and I had a to-do to come back on this. We discussed it while looking at both the quoted spec passage [1] and the original, TC approved proposal [2]. Our analysis is based primarily on a few items: * Additional language in [1] that specifically defines "matching content" * Items 22 and 23 in the "Technical requirements" from [2] * Sample in Use Case 4 in [2] In both documents, there are two distinct categories of key based content substitution -- 1 for elements without @href, and one for elements with @href. For elements without @href - the specification says that "matching content is taken from the <keyword> or <term> elements within <keywords> within <topicmeta>". The first keyword or term is used if more than one is specified. Based on use case #4 in [2], and on previous discussion on the TC list, the intent was to use <linktext> as fallback. Based on processes elsewhere and on user expectations, it seems logical that <navtitle> should be a further fallback, but that is not specifically addressed. So, our understanding works as follows: 1. Take content from the first <keyword> or <term> within <keywords> within <topicmeta>. 2. If that is not found - the replacement text should be the full contents of the linktext element. The spec and proposal say that elements which are not allowed in the new context should be dropped; I think it makes far more sense to use a text-only version of the content. That is - if "This is <b>important</b>" goes into a context that doesn't allow phrases, it's better to use "This is bold" than to use "This is". But - that should probably be a clarification (or at least specifically allowed) in DITA 1.3. 3. If linktext is not found, the same rule can be applied to the full contents of <navtitle>. For elements with href - we understand that the matching content is meant to come from the linktext element, with the same rules about dropping or generalizing disallowed content. The specification states that for <link>, a <shortdesc> element in the key definition should become a <desc> element in the <link> element; I personally expect the same behavior to apply to <xref>. I think that navtitle is again a logical fallback when linktext is not specified. My own opinion is that DITA 1.3 should clarify the behavior for specific elements with href, so that some can be handled differently. For example - I think DITA 1.3 should state that <image> places content from linktext into <alt>. It could also allow author/@keyref to match an author element before falling back to linktext. These behaviors are not hinted at in either the proposal or specification, so I think the cannot realistically be added to DITA 1.2 as a fix or clarification. [1] http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/processing_key_ref erences.html [2] http://www.oasis-open.org/committees/download.php/26493/IssueNumber1207v 8b.html Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit From: "Su-Laine Yeo" <su-laine.yeo@justsystems.com> To: <dita@lists.oasis-open.org> Date: 02/07/2011 09:26 PM Subject: [dita] Question on key resolution for complex <topicmeta> content Hi everyone, It is not entirely clear to my team, either from the spec or from Eliot's Understanding DITA Keys and Key Spaces article, how keys should be resolved if the <topicmeta> element within a <keydef> contains complex content. The DITA 1.2 spec says: "When a key definition has a <topicmeta> subelement, elements that refer to that key and that are empty may get their effective content from the first matching subelement of the <topicmeta> subelement of the key-defining topicref... For elements that in addition to @keyref or @conkeyref do specify an @href attribute (such as author, data, data-about, image, link, lq, navref, publisher, source, topicref, xref, and their specializations), matching content includes all elements from within the key definition element that are in valid context within the key reference. Elements that are invalid within the key reference element directly or after generalization are not included or are filtered out." The first sentence says that the effective content is the "first matching" subelement in <topicmeta>. Does "first matching" "first element of exactly the same element type as the element which refers to the key," or does it mean something else? The second sentence seems to say that the effective content should include multiple elements from <topicmeta> if they are valid in element which refers to the key. E.g. say a <xref> element is resolved using a keydef, and that keydef contains the following subelements: <topicmeta> <shortdesc>My short description content</shortdesc> <keywords><keyword>keyword1</keyword><indexterm>indexterm1</indexterm></ keywords> <keywords><keyword>keyword2</keyword><indexterm>indexterm2</indexterm></ keywords> </topicmeta> Should the processor should resolve this as: Option 1: <xref></xref> Or should the processor resolve it as: Option 2: <xref> <keyword>keyword1</keyword> </xref> Or as: Option 3: <xref> <keyword>keyword1</keyword><indexterm>indexterm1</indexterm> </xref> Or as: Option 4: <xref> <keyword>keyword1</keyword><indexterm>indexterm1</indexterm> <keyword>keyword2</keyword><indexterm>indexterm2</indexterm> </xref> Cheers, Su-Laine Su-Laine Yeo Solutions Consultant JustSystems Canada, Inc. Office: 1 (778) 327-6356 syeo@justsystems.com --------------------------------------------------------------------- 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]