RE: [office] Conformance, Specification Quality and OASIS Recommendations

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

I have looked over Rob's proposal and Michael's response in formulating my
own analysis here.

It is my thinking that there is mostly alignment on the items below and we
are now refining the treatment.  I use Rob's numbering (with its implicit
0-item).

I don't see obvious solution to items 8+10.  I think we need to look at the
cases more carefully and determine what language works.  We might want to
factor those two out for more-careful separate examination while going ahead
with the other bits.

 - Dennis

DETAILS

0. CONFORMANCE GUIDELINES AND SPECIFICATION TEMPLATE

I find the guidelines valuable and I believe we should work to honor their
spirit as well as we can.  I find the checklist at the end a very good test
of how well we have done.

I want to point out that the current OASIS Templates for specifications
require that the conformance section be the *final* non-appendix section of
the specification.


1. NORMATIVE LANGUAGE

I am fond of the bold-face terms.  However, I think that whether or not we
use the bold (or capitalized, in plaintext) presentation, we should not use
those terms in any other way.  That way, there is no ambiguity on whether or
not we have forgotten to use bold or the bolding is an editorial mistake.

With regard to language, my experience is that where words like "may" and
"may not" are used, it is often the case that such statements are extraneous
or, if felt important as descriptive information, "can" and "can not" should
be used as observations concerning possibility, not requirement,
optionality, or permission.  (Note that the automatic text used in the
cross-references about where elements and attributes can occur is best
restated using can rather than may, since MAY and NEED NOT must tie to a
conformance target and the use of CAN and CAN NOT do not have that
constraint.)

I think as we review the specification to eliminate or replace over-casual
language and assure that we have established the desired connection to a
conformance target, this will be sorted out.

Also, if we take on an approach where (1) every normative statement be set
off and identifiable for cross-reference purposes and that (2) each such
statement makes its conformance target explicit, we will train ourselves to
be stingy with the use of those terms.

2. NOTATION

Agreed.  We should indicate the use of monospace and quoted terms that
represent literal items of an XML document.

The additional notational convention around the understood namespace
bindings for prefixes and QNames used in the specification can be there or
in 1.3 where namespaces are described.  (Now that I see this discussion, I
rather favor the idea of putting it in as simply notation.)

3. THE DOCUMENT PROCESSING AND CONFORMANCE SECTION

I agree to the separation.  The Conformance Section should move to the end
of specification, satisfying the current OASIS Template for specifications.

The Document Processing section can remain where the combined section is
now.


4. ORGANIZATION OF CONFORMANCE CLAUSES IN SECTIONS

I think this is an editorial concern that we should address, but we can
refine that as we go, so long as there are no forward references to them.
(We do need to think about that, though.)

5. NAMING THE SECTION

I think Conformance and Document Processing should be separated (see 3), so
the simplified naming follows.

6-7.  HOW WE TALK ABOUT CONFORMING THINGS WITHOUT CIRCULARITY

This does take further work.  We also have to deal with the different
document types/structures involving assemblages of XML documents in a
package and in single XML documents, and how they are even usable together.
This may be an open challenge.

In some cases, the problem is that we are being too informal.  For example,
as I recall, we speak of packages as a representation of ODF Documents.  It
becomes useful to say, "When an ODF Document is represented in a package ...
" As opposed to speaking of "When an ODF Document is an ODF Package," etc.  

[[Off topic: I was reminded of how important it can be to maintain a formal
distinction by the way the [xml-names] specification distinguishes between
an XML namespace (semantic notion), expanded name (semantic notion),
namespace name (semantic notion), and local name (semantic notion) from (1)
how a namespace is identified (the URI reference) and (2) the
syntactical/lexical forms that have those semantic interpretations:
qualified name, QName, local part, etc.  It is difficult to get this exactly
right, and I could not swear that [xml-names] does it perfectly.  But there
are ways we can avoid mistakes of name and mention and use, and of form
versus interpretation.]]   

8. LANGUAGE AROUND CONFORMANT AND EXTENDED DOCUMENTS

I agree that we need to simplify here.  I also notice that there is already
a problem with the terms in use and there may be a problem with statements
in the specification.  

8.1 The second problem is that we speak of conditions that apply to
conformant or conforming documents in many places in the specification.
These conditions apply equally to extended documents but it is not obvious
how to establish that.

 8.1.1 One way to do this is to have the conformant documents be a subset of
the extended documents.  That is usually how this is done, and it is all
right technically but probably not satisfying.  Another way is to be more
explicit about the conformant document that must be derivable from any
extended document.  That may be the only way to carry out the current
two-level approach.

 8.1.2 Another way, which I expect is even more objectionable, is to have
extended ODF documents and pure ODF documents and have them be,
collectively, conformant documents.  See 8.2.

8.2 The first problem is that people are already wanting to make
qualification of the use of conforming document to emphasize that what is
meant is the pure/plain conformant document and not any extended document.
I see "pure" and "minimal" used this way, each reflecting a position on the
part of the user.  Likewise I have already encountered more-pejorative
substitutes for "extended."  

8.3 We are also running into problems with our own cookie cutter, seeming to
neglect the case where a consumer may well accommodate some foreign elements
and attributes while failing to support/recognize others.  Similarly, an
extended producer is not confined to producing only extended documents, as I
see it, although a conforming producer is confined to producing only
conforming documents.  An output from an extended producer can be a
conforming document.  Our language may need to be more nuanced in these
respects.  (See 10 below)

9. SCHEMAS  

It is my impression that there is now only one schema for the principle
OpenDocument document structure.   That is, the one schema file provides
exactly what the strict schema file provided, but flattened into a single
file.

Discussion of there being a strict schema needs to be removed, as should the
Appendix on that topic.

10. WHETHER CONFORMING DOCUMENTS QUALIFY AS EXTENDED DOCUMENTS

This point comes at the subset question.  If conforming documents are not
subsets of the extended documents, then we need to be very careful about
what an extended producer is, what we mean when we say conforming/conformant
in many places in the specification, and also how we defined extended
documents.

If an extended document is one that DOES have (rather than CAN have) foreign
elements and attributes (and maybe other things that quack like extensions
or implementation-determined-only features), that might work but the
connection to conformant document must be drawn more carefully.  I stumble
upon this under (8) as well.

11. INTENTIONALITY

Yes, get rid of that.

12. PARSE AND INTERPRET

I think there are two parts to this.  One is using a better term than "parse
and interpret."  The other is to define conformance targets better.   

I want to point out that the schema does provide minimum structures for the
different document types although omitting content.xml from a package does
leave an odd case not accounted for in the schema.  We should connect the
dots better though.

If we want to add core levels tied to the kind of feature support
illustrated in the non-normative Appendix, that would be interesting but I
would not want us to attempt that at this point (preferring to see ODF 1.2
be completed in my lifetime).  I think that is seriously an ODF-Next
challenge, hopefully with substantial material available from the Adoption
and Interoperability and Conformance TCs as well as other stakeholder
communities.

-----Original Message-----
From: Michael.Brauer@Sun.COM [mailto:Michael.Brauer@Sun.COM] 
http://lists.oasis-open.org/archives/office/200903/msg00014.html
Sent: Monday, March 02, 2009 08:26
To: robert_weir@us.ibm.com
Cc: office@lists.oasis-open.org
Subject: Re: [office] Conformance, Specification Quality and OASIS
Recommendations

Hi Rob,

first of all, I agree to most of your items below.

Some comments are inline.

On 03/01/09 19:12, robert_weir@us.ibm.com wrote:
http://lists.oasis-open.org/archives/office/200903/msg00002.html
[ ... ]
> 1)  CD 01 Section 1.2 says, "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."  I think the " bold letters" restriction is a 
> carry over from our earlier IETF usage.  This is not typical in ISO 
> standards.  If we have this clause, as written, it will immediately lead 
> the reviewer to ask, "What does 'shall' or 'should not' mean when not in 
> bold letters'?"  I think we would be much better off if we removed this 
> quirky convention.  All uses of shall/should/may etc. would then be 
> expressing provisions, when used in normative clauses.  Of course, if 
> there are any uses of these terms where we do not wish to state a 
> provision then we should chose an alternative phrasing.

I personally do like the approach of having marked the use of "may" and
"should" and so on if they are used as a keyword, and I'm wondering if
it is really an issue if they are sometimes used in just the meaning
they have as English words. They are English words that have their
meaning in the English language, so why are they loosing their meaning
if they are sometimes used in the very particular meaning defined by the
control language? Not being an English native speaker, I'm also
wondering whether there is always an alternative phrase one could use.

Anyway, I have also no objections if we remove the "bold" convention,
provided that we carefully check each individual case whether
interpreting the "may", "should" as a keyword still would be correct.

> 
> 2) In the same section, 1.2 "Notation" we should also explain the textual 
> and typographical convention used for denoting quoted element names, 
> attribute names and attribute values.  I've seen one reviewer confused by 
> this, so it is worth stating the convention (monospace) explicitly.

+1. I think Patrick can just add something.

> 
> 3) In section 1.5, "Document Processing and Conformance", the document 
> processing piece is out of place.  Obviously we may have document 
> processing conformance requirements, but the OASIS guidelines suggest that

> these be stated under the appropriate  conformance "target", i.e., 
> Consumer or Producer, and not set into its own clause.  In other words, if

> we put Document Processing into its own section, then we can point to it 
> from the Conformance clause.

What you mean by this is probably that there should be one section
"Conformance" and one section "Document processing", but no section
"Document processing and conformance" anymore. Would be okay for me.
> 
> 4). The heading of 1.4 are not consistent.  In some cases the top level 
> headers, like 1.4.4 "Consumer Conformance" indicate a conformance clause. 
> But in other cases, like 1.4.3 "Producer Conformance" no provisions are 
> expressed.  1.4.3 is merely used to group 1.4.3.1 and 1.4.3.2.  Maybe this

> is OK?

If I remember it correctly, then the ISO directives do not allow to have
a section that has just one sub section.  We have two producer classes
but only one consumer class. If we want to group the consumers then we
get the structure we have right now.
> 
> 5) I recommend that section 1.4 be called "Conformance". If we want to 
> have a separate section on "Document Processing" then that is OK.  If we 
> want to specify document processing provisions in section 1.4, then that 
> is OK.  But we should have 1.4 be clearly and unambiguously be called 
> "Conformance".

That's okay for me.

> 
> 6) 1.4.2.1 is either circular or insufficiently defined  We have now "A 
> conforming OpenDocument document shall adhere to the specification 
> described in this document...".  But what does it mean to "adhere"?  If 
> this is the same as to conform, then this is circular.  If it means 
> something else, then it is undefined.  So the question is:  Did we mean to

> require something here?  If so, what?

SVG uses a similar phrase:

http://www.w3.org/TR/SVG11/conform.html#ConformingSVGDocuments

My reading of this is that a conforming document must not only meet the
requirements we state in the conformance section, but all we state in
the specification document, unless they are marked informative. Maybe it
is not required to explicitly state that. Maybe native English speakers
find a better phrase for this.

> 
> 7) 1.4.2 "If the document is an OpenDocument package..."  this is circular

> as well, since we don't define "OpenDocument package" except in Part 3. So

> we're really saying "if the document is A, then it shall conform with A". 
> To me it feels like there are two conformance targets masquerading as one 
> here: Packaged ODF Document and Single XML File ODF Document.  If we 
> define these each as their own conformance target, then we can easily 
> combine them and say "A conforming OpenDocument document is either a 
> Packaged ODF Document or a Single XML File ODF Document."  In other words,

> build the definition up from the individual targets.  Otherwise we get 
> these circular problems.

That's a good point.

> 
> 8) I'm not sure I like "conforming" to be part of the name of a 
> conformance target or conformance class.  If the conformance target is 
> called "conforming extended opendocument document" then what do you call 
> it when such a document does not conform?  For example, it has an error in

> the core part of the schema and is not valid.  Is it then a "nonconforming

> conforming extended opendocument document"? So I would not have 
> "conforming" be part of the name of any conformance target or class.

Would removing the italic formatting from the term "conforming" be
sufficient to address this concern?

> 
> 9) We mention "schema" and "strict schema" in the conformance clause, but 
> we don't really connect to it. In many places of the text we refer to "the

> schema defined by this specification".  We need to be precise here.  I 
> think upfront, before we even get to the conformance clause we need to 
> state something like: "This Part consists of a specification and an 
> associated schema definition file.  The schema definition file is named 
> odf12-cd01.rng". Otherwise the reader is lead to believe that the schema 
> is in the specification.  In fact we should probably be clearer

+1. A link to the specific schemas is indeed missing. I will think about
where we best could add it.

> 
> 10)  1.4.3.1 "It shall not produce any non-conforming OpenDocument 
> document of any kind" contradicts the next  line "It may produce 
> conforming OpenDocument extended documents".  A conforming extended 
> document is not at the same time a conforming non-extended document, so 
> obviously if a producer may produce an extended document, it is producing 
> something that is a non-conforming non-extended document.  We can probably

> clean this up if have documents declare, with an attribute on the root of 
> context.xml or via some similar mechanism, which conformance class they 
> belong to.  That way 1.4.3.1 can be a simple consistency test.

I agree that this may make sense.

> 
> 11) 1.4.3.1 says "It shall not produce any non-conforming OpenDocument 
> document of any kind" while 1.4.3.2 says "It shall not intentionally 
> create any non-conforming OpenDocument extended documents of any kind.". I

> don't think we can test "intent" so we should probably take out that 
> qualification.

I wanted to remove the term "intentionally" but seem to have missed that
occurrence.

> 
> 12) 1.4.4 "parse and interpret" -- I'd like to see if we can make a more 
> testable requirement here.  It may not be possible, since a Consumer 
> ranges from a full text editor down to possibly a Zip program or an XML 
> parser.  Our practical problem is that we have not defined a minimal set 
> of elements which a Consumer must understand.   In the general case, this 
> is probably right.  But we might consider also defining conformance 
> targets according to Appendix D.  So define an "ODF Text Consumer", "ODF 
> Spreadsheet Consumer", etc. and require interpretation of corresponding 
> ODF features.   I think this would be a tremendous gain for 
> interoperability.

I agree that this may make sense.

Best regards

Michael


-- 
Michael Brauer, Technical Architect Software Engineering
StarOffice/OpenOffice.org
Sun Microsystems GmbH             Nagelsweg 55
D-20097 Hamburg, Germany          michael.brauer@sun.com
http://sun.com/staroffice         +49 40 23646 500
http://blogs.sun.com/GullFOSS

Sitz der Gesellschaft: Sun Microsystems GmbH, Sonnenallee 1,
	   D-85551 Kirchheim-Heimstetten
Amtsgericht Muenchen: HRB 161028
Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
Vorsitzender des Aufsichtsrates: Martin Haering




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