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: 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]