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

From: Drew Adams <[email-masked]>
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".]