DITA Proposed Feature #12022

Unenumerate attributes that have fixed enumerated values in DITA 1.1 where the list of values should be unbounded and where making the lists unbounded would not be too disruptive in advance of more sophisticated tool support for working with enumerated attributes that are not defined directly in the governing DTDs or schemas.

Longer description

In DITA 1.1, a number of attributes are defined as fixed sets of keywords from which one or more may be selected. While these definitions are convenient for validation and for use in syntax-directed editors, in some cases they are inappropriately constraining in that they may not fully reflect all possible useful or sensible values, either for use by new specializations or for use of existing element types in new business or information domains.

Ideally the DITA declarations would not define any fixed sets of values except where such a set is provably complete for all possible future uses. However, the practical reality is that in the DITA 1.2 time frame most, if not all, XML editors will not be able to easily (or at all) provide authors with discrete lists of values unless those values are defined in the governing DTDs or schemas as enumerated attributes. In the future it is expected that more flexible mechanisms, such as a DITA-specific controlled vocabulary facility or emerging standards such as the OASIS Genericode mechanism will allow XML editors to provide generic support for enumerated attributes where the set of values to be used by any given author is defined outside the base DITA document types. Thus, for DITA 1.2 it is not practical to make all enumerated attributes unenumerated. Rather, the following attributes have been identified as being appropriate candidates for unenumeration in that they are both clearly limiting in their current form and do have any base or known processing that depends heavily on a specific set of values:
  • draft-comment/@disposition
  • author/@type
  • authorinformation/@type (is a specialization of author)
  • copyright/@type
  • permissions/@view
  • audience/@type,
  • audience/@job
  • audience/@experiencelevel
  • publishtype/@value
  • bookrestriction/@value

While these attributes will be unenumerated, the enumeration values defined by DITA 1.1 will be listed in the DITA specification as values that should be allowed in those attributes in all specializations. The specification must distinguish values that are merely suggested (meaning that individual documents or specializations need to allow those values) from values that are required to be allowed in all documents.

In advance of unenumerating all enumerated attributes, analysis identified new values to be added to existing attributes:
  • Add the value "spread" to the @expanse attribute. The value "spread" indicates that, if possible, the object should be rendered across a multi-page spread (normally a two-page spreads but some book designs may provide for more pages in a spread, such as foldouts). If the rendition target does not have anything corresponding to spreads then spread has the same meaning as "page".
  • Add additional values to the note/@type attribute as identified by the Machine Industry Subcommittee.

Statement of Requirement

DITA must allow users to limit or extend the set of values used with enumerated attributes where those attributes do not represent a necessarily completely and invariant set of possible values.

Use Cases


Scope

Minor: Changing attribute declarations from enumerations to #NMTOKEN(S) and updating attribute documentation reflect the new ability to restrict or extend the value sets.

Technical Requirements

Change the declarations for the following attributes:
  • In commonElements.mod
    • Update the list of values for the type= attribute to include the following values as defined by the Machine Industry TC in the Hazard Statement proposal:
      • caution1
      • caution2
      • notice
      • warning
  • In metaDecl.mod, change the declarations of the following attributes from enumerated values to #NMTOKEN
    • The type= attribute the author element
    • The type= attribute the copyright element
    • The view= attribute the permissions element
    • The job= attribute the audience element
    • The experiencelevel= attribute the audience element
  • In xnalDomain.mod:
    • The type= attribute of the authorinformation element
  • In bookMap.mod:
    • The value= attribute of the publishType element
    • The value= attribute of the bookrestriction element

New or Changed Specification Language

Update the entries for the changed attributes to indicate that the set of allowed values is unbounded and that the DITA 1.1 values are suggested or sample values.

Costs


Benefits