RE: [dita] MUST, SHOULD, and MAY, some key words from RFC 2119

Thanks for the examples - adding thoughts
to them below

Michael Priestley

Lead IBM DITA Architect 



http://dita.xml.org/blog/25

"Ogden, Jeff"
<> 

10/02/2007 03:01 PM

To

Michael Priestley/Toronto/IBM@IBMCA

cc

<>

Subject

RE: [dita] MUST, SHOULD, and MAY, some
key words from RFC 2119

OK and here are some examples
of overrides that I don’t think we should allow:

 

Allowing a reference of the
form “#elementid” to reference sub-topic content.

MP: if someone's using a CMS and assigning GUIDs to every element, they
may actually have one unique identifier per element, rather than per topic+element.
That said, I see your point - it would be preferable for the tool to externalize
the reference as properly formed DITA, even if it is internally managed
differently. I can easily see the syntax of the href and conref attributes,
along with the domains and class attributes, as being immutable. That said,
if someone wants to override what they do with that syntax (for example,
fetching the linktext for the subelement from its parent topic), I would
think that's reasonable. 

Allowing new attributes in
specializations that are not based on @props or @base.

MP: that's not a behavior, so is in a different bucket in my mind. The
doctype is a valid specialization or not regardless of what processing
is done with the doctype.

Allowing specializations to
give new meanings to or ignore the meanings of existing attribute/value
pairs (scope=”external”).

MP: maybe there's a difference here between "meaning" and "behavior".
For example, current behavior for scope="external" might be to
open up a new browser window - but in a particular delivery context they
might actually want to popup an intermediate window that says "you're
leaving the website and everything after this is unwarrantied" or
something. Not changing the meaning, but definitely changing the behavior.

Allowing specializations to
ignore @lockmeta.

MP: I can imagine a draft review process that pulled in "author"
info from the target topics, even though lockmeta was set, because they
wanted to use a single map for both review and for final publication, and
they only wanted the author info for review... So in this case, I am imagining
a process that would ignore lockmeta to do a particular metadata fetch
based on business need rather than specialization.

Allowing properties that normally
cascade from a map to a topic to not cascade depending on the specializations
in use.

MP: if a group was doing extensive customization in a map, and was tracking
authorship of the map at a chapter level, I can imagine overriding the
normal cascade of metadata from map to topic to stop author from cascading
and implying authorship of the actual topics rather than of the referencing
map sections.  Again, a customization not based on specialization,
but still definitely an override of default behavior. 

I don’t think this is an all
or nothing decision.  I think we can and should apply the key words
MUST, SHOULD, and MAY differently to different items in the DITA Standard.

MP: I can definitely see the
point of preserving the syntax and meaning of our core attributes - but
not sure how much of subsequent behavior we can really standardize beyond
"don't be an idiot".  For example, we have a "<b>"
element that should be rendered as bold - but if someone has a compelling
reason to override that (like bold text has been reserved for warnings
only), then I think adopters should have the freedom to define their own
output processing, even when it deviates from what's in the spec.

 

   -Jeff

 

From: Michael Priestley [mailto:]

Sent: Tuesday, October 02, 2007 2:41 PM

To: Ogden, Jeff

Cc: 

Subject: RE: [dita] MUST, SHOULD, and MAY, some key words from RFC
2119

 

Yes, I think specific examples are good. Here are some examples off the
top of my head for overriding existing core behaviors:

- conref: override current behavior to limit reuse to a particular set
of targets (eg only allow reuse from topics in a "/reuse" subdirectory)

- map-based linking: create breadcrumb links (to all ancestors) instead
of just parent links 

- link resolution: pull the shortdesc for APIRef topics from their syntax
as well as their shortdesc 

Some of the overrides could be driven by specializations, some could just
be driven by business process requirements.

Michael Priestley

Lead IBM DITA Architect 



http://dita.xml.org/blog/25

"Ogden, Jeff"
<> 

10/02/2007 02:30 PM

To

Michael Priestley/Toronto/IBM@IBMCA

cc

<>

Subject

RE: [dita] MUST, SHOULD, and MAY, some
key words from RFC 2119

 

 
 

Michael wrote: 

> In other words, all behavior, core and specialized, is overrideable.

  

This is the subject of the discussion (item #4 from my previous note) that
we plan to have. The fundamental question that we need to answer is, is
all behavior overrideable, that is, is everything either RECOMMENDED or
OPTIONAL, or are some things truly REQUIRED?

  

Or stated another way, the core as a whole is REQUIRED, but individual
items within the core may be REQUIRED, RECOMMENDED, or OPTIONAL with respect
to specializations.   

  

This doesn’t really get interesting until we get down to specific cases
and we have to figure out when to use MUST / REQUIRED, SHOULD / RECOMMENDED,
and MAY / OPTIONAL 

  

    -Jeff 

  

 

From: Michael Priestley [mailto:] 

Sent: Tuesday, October 02, 2007 2:15 PM

To: Ogden, Jeff

Cc: 

Subject: Re: [dita] MUST, SHOULD, and MAY, some key words from RFC
2119 

  

Looks good, Jeff - with the caveat though that even though the core is
MUST and the specializations are RECOMMENDED or OPTIONAL, a specialization
may introduce behavior that overrides the core.

In other words, all behavior, core and specialized, is overrideable.

Michael Priestley

Lead IBM DITA Architect 



http://dita.xml.org/blog/25

"Ogden, Jeff"
<> 

10/02/2007 02:08 PM

 

To

<>

cc

  

Subject

[dita] MUST, SHOULD, and MAY, some key
words from RFC 2119

  

 

  
 

Included below are some words taken from RFC 2119 on “Key words for use
in RFCs to Indicate Requirement Levels". I think we are going to need
to use this or a similar approach in the DITA standard.

 

1. MUST   This word, or the terms "REQUIRED" or "SHALL",
mean that the 

  definition is an absolute requirement of the specification.

 

2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean
that the 

  definition is an absolute prohibition of the specification.

 

3. SHOULD   This word, or the adjective "RECOMMENDED", mean
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.

 

4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED"
mean 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.

 

5. MAY   This word, or the adjective "OPTIONAL", mean 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 interoperate 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.) 

 

To see the full RFC (its short), see:  http://www.ietf.org/rfc/rfc2119.txt?number=2119

 

Note that as we split the DITA Specification into multiple specifications,
that an entire specification may be REQUIRED, RECOMMENDED, or OPTIONAL,
but within the individual specifications there will be items that are REQUIRED,
RECOMMENDED or which are OPTIONAL.

 

So, if I take the summary from Michael’s recent note:

-        
 everyone needs to support the core;

-        
 specialized support (beyond core
defaults) for the specialized parts of the spec are optional but encouraged,
and should represent an established user community;

-        
 specialized support (beyond core
defaults or standard specialization defaults) for non-standardized user
specializations are up to the user or their partners to provide

 

I can rewrite it using the RFC terms as follows:

-        
 everyone MUST support the core;

-        
 specialized support (beyond core
defaults) for the specialized parts of the spec are RECOMMENDED, and MUST
represent an established user community;

-        
 specialized support (beyond core
defaults or standard specialization defaults) for non-standardized user
specializations is OPTIONAL and up to the user or their partners to provide.

 

Michael, how did I do? 

 

-Jeff