Subject: WG ACTION: 2 weeks to discuss [LL60] Forward reference style

From: Erik Guttman <[email-masked]>
Date: Wed, 5 May 2004 01:05:44 +0200

Please post discussion of this issue to the mailing list over the 
next two weeks
ending May 18, 2004.  In order to accept this issued, we will need a strong WG
consensus given that this is very late in the process.

Please see http://www.drizzle.org/~aboba/ZEROCONF/issues.html for a list of
current issues and their status.

[LL60]

Description of Issue:		Forward reference style
Submitter Name:                 	Stuart Cheshire
Submitter Email Address:        [email-masked]
Date first submitted:          	 04 May 04
Reference:
Comment Type ['t'ech|'e'dit]:	e
Prio ['S' Must|1 should|2 may]:	1
Section:			1.2
Rationale/Explanation:
Lengthy Description:

[Stuart]

>    When ready to begin probing, the host should then wait for a random
>    time interval selected uniformly in the range PROBE_MIN to PROBE_MAX
>    seconds, and should then send NUM_PROBES probe packets, spaced
>    randomly, PROBE_MIN to PROBE_MAX seconds apart.

PROBE_MIN and PROBE_MAX suddenly appear, without mention. Can we give
their values FIRST, so the reader has a clue what we're talking about.

[Erik]

This is standard practice in all RFCs that include constants.  We could
add text to section 1.2 if you think that this is confusing to
implementors.

Personally I feel this goes without saying and adding it would only be a
matter of (questionable) style.

[Stuart]

I disagee.

What is the harm in helping the reader understand the document better?

How can unexplained forward references be good style?

Requested Change:

Add to section 1.2

   Constants are introduced in all capital letters.  Their values are
   given in Section 9.

---

From: Ralph Droms <[email-masked]>
Date: Tue, 04 May 2004 21:21:15 -0400

While it's not a big deal, the statement "This is standard practice in all
RFCs that include constants" can be disproven by counterexample; RFC 3315
defines all of the symbolic constants in an early section before any of
those constants are referenced in the specification.

I suggest simply moving section 9 so that it appears before any of the
defined symbolic constants are first referenced.

- Ralph

At 01:05 AM 5/5/2004 +0200, Erik Guttman wrote:
>Please post discussion of this issue to the mailing list over the next two 
>weeks

---

From: "Philip Nye" <[email-masked]>
Date: Fri, 7 May 2004 11:56:15 -0000

I have no problem at all with the way parameters are currently dealt with in the document. It is common usage - keep it as it is.

Philip

---

From: "John C. Welch" <[email-masked]>
Date: Fri, 07 May 2004 09:07:20 -0500

> How can unexplained forward references be good style?

I will say that at least in American English, suddenly using undefined terms
will get you fussed at by almost anyone.

Using terms without defining them first is a great way to cause problems.
Since this is an engineering document of sorts, document - specific terms
should be properly defined as to their usage in the document prior to that
usage.

john

-- 
"C++? That is for children. A Klingon Warrior  uses only machine code, keyed
in on the front panel switches in raw binary."