How should the spec handle statements about rendering expectations?

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

In August 2016, Robert and I embarked on a marathon work effort in response to OASIS Technical Advisory Board (TAB) comments. In response to TAB questions about our use of normative and non-normative terms, we looked at every instance of MUST and SHOULD in the draft DITA 1.3 spec. This, of course, also required that we look at all the instances of "must" and "should".

We'll cover some of this in a TC discussion of normative versus non-normative statements -- but one  thing that we noticed as part of this work effort was that there was inconsistent language in what we called "legacy Language Reference topics" -- topics that were authored very early and have probably not be changed since the first release of DITA. Some normative statements, some statements that probably should be normative (but which we could not change at that time), and just some suggestions about possible formatting.

Here are some examples of prose in the spec that contains statements about rendering expectations. I've separated them into three groups: topics with normative statements; topics with statements that are not (but probably should be) normative; and topics that contain suggestions about formatting/rendering.

Normative statements

<draft-comment>
Processing systems SHOULD provide a mechanism that causes the content of this element to be rendered in draft output only. By default, processors SHOULD strip them out to prevent publishing internal comments by mistake.

<q>
Authors should not add quote punctuation manually when using the <q> element. Processors that render the <q> element SHOULD add appropriate styling, such as locale-specific quotation marks.

<abbreviated-form>
Has an entire section on "Rendering the <abbreviated-form> element". See http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/langRef/technicalContent/abbreviated-form.html#abbreviated-form

Non-normative statements (but should be normative?)

<abstract>
When the contained <shortdesc> occurs within phrase-level content, it is treated as phrase-level content and should not create a separate paragraph on output of the topic. When the contained <shortdesc> occurs as a peer to paragraph-level content, it is treated as block-level content and should create a separate paragraph on output of the topic. When multiple <shortdesc> elements are included in an <abstract>, they are concatenated in output of link previews or summaries (separated by spaces).

<required-cleanup>

Processing notes:

• Processors must strip this element from output by default. The content of <required-cleanup> is not considered to be verified data.
• Processor options might be provided to allow a draft view of migrated content in context.

<sl>
On output, the list should have no bullets, on the assumption that each item is short enough to fit on one line, and needs no additional differentiation from its neighbors.

<sli>
When a DITA topic is formatted for output, the items of a simple list should be placed each on its own line, with no other prefix such as a number (as in an ordered list) or bullet (as in an unordered list).

<steps> (and <steps-unordered> is similar
Steps with only a single step might be rendered as a paragraph rather than as a list. Two or more steps should typically be rendered as an ordered list. If all of the contained steps are simple (that is, have no more than a <cmd> element each) then the step list should default to compact. Otherwise it should be rendered as expanded (with blank lines between each step).

Suggestions about formatting

<lq>
Although rendering is left up to implementations, processors generally render <lq> as an indented block.

<choicetable>
By default, processors highlight the choice column using bold. To change the highlighting, set the @keycol attribute of the <choicetable> tag to 0 (zero).

<screen>
The default print representation is to enclose the screen within a box, suggesting a computer display screen.

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)