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

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

[Drew Adams]

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''

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

[Eli Zaretskii]

> Date: Sun, 5 Feb 2017 09:20:13 -0800 (PST)
> From: Drew Adams <drew.adams@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.

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

[Drew Adams]

> >   ‘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".]

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

[Eli Zaretskii]

> Date: Sun, 5 Feb 2017 10:58:24 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 25626@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.

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

[Drew Adams]

> > > 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.