Re: [css3-namespace] Requirements of the document as framed by RFC 2119

Le 19 sept. 06 à 14:22, fantasai a écrit :
> karl@w3.org wrote:
>> Hi, This is a QA Review comment for "CSS Module: Namespaces"  
>> http://www.w3.org/TR/2006/WD-css3-namespace-20060828/ 2006-08-28  
>> 2nd WD
>> About http://www.w3.org/TR/2006/WD-css3-namespace-20060828/
>> This is the list of requirements as framed by RFC 2119. The  
>> conformance
>> section makes it explicit. It is though said that the full prose  
>> of this
>> specification is normative and then not only the sentences where  
>> the RFC 2119
>> keywords appear. But the specification uses example in the prose  
>> as well,
>> like in the section 3.3 Declaring prefixes.
>> [[[ For example, following [REC-XML-NAMES], in Selectors [SELECT]  
>> the default
>> namespace… ]]]
> >
>> Is it a requirement or an example?
>
> That is an example, obviously, because it says "for example". As  
> the Conformance
> section states, examples are not part of the normative prose.

http://www.w3.org/TR/qaframe-spec/#norm-informative-gp
It is always better and recommended to clearly distinguish what is  
normative and informative.
See below the rationale.

>
>> It will be better to clearly define all requirements, if possible  
>> with RFC
>> 2119 keywords in a more systematic way. Defining the requirements  
>> and then
>> the prose to explain it if needed. It will be easier to create  
>> individual
>> test cases for each requirements.
>
> It is not the habit of the CSS specifications to use RFC 2119  
> keywords for
> every single requirement. Many -- if not most -- of the  
> requirements in CSS2.1
> are expressed as descriptive assertions, as allowed by the QA  
> Framework
> Specification Guidelines.

Yes it is perfectly correct to use prose but then it has to be  
perfectly clear to not mix what are requirements with examples.  
Separate the two, so it is clearly identifiable. For example, it  
could be presented like this

[[[
3.3. Declaring Prefixes

A namespace prefix, once declared, represents the namespace for which  
it was declared and can be used to indicate the namespace of a  
namespace-qualified name.

If in the namespace declaration the namespace prefix is omitted, then  
the namespace so declared is the default namespace. The default  
namespace applies to names that have no explicit namespace prefix.  
Modules that employ namespace prefixes must define in which contexts  
the default namespace applies.

Example: (brown box)
	For example, following [REC-XML-NAMES], in Selectors [SELECT]
	the default namespace applies to type selectors—but it does not
	apply to attribute selectors.

There is no default default namespace: modules that assign  
unqualified names to the default namespace must define how those  
unqualified names are to be interpreted when no default namespace is  
declared.

Namespace prefixes are, like CSS property names, case-insensitive.

If a namespace prefix or default namespace is declared more than once  
only the last declaration shall be used.
]]] -- CSS Module: Namespaces
        http://www.w3.org/TR/2006/WD-css3-namespace-20060828/#prefixes
        Thu, 24 Aug 2006 16:28:06 GMT

The WG has done it for a few example. Be consistent and do not mix  
examples with normative prose. The brown boxes clearly identify what  
is normative.

> For example:
> http://www.w3.org/TR/CSS21/visuren.html#q5
>   # Block-level elements (...) generate a principal block box that  
> contains
>   # either only block boxes or only inline boxes. The principal  
> block box
>   # establishes the containing block for descendant boxes and  
> generated content
>   # and is also the box involved in any positioning scheme.  
> Principal block
>   # boxes participate in a block formatting context.
>
> Rendered into RFC2119 terms, that would be
>   | Block-level elements (...) SHALL generate a principal block box  
> that
>   | contains either only block boxes or only inline boxes. The  
> principal block
>   | box SHALL establish the containing block for descendant boxes  
> and generated
>   | content and SHALL also be the box involved in any positioning  
> scheme.
>   | Principal block boxes SHALL participate in a block formatting  
> context.
>
> I can, with similarly excessive use of the word "SHALL", render all  
> of CSS
> Namespaces into RFC 2119. But I'm not convinced that it is  
> necessary, and it
> certainly makes the spec's language a lot more awkward.
>
> What would you like me to do?


It has been explained above. The given list with RFC2119 terms would  
be useful for Test Cases authors. Not in the specifications but  
certainly worthwhile to create. It will be necessary to define all  
requirements at a point, so the test suite can be written easily.

Each time a feature is proposed for the specification, ask the person/ 
company who proposed to
	- create the test assertion requirements
	- create the test cases which belong to these requirements.

It is perfectly to work like this.
An editor may refuse any additions to the specifications without  
these elements (test assertions, test cases).
It helps the WG to write the specification on a pseudo test-driven  
framework.
It makes it easier when CR is reached.
It makes the life of the editor easier in the end.



-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Wednesday, 27 September 2006 07:15:32 UTC