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

[Gregory Heytings]

> > > There's one thing I cannot seem to be able to find in the 
> > > documentation you added: how can a Lisp program know that it is being 
> > > run under a "labeled narrowing",
> >
> > A function/macro to check that could indeed be added, its body would 
> > be:
> >
> > (save-restriction (widen) (buffer-narrowed-p))
>
> We should add it and document it, but I'm surprised that there's no 
> easier way.  One problem with the above is that it could cause a more 
> thorough redisplay because it fiddles with buffer restrictions.

If necessary, a specific function which does not widen could be added to 
do that, using narrowing_lock_peek_tag:

DEFUN ("...", ...) (void)
{
  if (NILP (narrowing_lock_peek_tag (Fcurrent_buffer ())))
    return Qnil;
  else
    return Qt;
}

> Also, this doesn't return the label itself.

Indeed, but returning the label would defeat the purpose of the tool.  If 
a program can by itself determine that it is in a labeled narrowing and 
get its label, it can escape that narrowing without much ado.

> > That information should be given in the docstring of the function that 
> > creates that narrowing.  It is now present in the docstrings of the 
> > three hooks where it is used:
>
> Yes, but how do I know which one of these is in effect when my function 
> is called?

The only way is to look at the call tree of the function.

(Note that I'm writing the above to "defend" a feature that I still 
believe should better be removed from Emacs.)