OASIS Darwin Information Typing Architecture (DITA) TC

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

Thought you would all be interested to see that the DITA TC is taking a hard look at how it uses keywords as a result of the new guidlines.  /chet  ---------- Forwarded message ---------- From: Kristen James Eberlein < kris@eberleinconsulting.com > Date: Tue, Mar 4, 2014 at 10:28 AM Subject: [dita] RFC-2119 terminology To: DITA TC < dita@lists.oasis-open.org > 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) --------------------------------------------------------------------- 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 -- /chet  ---------------- Chet Ensign Director of Standards Development and TC Administration  OASIS: Advancing open standards for the information society http://www.oasis-open.org Primary: +1 973-996-2298 Mobile: +1 201-341-1393  Check your work using the Support Request Submission Checklist at  http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html   TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin Follow OASIS on: LinkedIn:     http://linkd.in/OASISopen Twitter:         http://twitter.com/OASISopen Facebook:   http://facebook.com/oasis.open Attachment: OASIS-Keywords-Directives-v6.0-1.pdf Description: Adobe PDF document

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Chet, Thanks! Hope you are having a great day! Patrick On 03/04/2014 11:05 AM, Chet Ensign wrote: > Thought you would all be interested to see that the DITA TC is > taking a hard look at how it uses keywords as a result of the new > guidlines. > > /chet > > ---------- Forwarded message ---------- From: *Kristen James > Eberlein* <kris@eberleinconsulting.com > < mailto:kris@eberleinconsulting.com >> Date: Tue, Mar 4, 2014 at > 10:28 AM Subject: [dita] RFC-2119 terminology To: DITA TC > <dita@lists.oasis-open.org < mailto:dita@lists.oasis-open.org >> > > > 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 < http://www.eberleinconsulting.com > +1 > 919 682-2290 <tel:%2B1%20919%20682-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 > > > > > -- > > /chet ---------------- Chet Ensign Director of Standards > Development and TC Administration OASIS: Advancing open standards > for the information society http://www.oasis-open.org > > Primary: +1 973-996-2298 Mobile: +1 201-341-1393 > > Check your work using the Support Request Submission Checklist at > http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html > > > TC Administration information and support is available at > http://www.oasis-open.org/resources/tcadmin > > Follow OASIS on: LinkedIn: http://linkd.in/OASISopen Twitter: > http://twitter.com/OASISopen Facebook: > http://facebook.com/oasis.open > > > > --------------------------------------------------------------------- > > 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 > > - -- Patrick Durusau patrick@durusau.net Technical Advisory Board, OASIS (TAB) Co-Chair, OpenDocument Format TC (OASIS) Editor, OpenDocument Format TC, Project Editor ISO/IEC 26300 Former Chair, V1 - US TAG to JTC 1/SC 34 Convener, JTC 1/SC 34/WG 3 (Topic Maps) Co-Editor, ISO 13250-5 (Topic Maps) Another Word For It (blog): http://tm.durusau.net Homepage: http://www.durusau.net Twitter: patrickDurusau -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQIcBAEBAgAGBQJTFgJtAAoJEAudyeI2QFGogzAP/ip+MiW3LxPdxo3YwXzpnvxp n+JX9fw/0a4FRfvXruECPHa87EeNmZif6ZmO+ie3cjD3RA7EqRUVG7bBv9qXf3GL 1V7b1Qcirb9MSkmrPuyt1Bx9kOOV63AA6c42WZTw6kJQ8d2zmEb6MHorT5WAyv6U lALpLlrKHDLHhxC1IPEvxluqffheULm+5cuKO/g/kNs5fEhICUG6teaKPEXQ8vlW pECn/EgtVwxJnj+y/EOSu6wCqlsC8HGD7A2oZbsA9O0QAMz9Q5OW4OI2QwAHqcSz eWKr89VU9KVS4/HPZ1BraX23ze9Le/CXSw3W+0u7PX3LaebgpPsCUa9/IcxiA5zN LeEwrr1FLiwpYIueKa+4AJXN2esHOU/tEQO41dwy0mr14JHzkOrIZfPCGx/Feb7V EeDITeRlGxCfP7Li0D64+QiUrwkESEWhVDTO9bm00BRRsQ9oh1tYn/FNp9NLk/S8 7x6OKyOTLGMYRkNDa/rLAY77BN332oOLuI/YKN8cHMt9Fe0Vo1kC7y8uw2FqvpXC M7VDEAxJdEdqDcdwNmZI4CXr1HeIcPsK8JwBt3IenjiIMhNP+AFrZBwV3VgFvGS3 pWcyGbhRRxUyI1J/C8Ar6QDFt5cKfOzP63vQ1c480ls36PdSOndMzNvFvSXse/vR hdgUqGpIpXgJFFuhWLdu =cN/+ -----END PGP SIGNATURE-----