RFC-2119 terminology

The DITA specification uses RFC-2119 keywords. To quote from the
    OASIS directives about normative terminology:

    

    "Keywords establish the requirements that implementers follow in
    conforming to OASIS specifications and standards. Careful use of
    keywords is one part of creating standards that help different
    implementers to have the same interpretation of these requirements
    and lead to interoperable applications from different vendors."

    

    We began implementing these keywords for DITA 1.2, but we now have
    much clearer guidance from OASIS (see attached PDF if you want all
    the details).

    

    Here are the RFC keywords:

    
      MUST 
      This word, or the terms "REQUIRED" or "SHALL", mean
        that the definition is an absolute requirement of the
        specification. 
      MUST NOT 
      This phrase, or the phrase "SHALL NOT", means that
        the definition is an absolute prohibition of the specification.
      
      SHOULD 
      This word, or the adjective "RECOMMENDED", means
        that there may exist valid reasons in particular circumstances
        to ignore a particular item, but the full implications must be
        understood and carefully weighed before choosing a different
        course. 
      SHOULD NOT 
      This phrase, or the phrase "NOT RECOMMENDED", means
        that there may exist valid reasons in particular circumstances
        when the particular behavior is acceptable or even useful, but
        the full implications should be understood and the case
        carefully weighed before implementing any behavior described
        with this label. 
      MAY 
      This word, or the adjective "OPTIONAL", means that
        an item is truly optional. One vendor may choose to include the
        item because a particular marketplace requires it or because the
        vendor feels that it enhances the product while another vendor
        may omit the same item. An implementation which does not include
        a particular option must be prepared to inter operate with
        another implementation which does include the option, though
        perhaps with reduced functionality. In the same vein an
        implementation which does include a particular option must be
        prepared to interoperate with another implementation which does
        not include the option (except, of course, for the feature the
        option provides). 
    
    
Right now, the spec does not always use these keyword correctly.
      Part of our moving forward is to correct this. Here are some
      examples of current correct and incorrect usage:

    

    
Correct:

    
"Processors SHOULD be able to
      perform filtering and flagging using the attributes listed above.
      The @props attribute can
      be specialized to create new attributes, and processors SHOULD be able to perform
      conditional processing on specializations of @props.

    Comment: This reflects the RFC-2119 terminology. It pertains
    to interoperation. This could be improved so that the normative
    statement actually listed the attributes and can be read by itself.

    

    

    Incorrect:

    

    "For each extension element type in the base vocabulary module whose
    content model or attributes are to be constrained in the constraint
    module, there MUST be a <xs:redefine> element that
    defines the restricted content model for the base element.
    Attributes for an element type MAY
    be constrained as part of the redefinition of the complex type."

    

    Comment: This simply has to do with how XML Schema works.
    It can be rewritten as follows: "For each element type in the
    vocabulary module whose content model or attributes are to be
    constrained in the constraint module, use an <xs:redefine>
    element to define the restricted content model. Attributes for an
    element type can be constrained as part of the redefinition of the
    complex type." 

    -- 

    
Best,

      Kris

      

      Kristen James Eberlein

      Chair, OASIS DITA Technical Committee

      Principal consultant, Eberlein Consulting

      www.eberleinconsulting.com

      +1 919 682-2290; kriseberlein (skype)

      

    

  

Attachment:
OASIS-Keywords-Directives-v6.0-1.pdf

Description: Adobe PDF document