Re: [dita] How should the spec handle statements about rendering expectations?

[Eliot Kimber <ekimber@contrext.com>]

With respect to the discussion on today's call, here's the point I was trying to make:

• Statements about rendering (layout, formatting, inclusion or exclusion, decoration details, etc.) in any final form deliverable cannot be MUST statements. The DITA specification is not a rendition standard, it's a data standard and thus it is inappropriate to make any rendition detail mandatory. Even the <q> element's requirement that the quote markers be generated can at best be a SHOULD (but a well-justified and emphatic SHOULD). 
• It is important to make the design intent of elements clear and one way to do that is to make statements about how the elements are intended or expected to be rendered in typical renderings. These statements can be SHOULD statements. SHOULD means "really you should do it this way unless you have a good reason not to". It's formally normative (meaning it is a condition of conformance) but, because it is SHOULD and not MUST it's not mandatory. 

On the issue of normative vs. non-normative:

Normative text in a standard should be clear, precise, and non-repetitive. The normative text exists to say either "this is what the design is or is not" or "this is what conforming {thing that can conform} MUST or SHOULD do to be conforming." There's no sense in which the rendition (as opposed to the overall processing, including address resolution, conref resolution, filtering, and other preprocessing concerns) can be conforming  because everything is necessarily optional as regards rendition requirements or expectations.

Given that understanding of normative, I think the reference entries should reflect:

1. Clear normative language describing the semantic and general processing intent of the element. Where appropriate, clear normative language describing the authoring intent (how to use the element, either by itself or in combination with other elements). The focus of this language is on what the element is and what it means. For most elements, the processing expectations for common use cases will be obvious from this definition.
2. Normative SHOULD statements about the rendition intent for typical use cases (e.g., final-form publications intended for reading by users of the thing documented {for technical documentation} or the human reader of non-technical publications rendered to paged media {PDF, fixed-layout EPUB, etc.} and interactive media {HTML, online help, flowed EPUB}). The use of normative SHOULD lends weight to the intent of the TC and helps encourage consistency of implementation for these use cases.
3. Non-normative rendering or processing suggestions or options where there is no need for or possibility of consistent implementation or where there is known to be wide variance in how the element is typically rendered (for example, troubleshooting tasks can be rendered in many different ways, with none being particularly privileged or preferred). This is useful as guidance to implementors and authors and helps elucidate the more formally-stated design but should not be normative. I think have a section labeled something like "Presentation Suggestions" or "Rendering Discussion" that is explicitly non-normative would be useful. The examples in the XSLT specification are a good example of this type of explanatory commentary.

In terms of the things the DITA specification requires (and must require) vs. things it can only suggest, address resolution (URI and key processing) is the only thing for which processing rules are mandatory, otherwise there can be no expectation of consistency and interoperation of processor behavior during preprocessing. Because of the interaction of key resolution, key scope construction, and branch filtering in DITA 1.3 there is effectively only one (or at most two) ways to do preprocessing and get the right answer for address resolution (that is, resolve keys to the correct resource following resolution of all branch filtering, content reference resolution, and key space construction). These aspects of processing are either already MUST statements or, where the spec must (for legacy reasons) allow variance in processing order (filter first vs. conref first), strongly worded SHOULD statements. All other aspects of DITA processing are necessarily either optional, where specified in the standard, or entirely up to implementors.

Cheers,

Eliot

----

Eliot Kimber, Owner

Contrext, LLC

http://contrext.com

From: dita <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Tuesday, February 9, 2016 at 8:40 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] How should the spec handle statements about rendering expectations?

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)

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php