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

Karl Dubost wrote:
> 
> 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.
 >
> > ...
> 
> 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

Ok, I have added to the Conformance section the following text to explain
which parts of the spec are examples and which are notes so that they may be
distinguished from the normative prose (which the Conformance section defines
to be everything else):

  # All of the text of this specification is normative except sections explicitly
  # marked as non-normative, examples, and notes.
  #
+# Examples in this specification are introduced with the words "for example" or
+# are set apart from the normative text with class="example", like this:
+#
+#  +---------------------------------------------------------------+
+#  | [Example I]                                                   |
+#  |   This is an example of an informative example.               |
+#  +---------------------------------------------------------------|
+#
+# Informative notes begin with the word "Note" and are set apart from the
+# normative text with class="note", like this:
+#
+#   > Note, this is an informative note.

While we've had problems with incorrect examples or incorrect normative prose,
the CSSWG has, to my knowledge, never had a problem with readers failing to
distinguish examples from normative prose, so I believe this should be
sufficient. Let me know if this addresses your concern.

>> 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.

I will group this part of your comment as part of
   http://lists.w3.org/Archives/Public/www-style/2006Sep/0019.html
and
   http://lists.w3.org/Archives/Public/www-style/2006Sep/0023.html
if that's ok.

~fantasai

Received on Thursday, 28 September 2006 01:25:11 UTC