Re: [office-comment] ODF 1.2 References

[marbux <marbux@gmail.com>]

On Sun, Feb 22, 2009 at 5:46 AM, MURATA Makoto (FAMILY Given)
<eb2m-mrt@asahi-net.or.jp> wrote:
> First, I believe that ODF 1.2 cannot become an ISO/IEC standard unless it
> ALWAYS uses "shall" or "should" as specified in Annex H of [ISO/IEC
> Directives].  If "shall" or "should" is used incorrectly, I believe
> there will be comments from member bodies and comments from ITTF.
> Comments from ITTF cannot be turned down.  Thus, the sentence you
> quoted cannot appear in the next edition of ISO/IEC 26300, I believe.

The committee draft has issues in this area, although I note that
ISO/IEC:26300-2006 has even more. Some WordPerfect word counts (not
yet confirmed by a second run on a different word processor):

Frequency of keyword terms indicative of options and recommendations:

may 3,490
*may not 19
*optional 26
should 295
should not 12

Total 3842

Frequency of keyword terms indicative of mandatory requirements:

*must 207
*must not 13
shall 80
shall not 22

Total 322

Further caveat: this is for the entire committee draft including
informational portions.

The terms marked with an asterisk above other than "may not" are
apparently leftovers from OASIS ODF 1.0, which used the RFC 2119
requirement keyword definitions. Their occurrences should be replaced
with their ISO/IEC equivalents.

"May not" might pass muster when viewed in isolation because "may" is
a defined term in the ISO/IEC Directives Part 2 Annex H. But when you
skim the passages that use the term in the committee draft, the term
seems sometimes intended to express permission, in others a
prohibition, and in still others it is not clear to me which sense was
intended.

But bottom line, it looks like there's some editorial work to do on this issue.

On related matters:

-- Present language in section 1.2 reads:

"Within this specification, the key words "shall", "shall not",
"should", "should not" and "may" are to be interpreted as described in
Annex H ..."

The phrase "are to be" should change to "shall be" since "shall" is
the relevant term defined by the cited Directives section as imposing
a mandatory requirement. If the convention expressed in the later
portion of the same sentence limiting the ISO/IEC definitions'
applicability only to those terms when marked by bold face is retained
(discussed below), the "shall" should acquire the bold face attribute.

Methods of expressing a requirement other than by using the terms
defined as imposing requirements should be avoided. They impede
identification of what is and is not mandatory in sum. E.g., the
editor has begun marking ISO/IEC keywords with a custom style in the
committee draft. The automated processing of relevant style
information will be impeded if a standardized vocabulary for
expressing requirements is not used. E.g., if "are to be" is regarded
as establishing a requirement, how might it be classified when the
custom style for ISO/IEC requirement keywords is processed?

On a closely related matter, the committee draft's section 1.2 states
that the requirement keywords only acquire the meanings given by
ISO/IEC Directives when set in bold face. This is problematic in
several different ways.

1. What meaning do those terms have when not set in bold face? By
implication their meanings may differ in that circumstance. But how
they differ in that context is unspecified.

2. This is no small problem by historical measure. All previous
published versions of ODF include many instances of requirement
keywords that should have been set in bold face but were not.

3. The reliance on bold face (or other text attributes) as an
indicator of requirements can neither be sent as plain text email or
easily be converted to plain text email without manual revision of
emphasized strings or loss of data as to what is and is not a
requirement keyword. I strongly suspect this is the reason that nearly
all IT standards I've looked at use all-capitalized characters for
requirement keywords rather than bold face or some other text
attribute.

4. I raise the question of whether there is any remaining need to
distinguish between relevant terms as to when the ISO/IEC definitions
apply. However, I caveat that I do not know the answer to that
question. But there are indications that there may not be such a need.

This was a convention adopted in OASIS ODF 1.0. That specification
depended on RFC 2119 requirement keyword definitions rather than
ISO/IEC definitions. Under the RFC 2119 definitions, the meaning of
"may" and "optional" is modal, with two conditional mandatory
interoperability requirements.

Under such circumstances, there was a reasoned need to distinguish
when those terms had the RFC 2119 meaning and when they had their
common and ordinary meaning of "permission."

However, ISO/IEC definitions do not define "optional" and their
definition of "may" adopts the common and ordinary meaning of the
term. The need to distinguish between circumstances when "may" has
different meanings is no longer apparent to me.

I have noticed no aspects of the ISO/IEC definitions that seem to
conflict with common and ordinary meanings of terms defined. I
therefore raise the question of whether there is any remaining need to
distinguish between circumstances when the terms have their ISO/IEC
definitions and when they do not.

If there in fact remains no reason for distinguishing between
circumstances when the terms take the ISO/IEC definitions and when
they do not, then the word processor's global find and replace feature
can be used by the editor to provide whatever emphasis is desired, if
any, for the terms in the text. It might be that only the usage of the
"shall" and "shall not" terms might need checking in context to ensure
that they are not in informational portions of the specification.

5. If the convention is preserved of distinguishing between
circumstances when the terms take the ISO/IEC definitions and when
they do not, the meaning of those terms when they are not emphasized
should be defined.

6. The present committee draft does not yet have the majority of
requirement keywords in the text marked in any way. Whatever
resolution is made of the issues above, at least one committee draft
should be produced that has the the full text emphasized as envisioned
for review by TC members prior to the public review version.

ODF history teaches that thorough review is necessary to avoid a
repeat of the specification being adopted without all terms being
marked with the emphasis where appropriate.

Best regards,

Paul E. (Marbux) Merrell, J.D.

-- 
Universal Interoperability Council
<http:www.universal-interop-council.org>