Updated feature 20

[Michael Priestley <mpriestl@ca.ibm.com>]

Changes made with exceptions identified
below.

"Paul Prescod" <paul.prescod@xmetal.com>
wrote on 05/16/2006 11:45:13 PM:

> Some small edits based upon feedback. One meaningless sentence 
> deleted and one phrase (labeled NEW:) added.
> 
> ====================
> 
> Attendees
> =========
> Robert Anderson, IBM
> Bruce Esrig, Lucent
> Paul Prescod, XMetaL
> Su-Laine Yeo, XMetaL
> 
> Discussion
> ==========
> 
> The specification should state that there can be at most one 
> occurrence of a "prop" element with no attribute specified,
at most 
> one for each attribute with no value specified, and at most one with
> each attribute value specification.

Done, same for revprop.

> 
> There is a section of the specification that refers to the scoping
> syntax even though it has been removed. Search the spec for the word"scoped".

Done.

> 
> The description of the passthrough attribute was not obvious to all
> readers. In particular, it wasn't clear that passthrough implies 
> inclusion. This is also true of the flag attribute.

Attempted clarification of passthrough and flag.

> 
> It would be helpful to have a motivating use case for passthrough.
> Also, it would be helpful to know what it means in contexts other
> than HTML output. 

Removed HTML example, changed to say "the value
should be preserved in the syntax required by the target runtime."
Don't want to get into replicating Eclipse or CSS syntax rules in our spec.

> I personally felt that unless there is some engine that can 
> interpret these pass-throughs, there is no use putting the feature
> in the spec. After all, output engines tend to evolve independently
> of the DITA specification. If Michael knows that the Eclipse team
is
> thinking about runtime filtering then fine, leave it in. But if they
> still need to be convinced then I'd rather the convincing happen 
> before the specification does. After all, if an output or display
> engine wanted to add that feature it could do so independent of DITA.
> 
> There are places where the specification refers to the action 
> attribute as "action" rather than "@action". This
is inconsistent 
> with other attributes.
> 

Done.

> There was some enthusiasm for the idea that implementations issue
a 
> warning or informational message in the case that an attribute or
> attribute value occurs in the content but not in the DITAVAL. It 
> seemed somewhat naïve to presume that the right behaviour is just
> "include". If someone adds a parallel step to your task
that only 
> applies to some context that is not relevant to you, then you want
> it to GO AWAY by default, not be output by default.

Added recommendation that conditional processing engine
provide a report of values used with no associated actions.

> 
> We found it confusing that the alternative text attributes occurred
> on different elements than the image references themselves. We 
> propose instead elements like start-image and end-image.
> 
> There was some enthusiasm for text-based prefixes and postfixes as
> an alternative to images. We proposed "start-text" and "end-text"
as
> element names. One proposal was to collapse the start-text-alt 
> element and the start-text element by saying that the text be used
> as alternative text if there was an image supplied or as prefix text
> if there was not. Others found this confusing.

Addressed by removing startimg/endimg attributes,
replacing with startflag and endflag elements, both of which have imgref
attributes or text content so they can be used to specify either text or
image flags; plus they both have the option to contain an alt-text element.

> 
> We should specify a way for images to be conditionally flagged. For
> example, something along the lines of: "if a background color
is 
> expressed for an image, it should be represented as a thick border.
> If a foreground color is expressed, it should be represented as a
> thin border."

Added note.

> 
> We proposed to take out the list of colour names in the 
> specification. They could be included by reference as suggested by
> Paul Grosso. 
> 
> On the other hand, the link to the XSLT specification implies that
> DITAVAL processors should support the syntaxes defined here:
> 
> http://www.w3.org/TR/xsl/slice5.html#expr-color-functions
> 
> We should be explicit about what syntaxes we support. I personally
> would like to know whether XSL will synchronize with SVG and CSS as
> defined here:
> 
> http://www.w3.org/TR/css3-color/#svg-color
> 
> Somehow we need a clear definition of what syntax the attribute 
> supports. It doesn't matter much what the syntax is.

I don't have a decision here. In the absence of input,
I am picking the existing XSLT reference because the list of colors is
shorter. 

> 
> In the descriptions of @startimg and @endimg, we felt that 
> everything before the comma is redundant: "If flag has been set,
the
> image to use for flagging the beginning of flagged content."
On the 
> other hand, it would be good to say whether it is an error to 
> specify the @startimg with @action=include, @action=exclude or 
> @action=passthrough.

Specified that they are ignored when flag is not set.

> 
> Printchar is a big open issue. There are three models: HTML, FO and
> IBM-existing. Nobody knows whether HTML supports changebars. My 
> proposal: keep princhar for internal IBM use, but deprecate it. Add
> a coloured changebar feature that would degrade gracefully to a 
> background color in formats that do not support change bars.

Attempted to reconcile by changing to "changebar",
limiting to revprop, and leaving its content dependent on the target output
support (ie it can take color, style or character as input, depending on
the output engine's capabilities).

> 
> If we add the start-text feature then the ">>" and
"<<" characters 
> described in the spec could be DEFAULTS for revprop behaviour. 
> 
> Proposal for Conflicts
> ======================
> 
> We proposed to handle style conflicts with a singleton element 
> called "styleconflict" that would allow ditaval authors
to say what 
> happens in the case of a style conflict. It would have foreground-
> conflict-color and a background-conflict-color attributes.
> 
> 
> If two rules style the same element with a different background 
> colour, then fall back to the styleconflict/@background-conflict-color.
> 
> If two rules style the same element with a different foreground 
> colour, then fall back to the styleconflict/@foreground-conflict-color.
> 
> If two rules style the same element with two different types of 
> underline, then use the styleconflict/@foreground-conflict-color 
> [NEW: and the heaviest kind of underline (double overrides single).]
> 
> The defaults for these attributes are application and media specific.
> 
> 

Changed as suggested.

IssueNumber20.dita

Title: DITA Proposed Feature # 20

DITA Proposed Feature # 20

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.

1. DITA architect for a team defines new attributes that are needed by the team (eg proglanguage)
2. 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.
3. 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)"
4. Author can now add values to the new attributes, since they are physically present in the document type
5. 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").
6. 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.

1. 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)
2. 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.
3. 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)"
4. Author can now add values to the new attributes, since they are physically present in the document type
5. 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").
6. 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

1. 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.
2. 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.
3. 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")
4. 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

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 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

=