Hi everyone,
My FAQ item for key resolution for complex <topicmeta>
content will cover how keyref-bearing elements should be rendered, both in
cases where there is <topicmeta> in the key-defining element and cases
where there isn't.
In this FAQ item, I plan to include a reference to this additional
spec on keyref processing for the <abbreviated-form> element:
http://docs.oasis-open.org/dita/v1.2/os/spec/langref/abbreviated-form.html#abbreviated-form
It gives a set of rules for rendering <abbreviated-form>
when it resolves to a glossentry topic. These rules do not say anything about
what to do with <topicmeta> in the key-defining element. It also says,
"In situations where it refers to another topic type, renderers should
display the content of the referenced topic's title" with no mention of <topicmeta>.
I plan to say that in rendering <abbreviated-form>:
- Follow the rules in http://docs.oasis-open.org/dita/v1.2/os/spec/langref/abbreviated-form.html#abbreviated-form
- If these rules don't produce any content that can be rendered,
processors may follow general processing rules for elements with a @keyref
which cannot take a @href.
Please let me know if you expect the FAQ to say something
different.
Cheers,
Su-Laine
Su-Laine Yeo
Solutions Consultant
JustSystems Canada, Inc.
Office: 1 (778) 327-6356
syeo@justsystems.com
XMetaL Community Forums: http://forums.xmetal.com
For partners only: http://www.justpartnercenter.com
From: Su-Laine Yeo
[mailto:su-laine.yeo@justsystems.com]
Sent: Tuesday, February 22, 2011 7:32 PM
To: dita
Subject: RE: [dita] Question on key resolution for complex
<topicmeta> content
Actually, for
elements with a @keyref which can take a @href, the first rule for determining
replacement text should be to resolve the indirect reference as if it were a
direct one, right? E.g. say you have:
<map>
<keydef keys ="foo" href=""foo.dita">
<topicmeta><keywords><keyword>bar</keyword></keywords></topicmeta>
</keydef>
</map>
<topic>
...
<xref keyref ="foo"></xref>
...
</topic>
Then this should be resolved as if it were:
<topic>
...
<xref href = ""foo.dita"></xref>
...
</topic>
For example, if HTML output is generated, the hyperlink text should be the
title of the "foo.dita" topic. The way the spec is currently written
implies that the hyperlink text should be "bar". I believe what is
intended is for the hyperlink text to be "bar" if and only if the
keydef element doesn't resolve to a resource.
Cheers,
Su-Laine
-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
Sent: Monday, February 21, 2011 4:54 PM
To: dita
Subject: RE: [dita] Question on key resolution for complex <topicmeta>
content
Thanks Chris, Robert, and Michael. I concur with Chris about the
intention being different from what the spec says. Let's finish getting
this darned thing ironed out. Otherwise questions about this passage are
going to keep coming back to us every time a different developer tries
to implement keyref and we're going to feel like we're on a
time-travelling spaceship. I think what we need is the following:
Someone should own the task of doing a rewrite of the following
statement:
"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."
Then the TC should review and approve it. Then it can go into the keyref
FAQ and/or DITA 1.2 erratum.
As a question that might be easier to answer quickly, would the
following processor behaviour be considered compliant with DITA 1.2?
********************
For elements with a @keyref which cannot take a @href, determine the
element contents as follows:
- First choice: Use content from the first <keyword> or <term>
within
<keywords> within <topicmeta>.
- Second choice if there is no <keyword> or <term> in
<topicmeta>: Use
the contents of the <linktext> element in <topicmeta>.
- Third choice if there is no <keyword> or <term> or
<linktext> in
topicmeta: Use the contents of the <navtitle> element in
<topicmeta>.
- Fourth choice if there is no <keyword> or <term> or
<linktext> or
<navtitle> in <topicmeta>: Use the contents of the local element,
i.e.
the one with the @keyref on it.
For elements with a @keyref which can take a @href, determine the
element contents as follows:
- First choice: Use the contents of the <linktext> element in
<topicmeta>.
- Second choice if there is no <linktext> in topicmeta: Use the
contents of the local element, i.e. the one with the @keyref on it.
For elements with a @keyref which can take a @href and can also contain
a <desc> subelement, determine the contents of the <desc>
subelement as
follows:
- If <topicmeta> contains a <shortdesc> element, copy the contents of
the <shortdesc> into the <desc> element.
- If <topicmeta> does not contain a <shortdesc> element, and a
local
<desc> element already exists, use the contents of the local <desc>
element.
- If <topicmeta> does not contain a <shortdesc> element, and a local
<desc> element does not exist, do not create an empty <desc>
element.
When you copy content from <topicmeta>, include markup that is valid in
the new context. Strip any markup that is not valid in the new context.
********************
Cheers,
Su-Laine
-----Original Message-----
From: Nitchie, Chris [mailto:cnitchie@ptc.com]
Sent: Monday, February 21, 2011 10:46 AM
To: Robert D Anderson; Su-Laine Yeo
Cc: dita
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
---------------------------------------------------------------------
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