[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [office] Conformance, Specification Quality and OASIS Recommendations
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]