OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

office message

[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]