Subject: RE: [Simple] Double specification: text and schema

From: "Drage, Keith (Keith)" <[email-masked]>
Date: Fri, 2 Jul 2004 12:04:51 +0100

This can be carried to extremes that create major problems, and I would support Jonathan to the extent that he has written below, but would not take this as license to add informative and descriptive material without further purpose.

The main purpose of RFCs (of the type we are talking about) is to carry the normative requirements. 

Informative material is to support and explain those normative requirements.

I see little point in a complete informative description of something that is correctly and appropriately defined in a normative fashion elsewhere.

I have no problem with such duplicating informative statements that set the context for a normative requirement, thus, for example:

"All messages contain foo. The sender MUST set the contents of foo to xxxx."

but "All messages contain foo." with no further requirement should not occur.

I believe that this is much as Miguel originally proposed.

Additionally I have no problem with the reiteration of the normal rules regarding treatment of the MUST, SHOULD etc words when they appear, and there should definitely be a MUST associated with any XML or BNF specification. But I disagree with Joel's proposal to insert sentences that state when an RFC is in conflict with itself one clause has priority over another. Previous experience leads me to the conclusion that where such statements appear, when the standards organisation actually gets round to fixing the specification, the solution follows the lower priority documentation. Internal conflicts in specifications should always be treated as an error in the specification and appropriately fixed.

regards

Keith

> -----Original Message-----
> From: Jonathan Rosenberg [mailto:[email-masked]]
> Sent: 02 July 2004 11:23
> To: Miguel Garcia
> Cc: Joel M. Halpern; SIMPLE mailing list
> Subject: Re: [Simple] Double specification: text and schema
> 
> 
> 
> 
> Miguel Garcia wrote:
> 
> > Hi Joel:
> > 
> > I don't agree with you. We can't avoid the XML schema. I 
> believe you 
> > agree with me.
> > 
> > Since the XML schema already needs to indicate whether an 
> element or 
> > attribute is mandatory or not, there is no point in 
> repeating the same 
> > information in the text. What for?
> 
> I think that it can be useful for purposes of clarification. I would 
> advise using non-normative terminology in the text. So, for example:
> 
> "The <foo> element includes a single mandatory attribute, "bar", and 
> always has two children, <sip> and <ping>..."
> 
> I think it also makes sense to have an explicit statement about the 
> normative nature of the schema, and that any explanatory text is not 
> normative. I routinely put such statements in "overview of 
> operations" 
> sections, which are not written with RFC2119-strentgh terms.
> 
> -Jonathan R.
> 
> -- 
> Jonathan D. Rosenberg, Ph.D.                600 Lanidex Plaza
> Chief Technology Officer                    Parsippany, NJ 07054-2711
> dynamicsoft
> [email-masked]                     FAX:   (973) 952-5050
> http://www.jdrosen.net                      PHONE: (973) 952-5000
> http://www.dynamicsoft.com
> 
> _______________________________________________
> Simple mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/simple
> 

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple

---

From: "Mary Barnes" <[email-masked]>
Date: Mon, 5 Jul 2004 12:44:10 -0400

Hi Miguel,

The problem is that if there are inconsistencies in the text (whether it's
normative or not) and the XML, you've got a problem.  I agree that a
statement specifying that if there are inconsistencies, the XML schema
overrides the text, thus allowing an implementation to go forward without
having to await resolution of the inconsistency.  

But, I stand by the view that I think having the text be normative actually
will improve the quality of documentation overall as it forces the author(s)
to double check and ensure that text matches the XML, particularly when the
text is in the same document as the XML.  I would agree that there's some
room for flexibility when the text is in another document.  But, that still
requires a precise statement as to whether the text/XML in the other
document would override the referenced document text/XML.  

However, you're still not really solving the basic problem that it's
important to write accurate documentation to ensure that things are clearly
understood. My primary concern is that the end result will be poorer
documentation as the message is that all that matters is the XML.  

Mary

-----Original Message-----
From: Miguel Garcia [mailto:[email-masked]] 
Sent: Monday, July 05, 2004 1:47 AM
To: Barnes, Mary [NGC:B601:EXCH]
Cc: Joel M. Halpern; Jonathan Rosenberg; SIMPLE mailing list
Subject: Re: [Simple] Double specification: text and schema

Hi Mary:

I don't have any problem with having accurate comments on the text. My 
problem is with having normative statements that, at some point in time, 
may differ with the XML schema (which is also normative). I am just 
seeking for a future proof specification that allows interoperability.

I have seen many other SDOs that systematically repeat normative 
statements across the same or different specifications, and you know 
what? They are always divergencies. As I want to avoid this divergence, 
my proposal is to avoid normative statements when the normative part is 
described in the XML schema.

I still think that Jonathan's proposal was excellent: comment the XML 
schema in the text, but avoid normative statements.

- Miguel

Mary Barnes wrote:
> I agree with Joel; I think we're getting back to the fundamental debate 
> on whether one should comment code or whether good code is self 
> documenting (or whether detailed design documents should have 
> pseudo-code or real code, etc.)  It is important to have good and 
> accurate as possible textual descriptions along with the XML. And, I 
> don't see a problem with it being normative, either (in fact that would 
> be my preference). I don't consider myself an XML guru, but I can manage 
> my way through with the appropriate normative text.  That's how it's 
> done for all the other specs; why should the XML based specs be any 
> different?   
> 
> Certainly, there are issues with some of the current documents in the 
> text that could be further clarified to ensure consistency with the XML 
> schema, but I think that's along the lines of the last point you make 
> below about putting a "bit of effort" in writing the documents.   
> 
> Regards,
> Mary.
> 
> From: Miguel Garcia [mailto:[email-masked]]
> Sent: Friday, July 02, 2004 8:16 AM
> To: Joel M. Halpern
> Cc: Jonathan Rosenberg; SIMPLE mailing list
> Well, here is the disagreement. I just want to tell authors: "don't use
> normative text when there is normative definition expressed in the
schema".
> 
> Believe me, and record my words for a future time: if we start doing
> double specification of normative requirements in RFCs, we will face
> interoperability problems.
> 
> If you are not able to put a bit of effort when writing your documents,
> we all will pay in the future.
> 
> - Miguel
> 
> Joel M. Halpern wrote:
> 
>  > Part of what I am trying to avoid is telling authors that they must be
>  > extra careful never to use MUST words about things described in the
>  > schema.  In a typical text description there will be explanatory text,
>  > there will be explanation of requirements that are also in the schema,
>  > and there will be explanation of requirements that are not in the
>  > schema.  (Occasionally one gets lucky and the last category is empty.)
>  > As an author, I really don't want to have to try to change style from
>  > sentence to sentence in a section depending upon whether or not the
>  > particular behavior I am describing also occurs in the schema.
>  > Also, as I reader I would like to see a complete description in the 
> text.
>  >
>  > Yours,
>  > Joel M. Halpern
>  >
>  > At 06:23 AM 7/2/2004 -0400, Jonathan Rosenberg wrote:
>  >
>  >
>  >> Miguel Garcia wrote:
>  >>
>  >>> Hi Joel:
>  >>> I don't agree with you. We can't avoid the XML schema. I believe you
>  >>> agree with me.
>  >>> Since the XML schema already needs to indicate whether an element or
>  >>> attribute is mandatory or not, there is no point in repeating the
>  >>> same information in the text. What for?
>  >>
>  >>
>  >> normative. I routinely put such statements in "overview of operations"
> Miguel A. Garcia           tel:+358-50-4804586
> Nokia Research Center      Helsinki, Finland
> 
> 

-- 
Miguel A. Garcia           tel:+358-50-4804586
Nokia Research Center      Helsinki, Finland

---

From: "Joel M. Halpern" <[email-masked]>
Date: Mon, 05 Jul 2004 14:21:54 -0400

[I agree with Mary, and believe this is just an example of a general
case.]

To use a concrete example, I recently had reason to look at the
iscomposing draft.  The XML for that is very short.  The schema
therefore is actually fairly readable.  Even so, I found the absence
of clear English text describing the required elements of the document
disconcerting.  (All the necessary pieces are there, but it is
harder to understand than it ought to be.)  If the schema were any
more complex, it would be very hard.  If the ForCES Model document
(which relies heavily on XML Schema) were to omit normative language for
all elements covered by the XML Schema, it would read very badly, and be
very hard to understand.

We have been using duplicate specifications for ages.  When we use
ABNF for syntax, we do not leave out normative language about what the
syntax is.  (We do not insist that the English be complete.
But we do have normative English.) We do say that the ABNF is
definitive.  And we consider it a bug if they differ.

When IEEE did the original 802.1d spec, they included well commented code
for all the behaviors.  They also included good, clear, English
descriptions of the required behaviors.

XML is not any different from any of the other formal specification tools
we use, and should not be treated differently.

Yours,

Joel

At 12:44 PM 7/5/2004 -0400, Mary Barnes wrote:

Hi Miguel,

The problem is that if there are inconsistencies in the text (whether it's normative or not) and the XML, you've got a problem.  I agree that a statement specifying that if there are inconsistencies, the XML schema overrides the text, thus allowing an implementation to go forward without having to await resolution of the inconsistency.

But, I stand by the view that I think having the text be normative actually will improve the quality of documentation overall as it forces the author(s) to double check and ensure that text matches the XML, particularly when the text is in the same document as the XML.  I would agree that there's some room for flexibility when the text is in another document.  But, that still requires a precise statement as to whether the text/XML in the other document would override the referenced document text/XML.

However, you're still not really solving the basic problem that it's important to write accurate documentation to ensure that things are clearly understood. My primary concern is that the end result will be poorer documentation as the message is that all that matters is the XML.

Mary

-----Original Message-----

Hi Mary:

- Miguel

> normative text when there is normative definition expressed in the schema".

>  > Part of what I am trying to avoid is telling authors that they must be

>  > extra careful never to use MUST words about things described in the

>  > schema.  In a typical text description there will be explanatory text,

>  > there will be explanation of requirements that are also in the schema,

>  > and there will be explanation of requirements that are not in the

>  > schema.  (Occasionally one gets lucky and the last category is empty.)

>  > As an author, I really don't want to have to try to change style from

>  > sentence to sentence in a section depending upon whether or not the

>  > particular behavior I am describing also occurs in the schema.

>  > Also, as I reader I would like to see a complete description in the

>  >

>  > Yours,

>  > Joel M. Halpern

>  >

>  > At 06:23 AM 7/2/2004 -0400, Jonathan Rosenberg wrote:

>  >

>  >

>  >> Miguel Garcia wrote:

>  >>

>  >>> Hi Joel:

>  >>> I don't agree with you. We can't avoid the XML schema. I believe you

>  >>> agree with me.

>  >>> Since the XML schema already needs to indicate whether an element or

>  >>> attribute is mandatory or not, there is no point in repeating the

>  >>> same information in the text. What for?

>  >>

>  >>

>  >> I think that it can be useful for purposes of clarification. I would

>  >> advise using non-normative terminology in the text. So, for example:

>  >>

>  >> "The <foo> element includes a single mandatory attribute, "bar", and

>  >> always has two children, <sip> and <ping>..."

>  >>

>  >> I think it also makes sense to have an explicit statement about the

>  >> normative nature of the schema, and that any explanatory text is not

>  >> normative. I routinely put such statements in "overview of operations"

>  >> sections, which are not written with RFC2119-strentgh terms.

>  >>

>  >> -Jonathan R.

>  >>

>  >> --

>  >> Jonathan D. Rosenberg, Ph.D.                600 Lanidex Plaza

>  >> Chief Technology Officer                    Parsippany, NJ 07054-2711

>  >> dynamicsoft

>  >> [email-masked]                     FAX:   (973) 952-5050

>  >> http://www.jdrosen.net                      PHONE: (973) 952-5000

>  >> http://www.dynamicsoft.com

>  >>

>  >> _______________________________________________

>  >> Simple mailing list

>  >> [email-masked]

>  >> https://www1.ietf.org/mailman/listinfo/simple

>  >

>  >

--

Simple mailing list

[email-masked]