Subject: [EAI] Consensus Issue #3: remove repetition of normative text?

From: Joseph Yee <[email-masked]>
Date: Mon, 17 Jan 2011 12:15:43 -0500

Issue #3: remove repetition of normative text?

http://trac.tools.ietf.org/wg/eai/trac/ticket/3

Description 
---------------

Should the WG remove repetition of normative text from other documents to the extent possible. Incorporate by reference and, where necessary, note explicitly that tutorial / context-providing references are not normative.

---------------

Please use this thread or the issue tracker for discussion. The end date of discussion is Tuesday, Jan 25 - 9pm Pacific Time and conclusion will be drawn afterwards.    

Best,
Joseph

---

From: "Charles Lindsey" <[email-masked]>
Date: Thu, 20 Jan 2011 12:27:49 -0000

> Should the WG remove repetition of normative text from other documents  
> to the extent possible. Incorporate by reference and, where necessary,  
> note explicitly that tutorial / context-providing references are not  
> normative.

Yes.

But please replace removed syntax by NOTEs of the form
    "<xxx> is defined in [RFCyyy] to be of the form:
       <helpful example or brief syntax summary>"
so that readers can follow the intent of the documents without excessive  
switching between RFCs.

-- 
Charles H. Lindsey ---------At Home, doing my own thing------------------------
Tel: +44 161 436 6131                       
   Web: http://www.cs.man.ac.uk/~chl
Email: [email-masked]      Snail: 5 Clerewood Ave, CHEADLE, SK8 3JU, U.K.
PGP: 2C15F1A9      Fingerprint: 73 6D C2 51 93 A0 01 E7 65 E8 64 7E 14 A4 AB A5

---

From: Claudio Allocchio <[email-masked]>
Date: Fri, 21 Jan 2011 11:39:38 +0100 (CET)

>> Should the WG remove repetition of normative text from other documents to 
>> the extent possible. Incorporate by reference and, where necessary, note 
>> explicitly that tutorial / context-providing references are not normative.
>

YES!

> so that readers can follow the intent of the documents without excessive 

As I said in my review, repetitions, AND summaries can be very dangerous, 
non only when the original specification gets an update, but because they 
can give the reader/implementor the false sense of complete understanding 
of the environment (and e-mail IS complex). I'm inclided to say yes to 
helpful examples, and no to brief syntax summaries.

------------------------------------------------------------------------------
Claudio Allocchio             G   A   R   R          [email-masked]
                         Senior Technical Officer
tel: +39 040 3758523      Italian Academic and       G=Claudio; S=Allocchio;
fax: +39 040 3758565        Research Network         P=garr; A=garr; C=it;

            PGP Key: http://www.cert.garr.it/PGP/keys.php3#ca

---

From: John C Klensin <[email-masked]>
Date: Sat, 22 Jan 2011 06:16:31 -0500

--On Monday, January 17, 2011 12:15 -0500 Joseph Yee
<[email-masked]> wrote:

> Should the WG remove repetition of normative text from other
> documents to the extent possible. Incorporate by reference
> and, where necessary, note explicitly that tutorial /
> context-providing references are not normative.
>...

Yes, sort of.

This solution is much more acceptable to me if a note along the
lines that Charles suggests is added, but such notes need to
distinguish carefully between "version in RFC as specified" and
"version in RFC or its successor".

   john