[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Issue 12007 : Indirect reference/keyref proposal
Attached is the current draft of the proposal for DITA Issue # 12007 : 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 Priestly and is the work of an ad hoc subcommittee convened by Michael Priestly that includes: Michael Priestley, Jeff Ogden, Erik Hennum, Deborah Pickett; Ian Larner; Michael Gannon, and Eliot Kimber. This proposal is not yet ready for discussion by the full DITA TC, but the ad hoc subcommittee would welcome comments and suggestions on the current approach as outlined in the draft. Send your comments to this list (dita@lists.oasis-open.org) or to jogden@ptc.com or to mpriestl@ca.ibm.com. -Jeff Ogden |
DITA Issue # 12007 (draft version 2.1, 29 October 2007)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 Priestly and is the work of an ad hoc subcommittee convened by Michael Priestly that includes: Michael Priestley, Jeff Ogden, Erik Hennum, Deborah Pickett; Ian Larner; Michael Gannon, and Eliot Kimber. This proposal is not yet ready for discussion by the full DITA TC, but the ad hoc subcommittee would welcome comments and suggestions on the current approach as outlined here. Send comments to the DITA TC list or to jogden@ptc.com or to mpriestl@ca.ibm.com. Longer descriptionWhenever 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, and other reference elements. 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 names are defined using a topicref or topocref specialization that uses the new keys attribute. A keys definition defines one or more key names and the value to which the keys resolve. Keys resolve to the URI given as the href value or to the contents of a linktext element contained within a topicref or topicref specialization. Key definitions are used to resolve references when a reference attribute (href, conref, …) on an element in a topic or a map contains a key reference. A key reference consists of the string “ditakey:” followed by a key name, optionally followed by a “/” character and an id of a sub-topic element or by a “#” character and an id of a map element. If a key reference cannot be resolved, the reference is resolved using an optional fallback reference attribute on the original reference element. ScopeMajor Use Case 1: Redirect link or xref
Note: Should have a warning when an inline xref is removed. Use case 2: Redirect conref
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. Use case 3: Create links from keywords/terms/etc.
Use case 4: Swap out variable content
Note: Should generate a warning message when a key reference on an empty element cannot be resolved, resulting in the element effectively being removed. Use case 5: Splitting/combining targets
Technical RequirementsAdd keys and usage attributes to topicref element in map. Add keyref attribute to selected elements in topic and map [need a complete list of elements]. Remove keyref attribute from and add fbref (fallback reference) attribute to selected elements in topic and map [need a complete list of elements]. 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 which cannot contain the “/”, “#”, or space characters. The use of periods in key names is discouraged to allow the use of periods to establish a hierarchal key name space in the future. Document key reference syntax: the string “ditakey:” followed by a key name optionally followed by / and topic element id or # and mapid; for example,
Key references can be added to or used from any of the existing reference attributes (href, conref, …) in topics or maps [need a complete list of elements]. When an elementid or a mapid is present as part of a key reference, the id is combined with the resolved key definition value to make the complete reference. Document fbref value syntax and semantics: a non-keyref reference value that when present will be used in place of the primary reference attribute when the primary reference attribute includes a key reference that cannot be resolved. Document usage attribute syntax and semantics: a list of one or more space separated tokens that indicate the role or roles that the topicref or topicref specialization is playing. Like class and domains, the usage attribute value will usually be defined in the DTD or schema rather than in the document instance. Standard usage tokens are “content”, “relationships”, and “properties”. Additional new usage tokens may be added. The three standard tokens will be included as the default value for @usage, but this could be changed for a specific topicref specialization. To avoid name conflicts it is suggested that user’s adopt the same prefixing scheme for user defined usage tokens as is currently suggested for chunk token names. [Need more detail on the semantics of each of the three standard usage tokens.] Document required behavior in language and architectural specs, as follows: Keys are defined in maps and not in topics. Keys resolve to topics, to collections of topics (ditabase), to maps, to referencable portions of maps, to non-DITA documents, to external URIs, or to text strings. Keys do not resolve to sub-topic elements. Key definitions are not scoped by the map in which they occur or by nesting within a map. Key definitions and key references are processed in the order in which they are encountered. An earlier key definition is overridden by a later key definition. Key references included in conref attributes are resolved before the conref is processed. Key references are resolved as follows:
The common attributes between a key reference element and a key definition element other than the keys and id attributes are combined in a fashion that is similar to the combining that is defined for attributes on source and target conref elements today including the special processing for the xml:lang, dir, and translate attributes. When they are combined, attributes on a key reference element take precedence over attributes on a key definition element. For a chain of key reference elements the priority for combining attributes is: 1. key
reference element The combined attributes may 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. CostsToolkit will need to include preprocessing pass 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 conrefs can continue being resolved in the editor, even though the conref attribute on its own is no longer enough to locate the content (the conref 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. BenefitsA 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. Time Required5 one hour meetings to agree on requirements and solution (hoping, three down, two to go) 2 days to document ? days to implement changes to DTDs and schemas ? days to implement changes to DITA Open Toolkit and other output processors Issues
|
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]