Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

[Stefan Monnier]

> +into the current buffer before point.  The text inserted is the region
> +between @var{start} (inclusive) and @var{end} (exclusive).  (These

That is misleading: buffer positions are *between* characters (or
alternatively, characters are placed *between* buffer positions).
Talking about "inclusive" and "exclusive" here makes it sound like
buffer positions are placed *on* characters.


        Stefan

Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 15 Aug 2013 23:53:49 -0400
> Cc: emacs-devel@gnu.org
> 
> > +into the current buffer before point.  The text inserted is the region
> > +between @var{start} (inclusive) and @var{end} (exclusive).  (These
> 
> That is misleading: buffer positions are *between* characters (or
> alternatively, characters are placed *between* buffer positions).
> Talking about "inclusive" and "exclusive" here makes it sound like
> buffer positions are placed *on* characters.

Are you saying that characters don't have positions?  We say
"character at POSITION", and we mean that.  What is misleading here?

Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

[Stefan Monnier]

> Are you saying that characters don't have positions?

Obviously not.

> We say "character at POSITION", and we mean that.

We do say that at times, but note that the functions we provide have
names like `char-after' and `char-before'.  The naming was sometimes
poorly chosen (e.g. `text-properties-at'), so we're not completely
consistent here.

> What is misleading here?

That saying explicitly "inclusive" and "exclusive" means that using "at"
is not just an abuse of language but is really how things should
be understood.

If we want to be more explicit, then rather than using "inclusive" and
"exclusive", I'd rather we add a blurb like "Remember that positions are
/between/ characters, so the char right \"at\" END will not be included".


        Stefan

Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: xfq.free@gmail.com, emacs-devel@gnu.org
> Date: Fri, 16 Aug 2013 12:20:02 -0400
> 
> If we want to be more explicit, then rather than using "inclusive" and
> "exclusive", I'd rather we add a blurb like "Remember that positions are
> /between/ characters, so the char right \"at\" END will not be included".

What's the difference?  Both say that character at END will be
excluded.

Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

[Xue Fuqiao]

This rule applies to all functions that use the region.  More generally,
it applies all functions that use BEG and END if they are buffer positions.

Since there are too many functions, IMO a better approach is remove them
("inclusive" and "exclusive") from their own documentation and add a
blurb like Stefan said in a node like (info "(elisp) The Region").

Re: [Emacs-diffs] trunk r113909: Refine the documentation of `insert-buffer-substring'.

[Eli Zaretskii]

> Date: Sun, 18 Aug 2013 06:27:25 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel <emacs-devel@gnu.org>
> 
> This rule applies to all functions that use the region.  More generally,
> it applies all functions that use BEG and END if they are buffer positions.
> 
> Since there are too many functions, IMO a better approach is remove them
> ("inclusive" and "exclusive") from their own documentation and add a
> blurb like Stefan said in a node like (info "(elisp) The Region").

Like I said, I don't see anything wrong with "inclusive" and
"exclusive".  But if you want a good place to add such a blurb, do
that in the preamble in the node "Text", which already tries to say
something along these lines.  By contrast, "The Region" is only about
the region between mark and point, which is not entirely relevant to
the functions that accept BEG and END as arguments, because these
arguments don't have to come from the region limits.

Btw, this rule applies to string positions as well, I think.