MathML2 review with SpecGL LC

Hi QA WG,

As agreed last month, here comes my review of MathML2 
http://www.w3.org/TR/2003/REC-MathML2-20031021/
through SpecGL:
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/

On the 13 requirements, MathML2 satisfies 8 of them, 2 are N/A, 1 I
couldn't tell and 2 were failed.

On the 25 good practices, 11 were satisfied, 8 failed, 2 N/A and 4
couldn't be determined (my count may be off by 1 unit, sorry)

I've embedded comments on SpecGL itself, labeled with [SPECGL] inside my
review.


===============================
* 13 Requirements (Normative) *
===============================

1.1.A: Include a conformance clause.
Yes: http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.genproc

2.1.A: Define the scope.
Yes: the "introduction" section, and more specifically the "Design goals" section 
give a good overview of what MathML2 defines.
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter1.html#intro.goals

2.2.A: Identify who or what will implement the specification.
Yes: the "MathML conformance" section defines 4 classes of products
(without calling them that way): a valid MathML expression (a piece of
markup), and 3 types of processor: input-conformant, output-conformant
and roundtrip-conformant.
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#id.7.2.1

2.3.A: Make a list of normative references.
No: there is a list of references, but it doesn't distinguish between
normative and informative references.

[SPECGL] As a side remark, I think that the start of the "why care"
section of this particular point is confusing: I don't think WG needs to
know why they should use other technologies ("do not reinvent the
wheel"), but rather why it is important that they make formal references
to these other technologies, and esp. the one that are normative.

3.1.A: Define the terms used in the normative parts of the  
specification.
Yes: there is a glossary section
http://www.w3.org/TR/2003/REC-MathML2-20031021/appendixh.html
and a terminology section for more specific terms used in section 3.
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter3.html#id.3.1.2

3.1.B: Create conformance labels for each part of the conformance model.
Yes: MathML2 defines a "valid MathML expression", a "MathML processor",
with 3 flavors of conformance with well defined labels.
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#id.7.2.1

3.2.A: Use a consistent style for conformance requirements and explain  
how to distinguish them.
No: MathML2 seems to use a declarative style, but uses sometimes
lowercases should/must without a well-defined meaning.

3.2.B: Indicate which conformance requirements are mandatory, which are  
recommended and which are optional.
Yes, but not very clearly; the conformance section lists what the
various processors "must" do, and says it "makes no demands of
individual processors" beyond those.
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.genproc

4.1.B: If the technology is subdivided, then indicate which  
subdivisions are mandatory for conformance.
N/A: the technology is not subdivided.

4.1.C: If the technology is subdivided, then address subdivision  
constraints.
N/A: the technology is not subdivided.

4.3.A: Address Extensibility.
Yes: MathML2 has a section called "MathML 2.0 Extension Mechanisms and
Conformance"
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.extension with 3 specific extensibility hooks in MathML2.0.
Beyond that, it has a section called "Future Extensions", and says it
relies on the XML Extensibility mechanisms, with a defined (but not
required) behavior for processors to react to non-standard elements and
attributes.
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.future

4.4.A: Identify deprecated features.
Not sure: they are indeed identified, but spread across the document.

[SPECGL] the "what does it mean" looks more like a "why care" section;
in particular, it's not clear to me whether this meant that they should
be all listed in a single section, or if having them spread across the
spec is ok.

4.4.B: Define how deprecated feature is handled by each class of  
product.
Yes: http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.deprec

=====================================
* 25 Good Practices (Not normative) *
=====================================

1.1.B: Define the specification's conformance model in the conformance  
clause.
Yes: the conformance section addresses the 3 topics mentioned in SpecGL

1.1.C: Specify in the conformance clause how to distinguish normative  
from informative content.
No

1.2.A: Provide the wording for conformance claims.
No

1.2.B: Provide an Implementation Conformance Statement proforma.
No

1.2.C: Require an Implementation Conformance Statement as part of valid  
conformance claims.
No

2.1.B: Provide examples, use cases, and graphics.
Yes, esp. http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter2.html#fund.examples

2.3.B: Do systematic reviews of normative references and their  
implications.
???: how can this be determined?

[SPECGL] A good practice starting with "Do ..." look more like a
technique. I think we should reword it to say the expected result in the
spec if any, or make it a technique of 2.3.A

3.1.C: Define the unfamiliar terms in-line, and consolidate the  
definitions in a glossary section.
Yes

3.1.D: Use terms already defined without changing their definition.
Yes, MathML2 makes explicit references to definitions e.g. in XML, and
other well-defined Math Notations.

4.1.A: Create subdivisions of the technology when warranted.
Pass: The design goals of MathML doesn't seem to warrant subdivisions
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter1.html#intro.goals

4.1.D: If the technology is profiled, define rules for creating new  
profiles.
N/A: not profiled

4.2.A: Make sure there is a need for the optional feature.
???: how to determine when not in the group?

[SPECGL] can we say something about a result in the spec? probably ok as
is, but worth investigating

4.2.B: Clearly identify optional features.
Not done.

4.2.C: Indicate any limitations or constraints on optional features.
No

4.3.B: If extensibility is allowed, define an extension mechanism.
Yes (see above)

4.3.C: Warn implementers to create extensions that do not interfere  
with conformance.
Yes, somewhat: 
"""Note that the intent of allowing non-standard attributes is not to
encourage software developers to use this as a loophole for
circumventing the core conventions for MathML markup. Authors and
applications should use non-standard attributes judiciously"""
http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.unspecified

4.3.D: Define error handling for unknown extensions.
Yes http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.error

4.4.C: Explain how to avoid using a deprecated feature.
Yes, apparently done relying on CSS (but hard to tell since not all the
deprecated features are listed from a single point)

4.4.D: Identify obsolete features.
N/A: deprecated in MathML2 is probably equivalent to obsolete,  but
since MathML2 processors are encouraged to support MathML1.x, there is
no much difference in this case.

[SPECGL] is this something we need to address in specGL? i.e. support of
specifications across versions?

4.5.A: Define an error handling mechanism.
Yes, http://www.w3.org/TR/2003/REC-MathML2-20031021/chapter7.html#interf.error

5.A:   Define an internal publication and review process.
Can't tell

5.B:   Do a systematic and thorough review.
Can't tell

[SPECGL] since neither of these can be assessed by an external
reviewers, what about removing them from the ICS?

5.C:   Write sample code or tests.
Yup, the examples include sample markup 

[SPECGL] unclear if to be satisfied, this needs to be true for each feature

5.D:   Write Test Assertions.
No, not as far as I can tell

5.E:   Use formal languages and define which from prose and formal  
languages has priority.
No: MathML2 does efine a DTD and an XML Schema:
http://www.w3.org/TR/2003/REC-MathML2-20031021/appendixa.html#parsing.usingdtdt
but doesn't not address the priority of prose over formal language.

Dom
-- 
Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org