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:
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.
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.
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 <> on behalf of Kristen James Eberlein <>
Date: Tuesday, February 9, 2016 at 8:40 AM
To: dita <>
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
