Word usage

Word usage

[David Kastrup]

In color.el, the doc strings frequently say something like

"must be between [0,1]."

That is bad English.  Either you write "must be between 0 and 1
inclusively." (which is less techno-babble), or you write "must be in
[0,1]".  But a value can't be "between" an interval.  That is
nonsensical.

-- 
David Kastrup

RE: Word usage

[Drew Adams]

> In color.el, the doc strings frequently say something like
> "must be between [0,1]."
> 
> That is bad English.  Either you write "must be between 0 and 1
> inclusively." (which is less techno-babble), or you write "must be in
> [0,1]".  But a value can't be "between" an interval.  That is
> nonsensical.

And Emacs doc should definitely use the former, not the latter.  We should not
suppose that Emacs users are familiar with math notation beyond the most basic
(e.g. arithmetic or algebra).  There is no reason to expect general users to be
familiar with interval notation.

Another clear alternative for such a statement is "N, where 0 <= N <= 1".
Another is "N, where (and (<= 0 N) (<= N 1))", which speaks Emacs Lisp.

Re: Word usage

[Stefan Monnier]

> And Emacs doc should definitely use the former, not the latter.
> We should not suppose that Emacs users are familiar with math notation
> beyond the most basic (e.g. arithmetic or algebra).  There is no
> reason to expect general users to be familiar with interval notation.

color.el is clearly not intended for general users, so the [0,1]
notation seems adequate for that context.


        Stefan

RE: Word usage

[Drew Adams]

> > And Emacs doc should definitely use the former, not the latter.
> > We should not suppose that Emacs users are familiar with 
> > math notation beyond the most basic (e.g. arithmetic or algebra).
> > There is no reason to expect general users to be familiar with
> > interval notation.
> 
> color.el is clearly not intended for general users,

Of course it is.  Who is it excluding?

> so the [0,1] notation seems adequate for that context.

Not.  It is entirely possible to follow the code and comments of color.el
without necessarily being familiar with math interval notation - or at least it
should be.  (I assert that having still never seen the color.el code. ;-))

"Adequate"?  There is no reason to use (non-Emacs) jargon when English is just
as clear and is sufficiently concise.

Both "must be between 0 and 1 inclusively" (suggested by David) and "N, where 0
<= N <= 1" (which I suggested) are pretty clear to everyone, and they are not
particularly verbose.

They are _no more verbose_ than "must be in the interval [0, 1]".  You gain
nothing by using the latter, and you can lose clarity for some readers.  It is
perverse to opt for possible confusion with no gain.  (Are we showing off?)

Unless you are using interval descriptions over and over, and especially a mix
of interval types, there is no reason to use interval syntax here (especially
without explicitly introducing it).

http://en.wikipedia.org/wiki/Occam's_razor
http://en.wikipedia.org/wiki/KISS_principle

Re: Word usage

[Ted Zlatanov]

On Sun, 28 Nov 2010 11:15:47 -0800 "Drew Adams" <drew.adams@oracle.com> wrote: 

>> > And Emacs doc should definitely use the former, not the latter.
>> > We should not suppose that Emacs users are familiar with 
>> > math notation beyond the most basic (e.g. arithmetic or algebra).
>> > There is no reason to expect general users to be familiar with
>> > interval notation.
>> 
>> color.el is clearly not intended for general users,

DA> Of course it is.  Who is it excluding?
...
DA> It is entirely possible to follow the code and comments of color.el
DA> without necessarily being familiar with math interval notation - or
DA> at least it should be.  (I assert that having still never seen the
DA> color.el code. ;-))

Seriously?  I would have a lot of trouble writing these statements
together in the same page, never mind paragraph.

I suggest you look at the color.el source code.  If you can't handle
math notation, you have no hope of understanding it.

DA> http://en.wikipedia.org/wiki/Occam's_razor
DA> http://en.wikipedia.org/wiki/KISS_principle

Heh.  Why don't you cite the Pareto principle to make the trifecta?  It
applies as much as the other ones...

Ted

RE: Word usage

[Drew Adams]

> look at the color.el source code.  If you can't handle
> math notation, you have no hope of understanding it.

Then add a comment line (at most two) to the file explaining interval syntax for
anyone who is not familiar with the notation.  Understanding algorithms (the
real math) is not the same as being familiar a with particular notation.

In particular, there are (unfortunately) lots of (smart) programmers who are not
very well versed in math.  That does not mean that they cannot understand, given
an explanation of the (in this case trivial) syntax.

Re: Word usage

[Ted Zlatanov]

On Fri, 10 Dec 2010 12:24:19 -0800 "Drew Adams" <drew.adams@oracle.com> wrote: 

DA> In particular, there are (unfortunately) lots of (smart) programmers who are not
DA> very well versed in math.  That does not mean that they cannot understand, given
DA> an explanation of the (in this case trivial) syntax.

You're defending a class of people that doesn't exist: smart programmers
who are bad at math and somehow missed out on interval notation, and who
now are attempting to use color.el.  There may be one in the world, I
guess...

But I will point out that the same arguments can be made in mirror form
against using an English description of the interval because smart
programmers may be bad at English.  In fact that's a more likely
scenario.

Ted

RE: Word usage

[Drew Adams]

> You're defending a class of people that doesn't exist: smart 
> programmers who are bad at math and somehow missed out on
> interval notation, and who now are attempting to use color.el.
> There may be one in the world, I guess...

Such arrogance.

Just add a simple comment describing the syntax, please. E.g.:

;; Parens `(', `)' and brackets `[', `]' indicate intervals.
;; A bracket means the start `[' or end `]' point is included.
;; A paren means it is not included. (Standard interval notation.)

Is that so hard?

Re: Word usage

[Ted Zlatanov]

On Fri, 10 Dec 2010 13:40:01 -0800 "Drew Adams" <drew.adams@oracle.com> wrote: 

DA> Just add a simple comment describing the syntax, please. E.g.:

DA> ;; Parens `(', `)' and brackets `[', `]' indicate intervals.
DA> ;; A bracket means the start `[' or end `]' point is included.
DA> ;; A paren means it is not included. (Standard interval notation.)

DA> Is that so hard?

I think it's condescending, personally.  But I'm arrogant like that.

Ted

Re: Word usage

[Julien Danjou]

[-- Attachment #1: Type: text/plain, Size: 474 bytes --]

On Sun, Nov 28 2010, David Kastrup wrote:

> In color.el, the doc strings frequently say something like
>
> "must be between [0,1]."
>
> That is bad English.  Either you write "must be between 0 and 1
> inclusively." (which is less techno-babble), or you write "must be in
> [0,1]".  But a value can't be "between" an interval.  That is
> nonsensical.

Fair enough. I've fixed that.

-- 
Julien Danjou
// ᐰ <julien@danjou.info>   http://julien.danjou.info

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]