Thanks, Jeff. That sounds good
to me.
"Referencing" is right, good
catch! I appreciate the two-step referencing (one from key reference to
key definition, the second from key definition to resource) , but I think the
distinction between key definition and referencing element might be enough. We
could expand it to "that element may be rendered as all or part of the content
at the location of the key reference" or perhaps better "that element may be rendered as all or part of the content in the
element with the key reference."
A key name is bound to resources
contained within a key definition created using the @keys attribute on a
<topicref> or <topicref> specialization in a map. The resources
included in the key definition may include items addressed by the @href
attribute such as a DITA map or topic, a non-DITA resource such as a graphic, or
an object specified by an external URI, other attributes on the <topicref>
element, and <topicmeta> content within the key definition such as titles
and other metadata. Which resources are actually used depends on the context in
which the key reference occurs.
When a key definition includes an
element within the <topicmeta> as a resource, that
element may be rendered as all or part of the content in the element with the
key reference. By this means, the referenced element can be used as a
variable, and the content of the resource provides a way to set the variable's
value wherever the key name occurs within the documents aggregated by the
map(s).
From: Ogden, Jeff [mailto:]
Sent: Wednesday, November 25, 2009 11:57 AM
To: Bruce
Nevin (bnevin); Eliot Kimber; Michael Priestley
Cc:
dita
Subject: RE: [dita] conref.dita editorial
review
Thanks. Here are some comments and questions about
the "general case".
I think Eliot switched to use "key name" in most places
where "key" was used.
This sentence:
A key is bound to the
resource addressed by the <topicref> or <keydef> in which it is
defined.
Might be better as:
A key name is bound to the
resource addressed by the <topicref> or <topicref> specialization
such as <keydef> in which it is defined.
Or even:
A key name is bound to the
resource addressed by the <topicref> or <topicref> specialization
in which it is defined.
In
is rendered as the content of
the referenced element.
Shouldn’t “referenced” be “referencing”? This is
confusing because a key reference references the key definition and the key
definition may reference some other resource, but in this particular case the
content is inserted into or replaces content from the element that contains
the key reference which is the referencing element.
Bruce asked:
> can a key be bound both to an element in the local
<topicmeta>
> and to the resource referenced by the @href
attribute in <topicref> or
> <keydef>, at the same time?
In the general key reference case it can. An
example would be <navtitle> within <topicmeta> within a key
definition that references a non-DITA resource using a URI. In the
specific case of conkeyref only the @href resource would be used. And if there
were no @href resource, the conref would be “disabled” and regular markup
before conref would be used. I tend to forget that key references can cause
things to be deleted or removed in addition to being overridden or
added.
So in the general case it isn't either/or between an
@href resource and <topicmeta> resources. Instead everything contained
within the key definition (the <topicref> itself and <topicmeta>
elements within the <topicref>) are available. The contents of the key
definition are used selectively as appropriate depending on the context in
which the key reference occurs.
So a reworded suggestion for the general case might
be:
A key name is bound to
resources contained within a key definition created using the @keys attribute
on a <topicref> or <topicref> specialization in a map. The
resources included in the key definition may include items addressed by the
@href attribute such as a DITA map or topic, a non-DITA resource such as a
graphic, or an object specified by an external URI, other attributes on the
<topicref> element, and <topicmeta> content within the key
definition such as titles and other metadata. Which resources are actually
used depends on the context in which the key reference occurs.
When a key definition
includes an element within the <topicmeta> as a resource, that element
may be rendered as all or part of the content of the referencing element. By
this means, the referenced element can be used as a variable, and the content
of the resource provides a way to set the variable's value wherever the key
name occurs within the documents aggregated by the map(s).
>
