dita — archive

[Jeff Ogden]

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). >