Docstring of `decode-coding-string' a bit misleading about insertion in buffer

Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Juanma Barranquero]

(with-temp-buffer
  (insert "line 1\n")
  (decode-coding-string "line 2\n" 'cp1252 nil (current-buffer))
  (insert "line 3\n")
  (buffer-string))

 => "line 1\nline 3\nline 2\n"

That's not a bug, I think, because decode-coding-string's docstring
says nothing about the point:

 Optional fourth arg buffer non-nil means that the decoded text is
 inserted in buffer instead of returned as a string.  In this case,
 the return value is the length of the decoded text.

And I can see how decode-coding-string parallels decode-coding-region,
where the decoded text replaces the original text without moving the
point.

However, the use of "inserted" in the docstring is a bit misleading,
as `insert' does move the point. I know that "inserted" here does not
mean that `insert' is used, but still it led me astray for a while.

  Juanma

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Kenichi Handa]

In article <f7ccd24b0810170719k3d743191na6c059938cf59c2@mail.gmail.com>, "Juanma Barranquero" <lekktu@gmail.com> writes:

> That's not a bug, I think, because decode-coding-string's docstring
> says nothing about the point:

>  Optional fourth arg buffer non-nil means that the decoded text is
>  inserted in buffer instead of returned as a string.  In this case,
>  the return value is the length of the decoded text.

> And I can see how decode-coding-string parallels decode-coding-region,
> where the decoded text replaces the original text without moving the
> point.

> However, the use of "inserted" in the docstring is a bit misleading,
> as `insert' does move the point. I know that "inserted" here does not
> mean that `insert' is used, but still it led me astray for a while.

How about adding "(after point and markers)" after "inserted
in buffer"?

---
Kenichi Handa
handa@ni.aist.go.jp

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Juanma Barranquero]

On Mon, Oct 20, 2008 at 09:04, Kenichi Handa <handa@m17n.org> wrote:

> How about adding "(after point and markers)" after "inserted
> in buffer"?

Is not that it inserts after point what is newsworthy, but that it
does not move the point, IMHO.

   Juanma

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Kenichi Handa]

In article <f7ccd24b0810200018ja17b125h273d318d641d50ac@mail.gmail.com>, "Juanma Barranquero" <lekktu@gmail.com> writes:

> On Mon, Oct 20, 2008 at 09:04, Kenichi Handa <handa@m17n.org> wrote:
> > How about adding "(after point and markers)" after "inserted
> > in buffer"?

> Is not that it inserts after point what is newsworthy, but that it
> does not move the point, IMHO.

Sorry, I can't parse the above sentence.  Anyway, if we
write "inserted in buffer (after point and markers)", I
think it means the text is inserted without moving point and
markers.

---
Kenichi Handa
handa@ni.aist.go.jp

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Juanma Barranquero]

On Mon, Oct 20, 2008 at 10:12, Kenichi Handa <handa@m17n.org> wrote:

> Anyway, if we
> write "inserted in buffer (after point and markers)", I
> think it means the text is inserted without moving point and
> markers.

I'm sure it means that. I think I would still have missed it, because
I misread the "inserted" as related to `insert', which moves the
point.

I would just add "The point does not move." or somesuch. But I'm not
good writing docs.

  Juanma

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Kenichi Handa]

In article <f7ccd24b0810200121g7491defcx5b549c7e96d38bf0@mail.gmail.com>, "Juanma Barranquero" <lekktu@gmail.com> writes:

> On Mon, Oct 20, 2008 at 10:12, Kenichi Handa <handa@m17n.org> wrote:
> > Anyway, if we
> > write "inserted in buffer (after point and markers)", I
> > think it means the text is inserted without moving point and
> > markers.

> I'm sure it means that. I think I would still have missed it, because
> I misread the "inserted" as related to `insert', which moves the
> point.

> I would just add "The point does not move." or somesuch. But I'm not
> good writing docs.

Me neither.  Could someone please improve these docstrings?
  encode-coding-region
  decode-coding-region
  encode-coding-string
  decode-coding-string

---
Kenichi Handa
handa@ni.aist.go.jp

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Eli Zaretskii]

> From: Kenichi Handa <handa@m17n.org>
> Date: Mon, 20 Oct 2008 19:43:12 +0900
> Cc: emacs-devel@gnu.org
> 
> > I'm sure it means that. I think I would still have missed it, because
> > I misread the "inserted" as related to `insert', which moves the
> > point.
> 
> > I would just add "The point does not move." or somesuch. But I'm not
> > good writing docs.
> 
> Me neither.  Could someone please improve these docstrings?
>   encode-coding-region
>   decode-coding-region
>   encode-coding-string
>   decode-coding-string

Done.

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Juanma Barranquero]

On Tue, Oct 21, 2008 at 17:57, Eli Zaretskii <eliz@gnu.org> wrote:

> Done.

Thanks.

    Juanma

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Kenichi Handa]

In article <uvdvmeya4.fsf@gnu.org>, Eli Zaretskii <eliz@gnu.org> writes:

> > Me neither.  Could someone please improve these docstrings?
> >   encode-coding-region
> >   decode-coding-region
> >   encode-coding-string
> >   decode-coding-string

> Done.

Thank you!

---
Kenichi Handa
handa@ni.aist.go.jp

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Richard M. Stallman]

    I would just add "The point does not move." or somesuch.

In Emacs tradition, we treat "point" as a proper name
when it refers to the current editing location.
It should not have an article.

Thus, it is incorrect to write, "The point does not move".
It should be, "Point does not move".

However, that text uses a passive verb, which is also not good.
Documentation is clearer if it avoids the passive voice whenever
possible.  So really this should say, "This does not move point."

If you see "the point" anywhere in Emacs documentation or comments,
referring to point, please fix it.

If you come across passive verbs in Emacs documentation or comments,
please see if it is possible to make the text shorter and clearer
using the active voice.  Usually that does make an improvement.  The
explicit subject required by the active voice often provides important
information which makes the text clearer, too.

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Kenichi Handa]

In article <E1KryAu-00029g-VE@fencepost.gnu.org>, "Richard M. Stallman" <rms@gnu.org> writes:

>     I would just add "The point does not move." or somesuch.
> In Emacs tradition, we treat "point" as a proper name
> when it refers to the current editing location.

Then, how do we refer to the position in a different buffer
that will become "point" when we switch to that buffer?

---
Kenichi Handa
handa@ni.aist.go.jp

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Richard M. Stallman]

    Then, how do we refer to the position in a different buffer
    that will become "point" when we switch to that buffer?

"Point in buffer FOO" or "buffer FOO's value of point".

Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer

[Richard M. Stallman]

    > Anyway, if we
    > write "inserted in buffer (after point and markers)", I
    > think it means the text is inserted without moving point and
    > markers.

    I'm sure it means that. I think I would still have missed it, because
    I misread the "inserted" as related to `insert', which moves the
    point.

Traditionally, to "insert something after point" does mean that point
remains before it.  But not all users know this, so it is prone to
misunderstandings.  I agree it is better to use text that is more
explicit and less terse.