Concerns about <abbreviated-form> and its rendering rules

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Hi, folks.

 

I have a lot of concerns about rendering of the <abbreviated-form> element. Here’s what we have in the draft DITA for Technical Content 2.0 spec:

 

------------------------

 

Rendering of <abbreviated-form> elements

There are specific rules that specify how processors should render <abbreviated-form> elements.

Note that the definition of "introductory context" will vary based on the processor and output format.

1. If the referenced topic is not a <glossentry> topic or a specialization of <glossentry>, the title of the topic SHOULD be rendered.
2. If the referenced topic is a <glossentry> topic or a specialization of <glossentry> and the <abbreviated-form> element is located in an introductory context:
• (If the referenced topic contains a non-empty <glossSurfaceForm> element) Processors SHOULD render the contents of the <glossSurfaceForm> element
• (If the referenced topic does not contain a non-empty<glossSurfaceForm> element) Processors SHOULD render the contents of the <glossterm> element
3. If the referenced topic is a <glossentry> topic or a specialization of <glossentry> and the <abbreviated-form> element is located in a non-introductory context:
• (If the referenced topic contains a non-empty <glossAcronym> element) Processors SHOULD render the abbreviated form of the term by displaying the contents of the <glossAcronym> element.
• (If the reference topic does not contain a non-empty <glossAcronym> element) Processors SHOULD render the contents of the <glossterm> element
 

My concerns:

• How can we make normative SHOULD statements about the rendering of <abbreviated-form> when we say that the entire concept of introductory and non-introductory contexts is inherently subjective?
• I think these rendering statements do not comply with the rules that we set out in the base spec for resolving key references to variable or link text. We certainly reworked that pretty extensively for DITA 2.0; now I think we need to consider how we make the base and <abbreviated-form> rules work together.

 

Base rules: See https://dita-lang.org/dita/archspec/base/processing-keyref-for-text , the significant text copied below:

 

Processing rules

Processors MUST resolve variable text that is defined using keys by using the following sequence:

1.     Effective text content is taken from the <keytext> element.

2.     Effective text content is taken from the <titlealt> element with @title-role set to linking.

3.     Effective text content is taken from the <titlealt> element with @title-role set to navigation.

4.     Effective text content is taken from the <titlealt> element with @title-role set to a processor-recognized value.

5.     Effective text content is taken from the title of the referenced document, if available.

6.     Effective text content is determined by the processor.

Kris