DITA Proposed Feature # 02

Allow nesting of keyword elements within keyword.

Longer description

The problem: The keyword element is often used to store common text such as product or platform names. This is done because keywords are allowed in nearly all locations that allow text. However, it is not possible to combine common strings into one single keyword for reuse. For example, both "Product A" and "Platform B" are common strings, and are often used together as "Product A for Platform B". To use the combined value, users must enter a new copy of each string in another keyword. Alternatively, they could always reference the two in text as "<keyword conref="#topic/product"/> for <keyword conref="#topic/platform"/>". So, it is impossible to reuse the string "Product A for Platform B" without repeating text somewhere.

A second problem is that it is not possible to pull a common string into an existing keyword-based element. If "Product A" is used throughout documentation, it will be stored as a keyword. However, "Product A" cannot be reused inside of a wintitle element. The user must either store a new reusable copy as a wintitle, or enter the text directly inline.

The solution: Change the content model of keyword from (#PCDATA | tm) to (#PCDATA | tm | keyword). This will allow combinations of common strings to be reused, without maintaining extra copies of the text. It will also allow users to pull a keyword into appropriate keyword-based contexts.

The full design needs to determine which keyword domains should nest keywords. A keyword specialization can contain either text (as they do today), text and one or more keywords from the same domain, or text and keyword. Nesting keyword means that the keyword specialization will be able to contain all other keyword domain specializations.

Discussion:

Scope

Small. Need to update the DTD and schema to allow keyword to contain itself. Need to determine which keyword domain elements should nest keywords.

Use Case

Users want to combine common strings into more complicated common strings. For example, if "Product A" and "Platform B" are both common strings, then users should be able to have the common string "Product A version 5 for Platform B" without redoing the common text:

<keyword id="a">Product A</keyword>
<keyword id="aV5"><keyword conref="#topic/a"/> Version 5</keyword>
<keyword id="B">Platform B</keyword>
<keyword id="av5forB"><keyword conref="#topic/aV5"/> for <keyword conref="#topic/B"/></keyword>

This markup allows users to use "Product A" as a common keyword, while also allowing them to create new common strings that reuse the keyword.

Use Case

Users want to use common keywords inside other keyword specializations. For example, if a product name is used in a <wintitle> element, users need to pull the value into that window title:

<keyword id="a">Product A</keyword>

<wintitle>Configuration panel for <keyword conref="#topic/a"/></wintitle>

Technical Requirements

Need to update the DTD and schema to add keyword to itself. Need to update keyword specializations to include appropriate elements.

Costs

May need to update tools to be aware of nested elements.

Benefits

Users can reuse common keywords in more locations.

Time Required

Several hours to determine what elements should nest in each keyword specialization, to update all DTDs, and to verify tools are not affected.