bug#56682: feature/improved-locked-narrowing 9dee6df39c: Reworked locked narrowing.

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

> You have to know where your function is called and by which caller
> a lock was placed.

That doesn't seem sufficient, because you need to additionally find the
name of the tag they used.  AFAICT currently you can only find that out
by looking at the code.  I think the names should be documented
somewhere else than just in the code itself.

> Currently there are three such tags (and I don't expect more
> tags in core): fontification-functions, pre-command-hook and
> post-command-hook.

These names seem wrong: I don't think the tag should say when/where the
lock happened to be placed, but what caused it to be placed.  IIUC all
three cases up there share the same reason: overly long lines.
So I think they should all use the same tag which could be something
like `long-lines` or maybe they should use names such as
`long-line-threshold` and `large-hscroll-threshold` to record precisely
the cause for the lock.

>> Looking more at the code, I have another question: why is
>> `narrowing_locks` a global alist indexed by buffers, instead of being
>> a buffer-local variable?
>
> For efficiency reasons.  If it were a buffer-local variable,
> reset_outermost_narrowings, which is called by redisplay_internal, would
> have to consider all buffers, which would become unnecessarily slow with
> many (say 1000) buffers.  With a global alist, only the (few) buffers in
> which narrowing locks are actually in effect are considered.

Then I suggest you put a comment to that effect in the code.  I also
can't understand why we need `xdisp.c` to call
`reset_outermost_narrowings`.  I see you tried to explain it in the
doc-comment of the function but I failed to understand the explanation.
Maybe you could extend the comment by pointing to a very concrete
example (or maybe a discussion on the mailing list)?

Another problem I see with it is that it seems to presume a very
particular use of locked narrowing (such as the one installed by the
long-lines code), whereas other uses of locked narrowing might not want
to be reset during redisplay.

Similarly the doc-comment of `narrowing_lock_get_bound` talks about
"bounds ... that are visible on display", but that function doesn't know
what bounds are visible on display, actually.  The interaction with
what's visible on display completely depends on when/where it's called
and when/where locks are installed.  Could you try and clarify the
doc-comment to say what the function actually does, and then separately
explain how it *may* relate with "what's visible on display" and under
which assumption this relation may hold?
IIUC what the function does when OUTERMOST is true is return the
narrowing that was in effect when the first lock was installed, right?


        Stefan