[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: UKE comment 1, was: Re: [office] Controlled Vocabulary
Patrick, all, I agree to your conclusions, and have changed the specification as follows: Section 1.2 Notation changed from Within this specification, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119] if they appear in uppercase bold letters. to Within this specification, the key words "shall", "shall not", "should", "should not" and "may" are to be interpreted as described in Annex H of [ISO/IEC Directives] if they appear in bold letters. In the bibliography, I have replaced the [RFC2119] enzty with [ISO/IEC Directives]: [ISO/IEC Directives] ISO/IEC Directives, Part 2 Rules for the structure and drafting of International Standards, 2004 All keywords appear now in bold letters only rather than in captialized bold letters. All occurencies of "MUST" and "MUST NOT" where replaced with "shall" and "shall not" (please note that I have marked only those ISO keywords with ** that actually have changed; all other keywords appear bold in the specification, too, allthough I did nor mark them below): Section 1.5 The paragraph Conforming applications either MUST read documents that are valid against the OpenDocument schema if all foreign elements and attributes are removed before validation takes place, or MUST write documents that are valid against the OpenDocument schema if all foreign elements and attributes are removed before validation takes place. now reads Conforming applications either *shall* read documents that are valid against the OpenDocument schema if all foreign elements and attributes are removed before validation takes place, or *shall* write documents that are valid against the OpenDocument schema if all foreign elements and attributes are removed before validation takes place. The paragraphs Foreign elements MAY have an office:process-content attribute attached that has the value true or false. If the attribute's value is true, or if the attribute does not exist, the element's content SHOULD be processed by conforming applications. Otherwise conforming applications SHOULD NOT process the element's content, but MAY only preserve its content. If the element's content should be processed, the document itself MUST be valid against the OpenDocument schema if the unknown element is replaced with its content only. Conforming applications MUST read documents containing processing instructions and SHOULD preserve them. now read Foreign elements may have an office:process-content attribute attached that has the value true or false. If the attribute's value is true, or if the attribute does not exist, the element's content should be processed by conforming applications. Otherwise conforming applications should not process the element's content, but may only preserve its content. If the element's content should be processed, the document itself *shall* be valid against the OpenDocument schema if the unknown element is replaced with its content only. Conforming applications *shall* read documents containing processing instructions and should preserve them. Section 1.7 The paragraphs For office documents that conform to this specification but are not contained in a package, it is RECOMMENDED to use the MIME type text/xml. It is RECOMMENDED that only MIME types and extensions that have been registered according to [RFC2048] are used for office documents that conform to this specification. It is also RECOMMENDED that the MIME types and extensions listed in appendix C are used where appropriate. now read Office documents that conform to this specification but are not contained in a package *should* use the MIME type text/xml. Only MIME types and extensions that have been registered according to [RFC2048] *should* used for office documents that conform to this specification. The MIME types and extensions listed in appendix C *should* be used where appropriate. Section 2.4.6 The paragraph To represent a text cursor position within a document, a processing instruction with PITarget opendocument (see §2.6 of [XML1.0]) SHOULD be used. The name of the cursor position processing instruction, cursor-position, MUST follow the PITarget opendocument. The processing instruction may have arbitrary application specific attributes, for instance to connect the cursor position with a certain view of the document, where the views themselves are specified as application specific settings. The syntax for these attributes MUST be the same as for attributes within XML start tags. now reads To represent a text cursor position within a document, a processing instruction with PITarget opendocument (see §2.6 of [XML1.0]) should be used. The name of the cursor position processing instruction, cursor-position, *shall* follow the PITarget opendocument. The processing instruction may have arbitrary application specific attributes, for instance to connect the cursor position with a certain view of the document, where the views themselves are specified as application specific settings. The syntax for these attributes *shall* be the same as for attributes within XML start tags. Section 3.1.1 The paragraphs Conforming applications MAY use the generator string to work around bugs that exist or existed in certain applications, but MUST NOT deliberately implement a different behavior depending on a certain generator string. If the application that created the document could not provide an identifier string, the application does not export this element. If another application modifies the document and it cannot provide a unique identifier, it MUST NOT export the original identifier belonging to the application that created the document. now read Conforming applications may use the generator string to work around bugs that exist or existed in certain applications, but *shall not* deliberately implement a different behavior depending on a certain generator string. If the application that created the document could not provide an identifier string, the application does not export this element. If another application modifies the document and it cannot provide a unique identifier, it *shall not* export the original identifier belonging to the application that created the document. Section 17.4 The paragraph If a MIME type for a document that makes use of packages is existing, then the package SHOULD contain a stream called "mimetype". This stream SHOULD be first stream of the package's zip file, it MUST NOT be compressed, and it MUST NOT use an 'extra field' in its header (see [ZIP]).. now reads (please note that I have also removed the duplicate dots at the paragarph end) f a MIME type for a document that makes use of packages is existing, then the package should contain a stream called "mimetype". This stream should be first stream of the package's zip file, it *shall not* be compressed, and it *shall not* use an 'extra field' in its header (see [ZIP]). Section 17.5 The paragraph URIs that reference a sub file of a package MUST be relative, and they MUST NOT contain paths that are not within the package. This especially means that sub files of a package MUST NOT be referenced by an absolute URI. now reads IRIs that reference a sub file of a package *shall* be relative, and they *shall not* contain paths that are not within the package. This especially means that sub files of a package *shall not* be referenced by an absolute IRI. Appendix C The paragraph Please check [MIMETYPES] before using these MIME types. If a MIME type is not listed there, it is RECOMMENDED to use the MIME type that is the result of inserting "x-" behind the "/" character (i.e. application/x-vnd.oasis.opendocument.text). now reads Please check [MIMETYPES] before using these MIME types. If a MIME type is not listed there, the MIME type that is the result of inserting "x-" behind the "/" character (i.e., application/x-vnd.oasis.opendocument.text) *should* be used. Please review these changes and let Patrick an me know any concerns you have. Best regards Michael Patrick Durusau wrote On 05/17/06 12:28,: > Michael and Friends, > > I have compared RFC 2119 and Annex H of the ISO Directives and prepared > the following mapping: > > MUST/SHALL > > RFC 2119: These as synonyms, that is they mean the same thing and may be > used interchangably without loss of precision. > > Or, in the words of RFC 2119: > > 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the > definition is an absolute requirement of the specification. > > Compare that to SHALL in ISO Annex H (MUST is not given as an alternative): > > "The verbal forms shown in Table H.1 shall be used to indicate > requirements strictly to be > followed in order to conform to the document and from which no deviation > is permitted." > > Table H. 1 lists shall with the following alternative phrasing for use > in different contexts: > > is to > is required to > it is required that > has to > only … is permitted > it is necessary > > Conclusion: We can change MUST to shall without loss of meaning or > changing the meaning of the use of MUST/SHALL in ODF. > > MUST NOT/SHALL NOT: > > RFC 2119: Again, these are synonyms. > > In the words of RFC 2119: > > 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the > definition is an absolute prohibition of the specification. > > > Compare that to "shall not" (must not is not an alternative) in ISO > Annex H: > > Same header, and provides the following alternative forms for shall not: > > is not allowed [permitted] [acceptable] [permissible] > is required to be not > is required that … be not > is not to be > > Conclusion: We can change MUST NOT to shall not without loss of meaning > or changing the meaning of the use of MUST NOT/SHALL NOT in ODF. > > BTW, a footnote in Annex H notes the following reason to avoid the use > of "must" for "shall": > > "Do not use “must” as an alternative for “shall”. (This will avoid any > confusion > between the requirements of a document and external statutory > obligations.)" > > SHOULD/RECOMMENDED: > > RFC 2119 provides: > > 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. > > > ISO Directives, Annex H says (for should/should not): > > The verbal forms shown in Table H.2 shall be used to indicate that among > several possibilities > one is recommended as particularly suitable, without mentioning or > excluding others, or that a > certain course of action is preferred but not necessarily required, or > that (in the negative form) > a certain possibility or course of action is deprecated but not prohibited. > > Conclusion: Recommended can be changed to should (4 occurrences, see my > earlier summary) and reference made to Annex H without loss or changing > of the meaning used for should/recommended in ODF. > > SHOULD NOT: > > RFC 2119: > > 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. > > > Conclusion: Same as for should/recommended, no change in meaning. > > MAY > > RFC 2119 says: > > 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.) > > > MAY and OPTIONAL are synonyms (note that OPTIONAL does not appear > outside of the terms list in 1.2 Notation) > > ISO Directives, Annex H says: > > The verbal forms shown in Table H.3 shall be used to indicate a course > of action permissible > within the limits of the document. > > The forms listed there are: > > may, or > > is permitted > is allowed > is permissible > > Conclusion: Same as MAY as used in ODF so no change in meaning. > > Note that REQUIRED and OPTIONAL, along with SHALL and SHALL NOT never > appear outside of 2.1, Notation. > > Apologies for not having done this by the numbers sooner. > > After reviewing the language, I think we will all conclude that we can > conform to the ISO Directives usage without changing the meaning of any > parts of ODF. (but that is just my opinion, sing out if you disagree). > > Hope everyone is having a great day! > > Patrick > > > > -- Michael Brauer Phone: +49 40 23646 500 Technical Architect Software Engineering Fax: +49 40 23646 550 StarOffice Development Sun Microsystems GmbH Sachsenfeld 4 D-20097 Hamburg, Germany e-mail: michael.brauer@sun.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]