* Docstring of `decode-coding-string' a bit misleading about insertion in buffer
@ 2008-10-17 14:19 Juanma Barranquero
2008-10-20 7:04 ` Kenichi Handa
0 siblings, 1 reply; 13+ messages in thread
From: Juanma Barranquero @ 2008-10-17 14:19 UTC (permalink / raw
To: emacs-devel
(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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-17 14:19 Docstring of `decode-coding-string' a bit misleading about insertion in buffer Juanma Barranquero
@ 2008-10-20 7:04 ` Kenichi Handa
2008-10-20 7:18 ` Juanma Barranquero
0 siblings, 1 reply; 13+ messages in thread
From: Kenichi Handa @ 2008-10-20 7:04 UTC (permalink / raw
To: Juanma Barranquero; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 7:04 ` Kenichi Handa
@ 2008-10-20 7:18 ` Juanma Barranquero
2008-10-20 8:12 ` Kenichi Handa
0 siblings, 1 reply; 13+ messages in thread
From: Juanma Barranquero @ 2008-10-20 7:18 UTC (permalink / raw
To: Kenichi Handa; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 7:18 ` Juanma Barranquero
@ 2008-10-20 8:12 ` Kenichi Handa
2008-10-20 8:21 ` Juanma Barranquero
0 siblings, 1 reply; 13+ messages in thread
From: Kenichi Handa @ 2008-10-20 8:12 UTC (permalink / raw
To: Juanma Barranquero; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 8:12 ` Kenichi Handa
@ 2008-10-20 8:21 ` Juanma Barranquero
2008-10-20 10:43 ` Kenichi Handa
` (2 more replies)
0 siblings, 3 replies; 13+ messages in thread
From: Juanma Barranquero @ 2008-10-20 8:21 UTC (permalink / raw
To: Kenichi Handa; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 8:21 ` Juanma Barranquero
@ 2008-10-20 10:43 ` Kenichi Handa
2008-10-21 15:57 ` Eli Zaretskii
2008-10-20 17:04 ` Richard M. Stallman
2008-10-20 17:04 ` Richard M. Stallman
2 siblings, 1 reply; 13+ messages in thread
From: Kenichi Handa @ 2008-10-20 10:43 UTC (permalink / raw
To: Juanma Barranquero; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 10:43 ` Kenichi Handa
@ 2008-10-21 15:57 ` Eli Zaretskii
2008-10-21 22:47 ` Juanma Barranquero
2008-10-22 1:23 ` Kenichi Handa
0 siblings, 2 replies; 13+ messages in thread
From: Eli Zaretskii @ 2008-10-21 15:57 UTC (permalink / raw
To: Kenichi Handa; +Cc: lekktu, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 8:21 ` Juanma Barranquero
2008-10-20 10:43 ` Kenichi Handa
@ 2008-10-20 17:04 ` Richard M. Stallman
2008-10-21 2:53 ` Kenichi Handa
2008-10-20 17:04 ` Richard M. Stallman
2 siblings, 1 reply; 13+ messages in thread
From: Richard M. Stallman @ 2008-10-20 17:04 UTC (permalink / raw
To: Juanma Barranquero; +Cc: emacs-devel, handa
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.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 17:04 ` Richard M. Stallman
@ 2008-10-21 2:53 ` Kenichi Handa
2008-10-21 19:40 ` Richard M. Stallman
0 siblings, 1 reply; 13+ messages in thread
From: Kenichi Handa @ 2008-10-21 2:53 UTC (permalink / raw
To: rms; +Cc: lekktu, emacs-devel
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Docstring of `decode-coding-string' a bit misleading about insertion in buffer
2008-10-20 8:21 ` Juanma Barranquero
2008-10-20 10:43 ` Kenichi Handa
2008-10-20 17:04 ` Richard M. Stallman
@ 2008-10-20 17:04 ` Richard M. Stallman
2 siblings, 0 replies; 13+ messages in thread
From: Richard M. Stallman @ 2008-10-20 17:04 UTC (permalink / raw
To: Juanma Barranquero; +Cc: emacs-devel, handa
> 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.
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2008-10-22 1:23 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2008-10-17 14:19 Docstring of `decode-coding-string' a bit misleading about insertion in buffer Juanma Barranquero
2008-10-20 7:04 ` Kenichi Handa
2008-10-20 7:18 ` Juanma Barranquero
2008-10-20 8:12 ` Kenichi Handa
2008-10-20 8:21 ` Juanma Barranquero
2008-10-20 10:43 ` Kenichi Handa
2008-10-21 15:57 ` Eli Zaretskii
2008-10-21 22:47 ` Juanma Barranquero
2008-10-22 1:23 ` Kenichi Handa
2008-10-20 17:04 ` Richard M. Stallman
2008-10-21 2:53 ` Kenichi Handa
2008-10-21 19:40 ` Richard M. Stallman
2008-10-20 17:04 ` Richard M. Stallman
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.