[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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:
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) |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]