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)