Re: [SpecGL Draft] A.1 GP In the conformance clause, define how normative language is expressed.

Le jeu 05/08/2004 à 21:04, Karl Dubost a écrit :
> Good Practice:
> 	In the conformance clause, define how normative language is expressed.

I haven't looked into the details, but as I mentioned before, this needs
to be coordinated closely with C2, GP1:
http://lists.w3.org/Archives/Public/www-qa-wg/2004Aug/0002.html

> What does it mean?
> 	There are a number of common language styles for expressing the 
> detailed conformance requirements of a specification. One of the most 
> popular is RFC 2119 [RFC 2119] -- keywords like must, may, and should 
> not both signal the presence of conformance requirements and express 
> their relative mandatory nature. Other styles include imperative voice 
> statements (as in the statement of the Good Practice item), physical 
> segregation via styling, labelling,

s/labelling/labeling /

I think this part should link to C2 where the different styles are
explained in more details.

>  etc. What matters is that the style 
> be consistent, unambiguous, and (ideally) quickly recognized.
> 
> Why should I Care?
> 	A specification is composed from many mandatory parts. Some 
> requirements with a programmatic nature, for instance DTD and XML 
> Schemas for a markup language, are easy to recognize and so to 
> implement. Most of the time, these strict definitions of a language are 
> not enough and there is a need for an explicit prose to explain the 
> nature of a name token (element, attribute, feature).

s/nature of a name token/semantics attached to the syntax tokens/

>  A clear 
> definition of the normative language helps developers to know the 
> requirements, to create test assertions for test suite developpers,

s/developpers/developers/

>  and 
> to avoid ambiguities when debating the prescriptive nature of the 
> prose.
> 
> Related:
> 	Link to Test assertions.
> 	Link to RFC 2119
> 	See @@section C.3@@.

(C.2 now)

> Techniques:
> 	1. Choose a formalism to express requirements
> 	2. Create a test assertions list

Hmm... Creating a test assertions list simply to "define how normative
language is expressed" (the GP we're under) seems like a real overkill;
I think you should scrap 2, and say in 3 "try and express the
conformance requirements as test assertions; if you can't expres..."

> 	3. If you can't express without ambiguities a test assertion, it means 
> that you need to write again in your chosen formalism or you need to 
> add requirements for your normative language that will cover these 
> cases.
> 	4. Don't use normative language which makes the interpretation vague. 
> (For example, MUST assume)

I think it would be worth explaining a bit more what you mean here; I
think I understand, but I don't think most people not knowing our
background would.

> Example:
> 	Plenty of examples for RFC2119.
> 	I will find examples for other kind of languages. This document and 
> Web Arch for example

I suggest these examples should be added to C2 instead; this GP is
really about putting information in the conformance section rather than
about the information itself.

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