Updated conditional processing feature

Extensible universal attributes, specifically for conditional processing (filtering/flagging, also known as profiling) and revision marking, but also for arbitrary attributes that have a similarly simple syntax; plus formalization of the ditaval syntax.

Interested parties

Michael Priestley (owner)
Robert Anderson
Paul Grosso
Bruce Esrig
Erik Hennum
Dana Spradley
Paul Prescod
Chris Wong

Longer description

Allow DITA document type developers to incorporate new conditional processing attributes that can be used for filtering and flagging, new revision attributes that can be used to mark changes to a document, or new attributes with no existing equivalent that can be managed and generalized in the same way as conditional processing attributes.

The new attributes need to be:

Identified as conditional processing attributes, or revision attributes, or neither
Preserved during generalization and respecialization
While generalized, still operable on by either general or specialized behaviors (for example, conditional processing or revision marking)

This proposal also documents a proposal for increased flexibility in the ditaval format that is used to select values for exclusion, inclusion, or flagging.

Scope

Major

Use Case: new conditional processing attributes

Creating new specialized attributes from an ancestor props attribute.

DITA architect for a team defines new attributes that are needed by the team (eg proglanguage)
DITA architect expresses each new attribute as a separate domain package (eg proglanguage.mod, with new attribute specialized from props attribute). Each new attribute is managed in a separate domain, to enable its ancestry to be tracked in the domains attribute.
DITA architect integrates the domain packages into the authoring DTDs or schemas:
1. redefining "props" attribute entity to include proglanguage attribute, same way we redefine element entities to integrate new domain elements;
2. adding the new attribute domain to the list of domains in the domains attribute, preceded by an "a"; for example domains="a(props proglanguage)" or domains="a(props audience role)"
Author can now add values to the new attributes, since they are physically present in the document type
Build developer defines values in ditaval format and runs a build to remove or flag content based on the new attributes (eg flag all proglanguage="Java").
Another build developer includes their content but needs to run all content through a specialization-unaware trademarking tool that requires generalization of the contributed content; after generalization, the content is processed into output with filtering based on the new attributes (which are now collapsed into props attribute):
1. the generalize process turned proglanguage="Java" into props="proglanguage(Java)"
2. the conditional processing transform recognizes the new form as equivalent to the old, and the instruction "flag all proglanguage=java" operates on either props="proglanguage(Java)" or proglanguage="Java".

Given the capability to add new conditional processing attributes, the current complex attribute syntax described for otherprops in DITA 1.0 will now be deprecated in favour of the new functionality described here.

Use case: new revision attributes

Creating new specialized attributes from an ancestor rev attribute.

DITA architect for a team defines new attributes that are needed by the team (eg tehnicalchange, to identify revisions that are more than just editorial or style edits)
DITA architect expresses each new attribute as a separate domain package (eg technicalchange.mod, with new attribute specialized from rev attribute). Each new attribute is managed in a separate domain, to enable its ancestry to be tracked in the domains attribute.
DITA architect integrates the domain packages into the authoring DTDs or schemas:
1. redefining "rev" attribute entity to include technicalchange attribute, same way we redefine element entities to integrate new domain elements;
2. adding the new attribute domain to the list of domains in the domains attribute, preceded by an "a"; for example domains="a(rev technicalchange)" or domains="a(rev technicalchange backwards-compatible-change)"
Author can now add values to the new attributes, since they are physically present in the document type
Build developer defines values in ditaval format and runs a build to remove or flag content based on the new attributes (eg flag all technicalchange="release2").
Another build developer includes their content but needs to run all content through a specialization-unaware trademarking tool that requires generalization of the contributed content; after generalization, the content is processed into output with filtering based on the new attributes (which are now collapsed into the rev attribute):
1. the generalize process turned technicalchange="release2" into rev="technicalchange(release2)"
2. the conditional processing transform recognizes the new form as equivalent to the old, and the instruction "flag all technicalchange=release2" operates on either technicalchange="release2" or rev="technicalchange(release2)".

Use case: new generic attributes

DITA architect for a team needs to add a new attribute that has no equivalent in existing DITA, for example a "phase" attribute that identifies what phase of a process an element is associated with.
DITA architect expresses each new attribute as a separate domain package (eg phase.mod, with new attribute "phase" specialized from "base" attribute). Each new attribute is managed in a separate domain, to enable its ancestry to be tracked in the domains attribute.
DITA architect integrates the domain packages into the authoring DTDs or schemas:
1. redefining "base" attribute entity to include phase attribute, same way we redefine element entities to integrate new domain elements;
2. adding the new attribute domain to the list of domains in the domains attribute, preceded by an "a"; for example domains="a(base phase)" or domains="a(base phase phasetype")
The DITA architect must also supply processing behavior for the new attribute, and ensure that it works on both the specialized form (eg phase="develop") and the generalized form (eg base="phase(develop)"), using the conditional processing match logic as a pattern.

Notes on matching against specialized attributes

As with other specialization cases, a match against an ancestor attribute should also apply to its specialized attribute children, but a match against a specialized attribute should not apply to its ancestors.

For example, given that "role" is an attribute specialized from "audience", which in turn is specialized from "props":

<prop att="audience" val="programmer" action="flag".../> would match against both audience="programmer" and role="programmer"
<prop att="role" val="programmer" action="flag" .../> would only match against role="programmer".

Notes on the generalized attribute syntax

When generalized, specialized attribute values are added to the end of their target ancestor attribute, within parentheses preceded by the name of the specialized attribute. For each attribute that has been generalized, a separate label and parentheses-enclosed set of values is added to the ancestor attribute.

For example, given that "role" is an attribute specialized from "audience", which in turn is specialized from "props":

role="programmer" can be generalized to audience="role(programmer)" or to props="role(programmer)"
props="role(programmer)" can be respecialized to audience="role(programmer" or to role="programmer"

Generalization and respecialization can use the domains attribute to determine the ancestry of role, and therefore the validity of audience as an intermediate target for generalization.

Generalized attributes are typically not expected to be authored or edited directly, but to preserve the values of the specialized attributes while the document is temporarily in a generalized form.

If a single element contains values for an attribute in more than one syntax, that is an error. For example <p audience="role(programmer)" role="admin">...</p> both provide values for the role attribute, but one in a generalized syntax and one in a specialized syntax. This is an error condition, since it means the document has been only partially generalized, or has been generalized and then edited using a specialized document type.

Use case: extended syntax for ditaval

Publishers require more flexibility in how they process values. The following format extends and formalizes the .ditaval format used in the DITA toolkit and referred to non-normatively in the DITA 1.0 specification:

val

Root element, contains one or more prop or revprop elements

prop

Identifies an attribute, and usually values in the attribute, to take an action on. The attribute must be props or a specialization of the props attribute (such as platform, product, audience, otherprops, or their specializations).

@att

The attribute to be acted upon. Must be one of props, audience, platform, product, otherprops, rev, or a specialization of them. If the att attribute is absent, then the prop element declares a default behavior for any attribute specialized from props.

@val

The value to be acted upon. The value may be only a component of a scoped value, for example "programmer" would match "programmer/enterprise". If the val attribute is absent, then the prop element declares a default behavior for any value in the specified attribute.

action

The action to be taken. The options are:

include: Include the content in output. This is the default behavior unless otherwise set.
exclude: Exclude the content from output (if all values in the particular attribute are excluded).
passthrough: Include the content in output, and preserve the attribute value as part of the output stream for further processing. For example, add to the class attribute in html output, using the format for generalized values: eg class="programminglanguage(programmer)"
flag: Flag the content on output (if the content has not been excluded).

@startimg

If flag has been set, the image to use for flagging the beginning of flagged content.

@endimg

If flag has been set, the image to use for flagging the ending of flagged content.

@color

If flag has been set, the color to use to flag text. Colors may be entered by name or by code. Processor support is recommended for the following: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. See the entry for color in http://www.w3.org/TR/xsl/slice5.html#section-N8794-Property-Datatypes.

@backcolor

If flag has been set, the color to use as background for flagged text. Colors may be entered by name or code. Processor support is recommended for the following: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. See the entry for color in http://www.w3.org/TR/xsl/slice5.html#section-N8794-Property-Datatypes.

@style

If flag has been set, the text style to use for flagged text. The following values are enumerated:

underline
double-underline
italics
overline
bold

@printchar

If flag has been set, the character to include in the margin of the flagged text, for example "|".

revprop

Identifies a value in the rev attribute of content, or of a specialization of the rev attribute, that should be flagged in some manner. Unlike the props attribute, which can be used for both filtering and flagging, the rev attribute and its specializations can only be used for flagging.

@att

The attribute to be acted upon. Must be rev or a specialization of rev. If the att attribute is absent, then the revprop element declares a default behavior for any attribute specialized from rev.

@val

action

The action to be taken. The options are:

include: Include the content in output without flags. This is the default behavior unless otherwise set.
passthrough: Include the content in output, and preserve the attribute value as part of the output stream for further processing.
flag: Flag the content on output (if the content has not been excluded).
: Flag the content using >> and << characters in addition to whatever image or style options are chosen.

@startimg, @endimg, @color, @backcolor, @style, @printchar

Same as for prop element

startimgalt

An element allowed inside either prop or revprop to provide alternate text for an image, when the startimg attribute sets an image to be used for flagging. If the element is absent inside revprop, the default alternate text of "start of change" will be used, in the language of the current document or element.

endimgalt

An element allowed inside either prop or revprop to provide alternate text for an image, when the endimg attribute sets an image to be used for flagging. If the element is absent inside revprop, the default alternate text of "end of change" will be used, in the language of the current document or element.

In case of conflicts between flagging methods at different levels (for example, a section is flagged green and a paragraph within the section is flagged red) the most deeply nested flagging method applies.

In case of conflicts between flagging methods on the same element (for example, a single element is being flagged with both green and red color) it is recommended that the conflicts be resolved as follows:

Image flagging: Add all image flags that apply.
color: Color the text magenta.
Draft comment:
do we need a way to set the conflict color, for the sake of accessibility?
backcolor: Make the background color magenta.
style: Add all font styles that apply.
printchar: Open issue?
Draft comment:
currently supported only for rev. we could make it specific to revprops, if we keep revprops.. Otherwise, would we need a conflict changebar, like we have a conflict color?.

Technical Requirements

Change to the architectural specification to allow specialization of new universal attributes off of the attributes props, rev, and base, following the domain model for specialization: each new universal attribute defined in a separate domain package that provides an attribute definition entity and a domain attribute value that starts with "a" and then lists the attribute ancestry in parentheses, eg a(props language). The domain can be integrated into a doctype by redefining the equivalent ancestor attribute entity to include the new attribute entity, and redefining the domains attribute to include the domains value entity.

Define syntax for generalized attribute values and generalization/respecialization logic for specialized domain attributes in the specification.

Update conditional processing logic to work the same on either specialized or generalized forms of the value: OR between attributes, AND within an attribute, whether or not an attribute actually exists.

Remove existing section of specification on how to "break" architecture to get attribute specialization.

Add a "props" attribute to the architecture, from which the other metadata attributes (platform, product, audience, otherprops) will be specialized.

Add a "base" attribute to the architecture, which will be ignored by unspecialized processing.

Ensure all attributes are expressed in entities to allow domain-based expansion/specialization (DTDs); document equivalent mechanism for schemas

Formalize and document ditaval format, including logic for filtering, flagging, ignoring, or passing through values in the props attribute or in attributes specialized from the props attribute; and for setting attribute defaults.

Costs

Time required for design should hopefully be minimal. There will be more work by the open-source toolkit to enhance existing transforms to handle "base" and "props"-specialized attribute generalization and respecialization, and make the conditional processing logic specialization-aware.

Benefits

Many people would make use of this. It is consistently a highly rated requirement. For some, this would remove a major barrier to DITA adoption.

Time Required

3 1-hour meetings to review requirements

3 1-hour meetings to agree on solution

2 days to complete document solution

dita message

DITA Proposed Feature # 20