Indirect referencing based on key references and key definitions to increase reusability of content.
This was originally proposed feature #40 (11040).
The current draft is based on an initial draft by Michael Priestley and is the work of an ad hoc subcommittee convened by Michael that includes: Michael, Jeff Ogden, Erik Hennum, Deborah Pickett; Ian Larner; Michael Gannon, Eliot Kimber, Robert Anderson, and occasionally Don Day.
Whenever a topic has a reference to other content, it makes the topic less reusable because of the dependency on the target being still available and still relevant. This proposal introduces a simple key-based redirection scheme that leverages existing attributes and map architectures to provide support for redirectable conrefs, topicrefs, xrefs, links, and other reference elements and attributes. It also provides a simplified architecture for managing variable or volatile content such as product names, which need to be easily swapped out when a topic is reused in new contexts.
Key definitions introduce global identifiers for resources referenced from a map. A key definition defines one or more keys and specifies the resource or resources to which the keys resolve. Map authors define keys using a topicref or topicref specialization that contains the new “keys” attribute. Keys resolve to the resources given as the href value on the key definition topicref element, to content contained within the key definition topicref element, or both.
Topic or map authors include key references on xref, link, topicref, and other reference elements using the keyref attribute. Key references may also be included in the new “conkeyref” attribute. A key reference consists of a key name, optionally followed by a “/” character and an id of a sub-topic element.
During processing key references in topics and maps are resolved using key definitions from maps.
If a key used in a keyref or conkeyref attribute is not defined, the reference is resolved using the href or conref value on the referencing element, if any, as a fallback.
Major
The term “key” and the phrase “key name” are used
interchangeably throughout this proposal.
The terms and phrases listed below have the meanings
described in RFC 2119 throughout this proposal:
·
“must” and the terms
"required" or "shall", mean that the definition is an absolute requirement of the
specification.
·
“must not” and the phrase
"shall not", mean that the definition is an absolute prohibition of the specification.
·
“should” and the adjective
"recommended", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be
understood and carefully weighed
before choosing a different course.
·
“may” and the adjective
"optional", mean that an item is truly optional. One user or vendor may choose to include the item
because a particular
marketplace requires it or because the user or vendor feels that it enhances the product while another user or vendor
may omit the same item. An implementation
which does not use or include a particular option must be prepared to interoperate with another
implementation which does include the option, though perhaps with
reduced functionality. In the same vein an
implementation which does use or include a particular option must be prepared to interoperate with another
implementation which does not include
the option (except, of course, for the feature the option provides.)
If one of
the above terms is not used in the description of a particular feature, the
feature is an absolute requirement of the specification.
Note: Should have a warning when an
inline xref is removed.
Note: The reusing author must create
a parallel set of elements and ids in the replacement topic - this proposal
does not remap the element ids within the topic, only the pointer to the topic
container.
Note: Should generate a warning
message when a key reference on an empty element cannot be resolved, resulting
in the element effectively being removed.
1)
Add keys attribute to topicref element in map.
2)
Add keyref
attribute to selected elements in topics and maps: data, data-about, longdescref, and navref.
3)
Add the conkeyref
attribute to all elements that carry the conref attribute.
4)
Document the keys attribute and key
name syntax: The keys attribute value consists of one or more space separated
key names. Key names consist of characters that are legal in a URI and must not
contain the “{“, “}”, “[“, “]”, “/”, “#”, “?”or space characters.
The case of key names is significant.
5)
Include in the DITA Architectural
Specification a best practice to reduce the possibility of key name conflicts
when topics and maps from one documentation set are reused as part of another
documentation set. The best practice encourages, but does not require, all key
names to follow a naming convention where key names are qualified using a
package or documentation set name. The use of simple or generic key names is
discouraged.
The goal is to have packages or documentation
sets that are small enough and under the control of a person or a small team so
that the use of key names within the package or set can be coordinated by the
person or team to avoid name conflicts.
An example of a qualified key name might be “acme.hazard.productname. An example of simple or generic key names that are
likely to result in name conflicts when topics and maps are reused are “platform”,
“product” and “productname”.
6)
Document key reference syntax: a key
name, optionally followed by the character “/” and a topic element id:
keyname
keyname/elementid
7)
A key reference must be included as
the value of the keyref or conkeyref
attribute. When an elementid is present as part of a
key reference, the id is combined with the resolved key definition value to
make the complete reference.
a)
The following elements and attributes
may include a key reference:
@keyref on elements that also carry the href attribute: author, data, data-about, image, link, longdescref, lq, publisher,
source, topicref, and xref
elements;
@keyref on the navref
element;
@keyref on elements that do not carry an href attribute: cite, dt,
keyword, term, ph, indexterm, index-base, and indextermref; and
@conkeyref on all elements that support the conref attribute.
b)
Specializations based on the elements
listed above may also include key references.
c)
The following reference elements and
attributes do not support key
references:
@href on the synnoteref
element (synnoterefs must be same document
references),
@longdescref on the image and object elements. @longdescref is deprecated in favor of the new longdescref element (proposal 12050a),
@codebase, @data, @classid,
and @archive on the object element.
8) Add a
new element, keydef, to the map group domain as a
specialization of topicref (class="+
map/topicref mapgropup-d/keydef"). The
specialization is a convenience element similar in purpose to the topichead and topicgroup
specializations. The keydef element is used to define
keys without any of the other effects that occur when using topicref
(no content included in output, no title included in TOC, no linking or other
relationships defined).
For the keydef
element the keys attribute is required, the toc and
print attributes have default values of “no”. The description of the keydef specialization in the DITA specification will make
it clear that the keydef element is not the only way
that keys are defined (and Michael is free to say I told you so when people
don’t read, don’t pay attention, or don’t understand this description).
9)
Update proposal #12013,
10) Expand proposal #12014, “Conref and
conditional processing: delayed resolution for use of DITA as a delivery
format” to include delayed resolution of key references.
Document required behavior in
language and architectural specs, as follows:
11) A key definition introduces a
global identifier for a resource referenced from a map.
12) Keys are defined in maps and not in topics.
13) Keys and key references resolve to topics, to collections of
topics (ditabase), to maps, to referencable
portions of maps, to non-DITA documents, to external URIs,
or to XML content contained within a key definition topic reference.
14) Key references, but not individual keys, may resolve to sub-topic
elements.
15) href attributes in the key definition
are resolved relative to the location of the key definition rather than
relative to the location of the key reference.
16) Key definitions are not scoped by the map in which they occur or
by the element hierarchy within a map. Key definitions made in maps are visible
from other maps including referencing maps at a higher, lower, or the same
level in the map hierarchy.
17) Key
definitions in referencing maps take precedence over key definitions in
referenced maps.
18) Key definitions, once made,
cannot be redefined.
19) A key is defined by the first
definition found in a breadth-first traversal of the hierarchy of referenced
map documents. Thus a key definition in a higher level map takes precedence
over key definitions in lower level maps and the first key definition in document
order within a single map takes precedence over later key definitions. A
duplicate definition within the branch of the map document hierarchy under the
defining map is ignored without a warning. A duplicate definition within one
map or outside of the branch of the map document hierarchy under the defining
map is ignored, possibly with a warning. Note that the phrases “hierarchy of
referenced map documents” and “map file hierarchy” mean the hierarchy of map
documents or map files and not the element hierarchy within the map documents
or files.
20) Key
definitions are part of a global key namespace that is defined by a particular
map hierarchy. The order of key definitions and key references relative to one
another within the map hierarchy is not significant. Keys do not need to be defined
before they are referenced. Forward references are allowed. Keys defined in any
map are available for use with key references from all maps and topics..
21) Key references are not allowed on and will be treated as an error
if used with href or conkeyref
attributes on topicref elements that reference maps
or portions of maps that define keys.
22) Key
references are resolved as follows:
a) For a
matching key definition that includes an href
attribute:
The key reference element should
be turned into a link to the referenced target; if the key reference element is
empty, matching element content, if any, from the key definition element is
used.
If there is no matching content
from the key definition element, the key reference element remains empty and normal
link processing should pull linktext or description (desc) content from the target of the href
or use the @navtitle value from the key definition as
would normally occur when processing an xref element
or specialization.
When @linking="none"
is in effect for the key definition, a key reference element such as term or
keyword that does not carry an href attribute is not
turned into a link, but other processing occurs as usual based on the context
of the reference including the potential pulling of link or description text
from the reference target.
b) For a
matching key definition with matching content, but without an href attribute:
The key reference element is
not turned into a link. If the key reference element is empty, matching element
content from the key definition element is used.
c) For a
matching key definition without matching content and without an href attribute:
The key reference element is
not turned into a link. If the key reference element is empty, the element
remains empty.
d) When
there is no matching key definition:
If there is an
href or mapref attribute on
the referencing element, the value of the href or mapref attribute is used as the reference and the key
reference element is processed as if there were no key reference. Otherwise the
key reference element is not turned into a link, and if the element is empty,
it remains empty with a warning emitted by the key reference processor.
23) Matching
element content falls into one of two categories:
a)
Matching content for key references contained in keyref or conkeyref attributes on elements which do not also carry an href or mapref attribute (cite, dt, keyword, term, ph, indexterm, index-base, and indextermref
and their specializations) is taken from the keyword or term elements
within keywords within topicmeta. If more than one
keyword or term element is present, the matching content is taken from the
first element.
b)
Matching content for key reference elements that
carry the keyref attribute, but which do carry an href or mapref attribute (author, data, data-about, image, link, lq,
navref, publisher, source, topicref,
xref, and their specializations) includes all
elements from within the key definition element that are in context within the
key reference. Elements that are not in context within the key reference
element directly or after generalization are not included or are filtered out.
24) conrefend attribute values do not include key references. Instead the
resolved referenced object of a conkeyref attribute
is implied by the object referenced by the conkeyref
attribute. The referenced object (file or CMS object, topic, map, or sub-map
element) from the key portion of a conkeyref attribute value overrides and replaces the
portion of the conrefend attribute value that refers
to the same level object (file or CMS object, topic, map, or sub-map element).
The referenced object from the key portion of the conkeyref
attribute value is combined with the remaining portion of the conrefend attribute to define the end of the conref range.
25) The common attributes between a key reference element and a key
definition element other than the keys and id attributes are combined in the
same way as attributes on source and target conref
elements are combined including the special processing for the xml:lang, dir, and translate attributes. There is no
special processing associated with either the locktitle
or the lockmeta attributes when attributes are
combined.
26) When attributes are combined, the attributes on a key definition
element take precedence over the attributes on a key reference element. For a
chain of key reference elements the priority for combining attributes is:
1. 1st
keys definition element
2. 2nd keys definition
element
3. . . .
4. last
keys definition element
5. key reference
element
27) Content from a key reference element and a key definition element
is combined following the same procedures that are used for combining metadata
between maps and other maps, and between maps and topics. The lockmeta attribute is honored when metadata content is
combined.
28) The combined attributes and content cascade from one map to
another or from a map to a topic, but this is controlled by existing rules for
cascading which do not change with the use of key references. Note that “cascade”
is the new term for what is currently referred to as “inherit” in the DITA 1.0
and 1.1 specifications.
1) Define a new attribute for use on topicref that would provide a way to define or restrict the roles the topicref element is playing. The goal is to provide a way to say that the topicref is being used to define keys, but not to reference content or define relationships or other combinations in a way that is more scalable than just adding a new “keydef='{yes | no | only}' attribute to supplement the existing print and toc attributes. Use of an attribute similar to @class and @domains named “usage” that would have a space separated list of tokens (content, relationships, properties, …) declared as a default value in DTDs and schemas, but not generally for use in document instances, was discussed.
2) Consider adding a scoping mechanism for use with key definitions and possibly other aspects of DITA based on the map hierarchy or the combined element hierarchy within a set of maps.
3) Consider allowing subsequent key definitions within the same map or within peer maps to override previous key definitions, probably as part of some hierarchal scope, and probably in a fashion that is the same as or similar to override mechanisms to be developed for other features such as ditaval.
4) Consider providing a mechanism that would allow map authors to override references in maps and topics even if references in the maps and topics were not authored using key references or with indirect referencing in mind.
The DITA Open Toolkit and other output processing implementations will need to include processing to turn key references into file/topic references for HTML or other output.
Usability requirements on editors to support key-based references, for example so that conref content for conkeyrefs that use key references can continue to be displayed by an editor, even though the conkeyref attribute on its own does not provide enough information to locate the content (the conkeyref must be interpreted in the context of a map file that associates the target key with a particular topic).
This puts a further premium on supporting map-based authoring, i.e., authoring a topic in the context of a map, rather than as isolated chunks.
Increased complexity for both authors and implementers, particularly with the continued overloading of the topicref element.
A major increase in reusability of content.
Removes need for file-system-centric workarounds such as conref substitution.
Opportunity for improved compatibility between different content management systems, and between CMSs and other systems such as file systems, dynamic web publishing systems, databases, etc. - each of which could use their own key scheme and just externalize it as a map file for the keyed content, as well as remapping keys to the preferred linking or retrieval mechanism at runtime.
Support for Issue #12031, Controlled Values / Taxonomies.
Several meetings to agree on requirements.
Two days to document.
Time to implement changes to DTDs and schemas.
Time to implement changes to DITA Open Toolkit and other output processors.