GNU bug report logs - #25626
25.1; doc of `bufferpos-to-filepos' for type `exact'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 25626 in the body.
You can then email your comments to 25626 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.1; doc of `bufferpos-to-filepos' for type `exact'
Date: Sun, 5 Feb 2017 09:20:13 -0800 (PST)

The doc string says this:

  ‘exact’, in which case we may end up re-(en/de)coding a large
    part of the file/buffer.

And (elisp) `Text Representations' says this:

  ‘exact’
    The result must be accurate.  The function may need to encode
    and decode a large part of the buffer.

If I understand the code right, I think both of these are misleading.
They can give the impression that the text in the region can have its
encoding changed in its buffer.

But when `bufferpos-to-filepos' encodes some text it puts the resulting
text in a different, temporary buffer, and returns its position - the
original text (in the original buffer) does not have its encoding
changed.

Please consider clarifying this, so that it lets users know that the
encoding cost of `exact' is only one of performance and that the buffer
text is not changed in any way (in particular, its encoding is not
changed).

Or if I'm mistaken, and it does possibly change the encoding of some of
the buffer text, then please consider clarifying the doc to state this
explicitly.

In other words, please elaborate on (clarify) what is meant by "may need
to encode and decode a large part of the buffer" and "may end up
re-(en/de)coding a large part of the file/buffer".

In GNU Emacs 25.1.1 (x86_64-w64-mingw32)
 of 2016-11-15
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --without-compress-install 'CFLAGS=-O2
 -static -g3''

Message #8 received at 25626 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25626 <at> debbugs.gnu.org
Subject: Re: bug#25626: 25.1; doc of `bufferpos-to-filepos' for type `exact'
Date: Sun, 05 Feb 2017 20:34:02 +0200

> Date: Sun, 5 Feb 2017 09:20:13 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc string says this:
> 
>   ‘exact’, in which case we may end up re-(en/de)coding a large
>     part of the file/buffer.
> 
> And (elisp) `Text Representations' says this:
> 
>   ‘exact’
>     The result must be accurate.  The function may need to encode
>     and decode a large part of the buffer.
> 
> If I understand the code right, I think both of these are misleading.
> They can give the impression that the text in the region can have its
> encoding changed in its buffer.

I don't understand how you get that impression.  You do know that
encoding text and then decoding it back produces the same text as was
there originally, right?

This text simply says that this option might be computationally
expensive.

Message #11 received at 25626 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 25626 <at> debbugs.gnu.org
Subject: RE: bug#25626: 25.1; doc of `bufferpos-to-filepos' for type `exact'
Date: Sun, 5 Feb 2017 10:58:24 -0800 (PST)

> >   ‘exact’, in which case we may end up re-(en/de)coding a large
> >     part of the file/buffer.
> >
> > And (elisp) `Text Representations' says this:
> >
> >   ‘exact’
> >     The result must be accurate.  The function may need to encode
> >     and decode a large part of the buffer.
> >
> > If I understand the code right, I think both of these are misleading.
> > They can give the impression that the text in the region can have its
> > encoding changed in its buffer.
> 
> I don't understand how you get that impression.  You do know that
> encoding text and then decoding it back produces the same text as was
> there originally, right?
> 
> This text simply says that this option might be computationally
> expensive.

If that's the intent then say that.  And I think it is the
intent, hence this bug: please just say that.

Saying "we may end up re-(en/de)coding" and "may need to
encode and decode" does _not_ specify that the text is encoded
_and then_ decoded back again, resulting in no change to the
buffer.  And the former means re-encode OR re-decode, not AND.)

And in fact, IIUC, the text is encoded to a separate buffer
(arg DESTINATION of `encode-coding-region'); it is not encoded
in the original buffer - the text in that buffer is unaffected,
and not because it is encoded and then decoded back.  But
perhaps I misunderstand this part.

[There are also typos in the doc string of `encode-coding-region':
"Optional 4th arguments" should be "Optional 4th argument" and
"is replace by" should be "is replaced by".]

Message #16 received at 25626-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25626-done <at> debbugs.gnu.org
Subject: Re: bug#25626: 25.1; doc of `bufferpos-to-filepos' for type `exact'
Date: Sun, 05 Feb 2017 21:56:02 +0200

> Date: Sun, 5 Feb 2017 10:58:24 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 25626 <at> debbugs.gnu.org
> 
> > This text simply says that this option might be computationally
> > expensive.
> 
> If that's the intent then say that.  And I think it is the
> intent, hence this bug: please just say that.

Done.

> [There are also typos in the doc string of `encode-coding-region':
> "Optional 4th arguments" should be "Optional 4th argument" and
> "is replace by" should be "is replaced by".]

Fixed.

Message #19 received at 25626-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 25626-done <at> debbugs.gnu.org
Subject: RE: bug#25626: 25.1; doc of `bufferpos-to-filepos' for type `exact'
Date: Sun, 5 Feb 2017 12:22:38 -0800 (PST)

> > > This text simply says that this option might be computationally
> > > expensive.
> >
> > If that's the intent then say that.  And I think it is the
> > intent, hence this bug: please just say that.
> 
> Done.
> 
> > [There are also typos in the doc string of `encode-coding-region':
> > "Optional 4th arguments" should be "Optional 4th argument" and
> > "is replace by" should be "is replaced by".]
> 
> Fixed.

Thank you.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.