Review of MathML 2.0 against QA Framework: Specification Guidelines

Based on SpecGL W3C Working Draft 10 February 2003

Review-assignment skeleton for document version:
http://www.w3.org/TR/2003/WD-qaframe-spec-20030210/

Reviewed by: Andrew Thackrah
Date completed: 30 April 2003

Front matter

Document Reviewed: Mathematical Markup Language (MathML) Version 2.0 (2nd Edition)

This document is a review of MathML 2.0 regarding its conformance to the guidelines of the QA Framework document: Specification Guidelines

The specification met (the requirements of) 16 out of 18 applicable Level 1 checkpoints.
The specification met (the requirements of) 9 out of 13 applicable Level 2 checkpoints.
The specification met (the requirements of) 8 out of 10 applicable Level 3 checkpoints.

See the Back matter at the end of the document for specific comments

Guidelines and Checkpoints

Guideline 1. Define Scope.

The spec. has good general background and specific markup background sections that cover scope.

1.1 Include the scope of the specification. [Priority 1]

Yes. Section 1 in good detail.

1.2 Illustrate what is in scope [Priority 2]

Yes. Scope is discussed in section 1.3.

1.3 Provide Usage Scenarios. [Priority 3]

Yes. Particularly sections 1.3.1, 1.3.2 and 2.2.

1.4 Provide examples. [Priority 2]

Yes. There are many functional examples throughout the text.

Guideline 2. Identify what needs to conform and how.

The classification of products varies a little with context. For example in some contexts products are grouped according to their function on presentation and content and in other contexts according to input/output/roundtrip handling of the markup. For conformance purposes only one product is defined: a "MathML processor". Some clear mapping between the classifications in the various might help although it is mostly clear.

2.1 Identify all classes of product. [Priority 1]

Yes. Four product classes are identified: renderers, processors, translators and editors.

2.2 For each class of product, define the conformance requirements. [Priority 1]

Yes. See section 7.2

2.3 Identify which of the categories of object are specified in the document as a whole. [Priority 3]

Yes. Presentation and Content are identified.

2.4 If there are several classes of products, define their relationships and interaction with other dimensions of variability. [Priority 2]

Yes. Section 7 covers intercommunication of rendering and processing tools.

Guideline 3. Specify conformance policy.

The spec. uses the term 'conformance' whereas the linked guidelines document uses the term 'compliance' even though the content of the guidelines document is essentially the same as the spec. If there are to be separate documents covering conformance/compliance it is recommended they use a single term. QAWG prefers 'conformance'.

3.1 Specify any universal requirements for minimum functionality. [Priority 2]

Yes. This is detailed in section 7 and also in a referenced (and linked) document "MathML 2.0 Compliance Guidelines".

3.2 If special conformance terms are used, include a definition in the specification. [Priority 1]

Yes. defines "MathML processor" in conformance section.

3.3 Justify any usage of a dimension of variability [Priority 1]

Guideline 4. Address the use of profiles to divide the technology.

The specification makes no use of profiles. The checkpoints in this section are not applicable (N/A)

4.1 Indicate whether or not the use of profiles is mandatory for conformance. [Priority 1]

N/A

4.2 If profiles are chosen, define any minimal requirements. [Priority 2]

N/A

4.3 If profiles are chosen, define their relationships and interaction with other dimensions of variability. [Priority 2]

N/A>

4.4 If profiles are chosen, address rules for profiles. [Priority 2]

N/A

Guideline 5. Address the use of modules to divide the technology.

The specification makes no use of modules. The checkpoints in this section are not applicable (N/A)

5.1 If modules are chosen, indicate any mandatory conditions or constraints on their usage. [Priority 1]

N/A

5.2 If modules are chosen, define their relationships and interaction with other dimensions of variability. [Priority 2]

N/A

Guideline 6. Address the use of functional levels to divide the technology.

The specification makes no use of functional levels. The checkpoints in this section are not applicable (N/A)

6.1 If levels are used, define their relationships and interaction with other dimensions of variability. [Priority 2]

N/A

Guideline 7. Identify the relation between deprecated features and conformance.

7.1 Identify each deprecated feature. [Priority 1]

Yes. Seems to apply only to Context and not Presentation (?) - if so, this could be made explict and explained.

7.2 For each class of product, specify the degree of support required for each deprecated feature and the conformance consequences of the deprecation. [Priority 1]

Yes. See section 7.2.1.2.

7.3 If deprecation is used, define its relationships and interaction with other dimensions of variability. [Priority 2]

Yes. Section 7.2.1.2 discusses deprecation wrt input/output/roundtrip product classes.

7.4 Include an explanation for the deprecation. [Priority 3]

Generally yes.

7.5 Include examples to illustrate how to avoid using deprecated features. [Priority 3]

Yes. In cases where reasons are not given an alternative usage is given. (Section 6.4)

Guideline 8. Define discretionary items.

Latitude for implementer discretion is large. Specific constraints are not all identified as this would clearly be exhaustive. This may be a potential interoperability problem (?)

8.1 State the circumstances for when discretionary items are allowed [Priority 1]

Yes. Implementers have discretion in some cases whether to use content or presentation markup. Rules and guidelines for these cases are given. Also see rendering rules (section 3).

8.2 For implementation dependencies, address the allowable differences between implementations [Priority 1]

Yes. Section 7.1

8.3 Indicate any constraints on the number of choices/options that can be implemented for discretionary choices [Priority 2]

Not really. Latitude for discretion is large.

8.4 Promote consistent handling of discretionary choices. [Priority 2]

Yes. Implementation notes cover this.

8.5 If discretionary items are used, define their relationships and interaction with other dimensions of variability. [Priority 2]

Yes. The relation between product classes and content/presentation discretion is discussed. Section 7.2 covers a product/extension relationship.

Guideline 9. Allow extensions or NOT!

The treatment of extensions is where the spec. performs least well against the SpecGL checkpoints. Future extensions are discussed in the context of future work to be added to the spec. In the context of an implementer extending the current spec. one mechanism is provided for Presentation extensions (mglyph) via Unicode but the conformance implications are not discussed. Interoperability implications are covered in a paragraph dissuading extensions unless absolutely necessary.

9.1 Indicate if the specification is extensible. [Priority 1]

Yes. Future extensions are discussed in section 7.3.

9.2 If extensions are allowed, define their scope and constraints. [Priority 1]

Yes. Section 3.2.9 covers Presentation extensions.

9.3 Prevent extensions from contradicting the specification. [Priority 1]

No. It is not made clear if extensions may contradict other parts of the spec.

9.4 Define a uniform mechanism to create an extension [Priority 3]

Yes. In the case of presentation mglyphs (section 3.2.9)

9.5 Require that extensions be published. [Priority 3]

No.

9.6 Require that implementations provide interoperable alternatives to extensions [Priority 3]

No.

9.7 If extensions are allowed, define their relationships and interaction with other dimensions of variability [Priority 2]

No.

Guideline 10. Provide a conformance clause.

10.1 Include a conformance section. [Priority 1]

Yes. Section 7.2.1.

10.2 Make normative reference to specifications on which the current specification depends [Priority 2]

Yes. (I think..) MathML is only dependent on versions of XML and Unicode.

Guideline 11. Specify how to make conformance claims.

Conformance claims are handled not through a statement provided in the spec. but by use of the official test suite. The results of a test run appear to constitute a claim.

11.1 Identify and define all conformance designations. [Priority 1]

Yes. identifies one general type and three sub-types (section 7.2.1).

11.2 Provide specific wording of the claim. [Priority 3]

Yes. The MathML test suite results are treated as the conformance claim (section 7.2.1.1)

11.3 Provide a conformance disclaimer. [Priority 3]

Yes. Implementers are encouraged to itemize parts of the spec. that are not meaningful to their product/implementation.

11.4 Impose no restrictions about who can make a claim or where claims can be published. [Priority 1]

Yes. No obvious restrictions.

Guideline 12. Publish an Implementation Conformance Statement proforma.

Publication is encouraged, not demanded. There is no common public repository for IC Statements

12.1 Provide an Implementation Conformance Statement proforma. [Priority 3]

Yes. (No ICS) Implementers are given wide latitude, particularly in presentation. They are encouraged to publish there own ICS (test suite results).

12.2 Require the ICS be completed as part of the conformance claim. [Priority 3]

Not Applicable

Guideline 13. Clearly identify conformance requirements.

In addition to a conformance section in the spec. the MathML group maintain a separate document "MathML 2.0 Compliance Guidelines". This document duplicates material in the spec. conformance section (section 7). This may lead to document synchronization errors.

13.1 Use conformance key words. [Priority 1]

No. Text is mainly descriptive rather than prescriptive. There is little use of 'must', some use of 'should' and 'may'. RFC2119 is not referenced. It is not clear if 'should' etc are used according to RFC 2119 rules.

13.2 Distinguish normative and informative text. [Priority 1]

Yes. Text is treated as normative unless explicitly marked.

13.3 Use consistent terminology. [Priority 1]

Yes.

13.4 Provide a fast way to find conformance information [Priority 2]

Yes. All in a single section, linked from table of contents (PDF bookmarks list in the version I read)

Guideline 14. Provide test assertions.

The specification does not identify assertions or provide any requirement-test linkage mechanism.

14.1 Provide test assertions [Priority 2]

No. There is a test suite but there is no direct linkage to assertions in the spec.

14.2 Provide a mapping between the specification and the test assertions list [Priority 2]

No. Text that contains a requirement that could be treated as an assertion is not labelled or identified as such and so it would not be possible to provide a linking mechanism.

Back matter

Generally the specification conforms well to SpecGL.

The main weakness is lack of information about the conformace implications of extensions to the spec. The possibility of extensions is readily acknowledged and in the main case a mechanism is provided but it is noted that there are interoperability issues here which are not dealt with other than to dissuade an implementer from using the extension mechanism where possible.

The spec. does not use strong, prescriptive RFC2119 language and this makes it harder to locate assertions (but easier to read...). Specific requirements are not tagged (to allow linkage to tests) although there is a test suite (which I haven't looked at)

I was a little confused about product classification. There is more than one classification scheme for the same set of applicable products. Conformance product classes and discretionary implementation classes use different terms.

There is a separate document for "Compliance Guidelines". This document appears to duplicate material in the conformance section of the specification which raises document maintenance concerns. Also both 'compliance' and 'conformance' are used (to mean the same thing).