May24 TAML PDF review

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

As promised, I did an editorial review of the complete TAML specification section 2.  Here are my notes.

On p.6, 2.1, second paragraph, strike ", with exceptions as follows"  That is not a table of exceptions to the statement in this paragraph. 

On p.6 immediately under the table, there is no definition of "lower camel case."

On p.6, last paragraph of section 2.1, "and are not valid as top level elements in a markup instance." is better stated as "in a markup instance under the TAML schema."

On p.6, first paragraph of 2.2, the first paragraph could have the "representing" replaced by "understood to be bound to".

On p.6, second paragraph of 2.2 is not meaningful as a normative statement.  It should probably be removed.  There is no reason to tell people what prefix they should use.  It is the binding to the namespace that matters.  The prefix could be Chinese.

On p.7, the paragraph "In many cases ... This is because" doesn't work, unless there are explicit places where "implicitly represented" is to be resolved.  Is this related to Test Assertion Tests and the inheritance of global settings?  Also, this is a bit more than a markup convention.

On p.7 in the last paragraph in front of section 2.3 in the PDF, there is "The XPath notation []" with nothing in the brackets.   There is a link to the [XPATH2] entry though.

On p.7, section 2.3.1, Starting in the first paragraph there are too many brackets around [TAM].  It looks like there are brackets in the text and brackets in the reference.  This problem continues through the remainder of the specification, at least in the PDF.

On p.7, section 2.3.1, under the Compact Relax NG definition, "If no provision is made for an implicit identifier to be assigned" is not meaningful.  How is one to know there is such a provision and when it is in effect.  Also, how does a TA Reference work in that case?

Note: The Compact Relax NG is such that an empty <taml:testAssertion /> element is completely valid.  I find that very strange.

On p.7, section 2.3.1 in the last paragraph of the page, "lg" described as an extension to the Test Assertions Model.  I think this is a problem.  "is an addition for TAML purposes."  Or just say that "The testAssertion element has an optional language attribute, lg, which has specific correspondence in the Test Assertions Model."  

I also notice that we are not consistent here with the use of font and quotes on element names, attribute names, etc.

I would restate the part of the last paragraph beginning "Declaring the language ..." as follows:

"If the 'lg' attribute is provided for a 'testAssertion' element, that attribute value *shall* be used as the default value of the 'lg' attribute for any descendant element of the 'testAssertion' element for which an optionally-allowed 'lg' attribute is not provided."  I don't know if this 'lg' attribute value can also be determined by default, but if it can we need to provide for that too.  Also, there may need to be a way to avoid a default.  Perhaps 'lg'="" would do it?

I would delete the sentence about profiles, since profiles are not the subject of the TAML specification and we have no way to make normative statements about them.

p.8 first paragraph.  The "extension to the Test Assertion Model" phrase appears again.  Suggestion: "The optional 'name' attribute provides for attaching informal, human-specifiable and -readable names to 'testAssertion' elements.  There is no condition on how these attribute values are assigned other than the requirement that they should be human-understandable text."

p.8 second paragraph.  I don't understand from this how I would provide a 'schemaVersionId" if I mean the schema version specified in this version of the TAML specification.  "version methodology" seems to be an undefined concept, and if it is a defined concept it needs to be elevated somewhere in this specification.

p.8 paragraphs 3-4 talk about implicit representation again.  In particular, "inferred from context" 

p.8 paragraph 5 is even more assertive about extending the model.  Suggestion" strike "but is specified here as an extension to the model".

p.8 paragraph 6 is probably something that should be in  section 2.2.  It should be sharpened to indicate that attributes introduced as extensions for a TAML-specified element shall have a namespace and that shall not be the TAML namespace.

p.8 Example - there should be a non-normative reference to the NIEM specification where it is mentioned in the first sentence.  Also, after the example, those elements for which there is a default 'lg' should be identified, perhaps in a sentence following the example.  I think, for this example, it is the <taml:target>, <taml:predicate>, and <taml:report> elements.  I'd like to see the schemaVersion attribute in this example also.

p.10 top of page, this is talking about the <derivedSourceItem> element but there is no accompanying Compact Relax NG definition as a lead-in.   There seems to be somethiing out of order here, in comparison to how all of the other notions have a preceding Compact Relax NG definition that is further explained with subsequent  prose.

p.10 Definition of <taml:comment>.  This Relax NG does not exclude TAML-defined elements as children of the comment.

p.10 Definition of <taml:interpretation>.  The phrase "(or as further specified in a conformance profile for this markup or a customization thereof)" refers to concepts not established here.   Suggestion: Remove that parenthetical phrase.  It is difficult to know how this is different than a comment, but I can overlook this bit of over-engineering.

p.11 top of page.  I just don't understand this.  Maybe how this applies to the example test assertion could be explained there.

p.12 2.3.6 second paragraph below the Relax NG" It seems that Custom enumerations *shall* be prefixed with a namespace prefix ... .  Otherwise the *shall not* makes no sense (maybe it doesn't anyhow), and we certainly don't want people to add unprefixed values to the attribute.

p.13 2.3.10 taml:report.  The schema allows taml elements as children of <taml:report>.

p.13 2.3.10 bottom of page.  The last paragraph does not mean that.  HTML is not XML.  XHTML yes, HTML no.

p.14 top.  After all of the work to avoid using judgmental terms pass and fail in the model, here they are instead of 'fulfilled' and 'notfulfilled'.  Funny.

p.14 second paragraph (first below the bulleted list).  Again, this makes a provision about something that is not the subject of this specification.  It would seem more appropriate to allow the QName provision for extensions to the values of 'label'.

p.14, third paragraph (second below the bulleted list).  Suggestion: Remove the text starting "This attribute is also useful when ..." and including the bulleted list.  If it is important to say what the additional conditions are by default, perhaps include that in the first bulleted list where the three attribute values are defined.

p.14, last paragraph of 2.3.10, delete "A more detailed report or diagnostic message may ... in a conformance profile."  The last sentence, "The taml:report element allows mixed content" should be in a separate paragraph.

pp.16-17.  Why is this not defined the same way as other TAML elements?

  ** end of notes **