Re: [dita] Question on key resolution for complex <topicmeta> content

[Robert D Anderson <robander@us.ibm.com>]

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_references.html
[2]
http://www.oasis-open.org/committees/download.php/26493/IssueNumber1207v8b.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