[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Scheme-reports] Three really picky points

On 2012-01-10, at 19:40, Alex Shinn wrote, responding to me:

(re exact results)
I think the formal meaning of "should" used in the draft already
implies "attempt to".
That's not my understanding of the definition of `should' from RFC 2119;
the text reads 
   SHOULD   This word, or the adjective "RECOMMENDED", mean that there
   may exist valid reasons in particular circumstances to ignore a
   particular item, but the full implications must be understood and
   carefully weighed before choosing a different course.

This sounds like a design decision (and that's the way I've always interpreted 
`should'), rather than a specification of how a procedure should behave. I 
know I'm being picky, but the original paragraph sounded wrong to me when I 
read it carefully this morning, and I only picked on `should' after the fact. 
It feels contradictory, even though I admit it isn't. I don't mind if my 
suggestion isn't adopted, I just think the paragraph should be reworded. 

(re inexact->exact and exact->inexact)

I removed this because we don't, in general, discuss the
historical reasons for names so it seemed out of place.
The notes were not updated, but will be before the final
draft (unless someone proposes we uniformly explain all
non-obvious names).

That's fine, but it's still a fact that the names of these procedures 
are misleading. There's a distinction between a name like cdr, which is
meaningless to those who don't know and love the IBM 709 computer, and 
inexact->exact, which might actively confuse the reader. I agree that 
the procedures are correctly described in the entry, but the names are 
at such variance from the description that the reader is justified in 
wondering if it's the description that's wrong rather than the names. 

Some text such as `Note: These procedures accept as an argument any 
kind of number, despite their names.' would help clarify that. That 
sounds kind of clunky (and somewhat duplicates the description), so 
my preferred wording is `Note: The names of these procedures are 
historical if not completely descriptive.', I don't think any 
further explanation need be provided.

-- vincent

Scheme-reports mailing list