Re: Unbalanced change hooks (part 2) [Documentation fix still remaining]

[Eli Zaretskii]

> From: Daniel Colascione <address@hidden>
> Date: Sun, 28 Aug 2016 20:18:32 -0700
> 
>     Please trust me that the documentation misleads.

You are welcome to suggest more accurate wording that describes the
current implementation.

> b-c-f and a-c-f are symmetric in name and signature. b-c-f is documented as 
> "List of functions to call before each text change." a-c-f is documented as 
> "List of functions to call after each text change." The elisp manual 
> documentation is similarly symmetric. This symmetry produces an expectation 
> that the behavior is symmetric, and this expectation is reinforced by how the 
> observed behavior is almost always symmetric in practice. Symmetric behavior 
> here is also what intuitively makes sense.

This is a naïve interpretation of what a "change" means and entails.
In reality, some changes are done with a single call to an insdel
function, while others need multiple calls that delete and insert text
piecemeal.  Thus the need to call the hooks before and after each
insdel call only sometimes.

Your bell analogy has the same issue: internally, the "chime" is in
fact a complex array of transitions and changes, not an atomic effect.
By treating it as an atomic unit, you actually uphold the view taken
by the current implementation, which attempts to minimize the number
of hook calls per change.

> Sure, I guess you could argue that current Emacs behavior is consistent with 
> the manual, but it's not what anyone would reasonably expect, and the current 
> behavior is surprising even to people who have been writing elisp for a long 
> time.

Surprising or not, the existing implementation is in use for many
years, and until now no complaints were presented about it.  And even
now we have a single complaint from a single use case of a single
package (which meanwhile fixed the problem without any core changes).
Which is ample evidence that the existing implementation does a good
job after all.

> I'm confident that with enough review, the core code could be changed to make 
> b-c-f and a-c-f symmetric without causing weird bugs elsewhere. The necessary 
> refactoring will probably make the logic cleaner as well.
> 
> Of course there's a risk that changing b-c-f will itself produce weird side 
> effects, but I have a hard time seeing how any code could actually depend on 
> the current surprising behavior.

That's exactly the nonchalant attitude towards changes in core that
explains why, after 30-odd years of development, which should have
given us an asymptotically more and more stable Emacs, we still
succeed quite regularly to break core code and basic features, while
"confidently" relying on our mythical abilities to refactor correctly
without any serious testing coverage.  Never again.