bug#33167: 26; Doc string of `region-extract-function'

[Drew Adams]

> >  - nil: return the content as a string.
> >
> > What does that mean, for a noncontiguous region?  Are the buffer
> > substrings for all of the region segments (zones) concatenated
> together?
> > If so, say that.
> 
> No, the value is a list of strings in this case.  I fixed the doc
> string to say that.

Good.  Thanks.  So with nil the value is a list of strings,
not a string that is "the content" of the noncontiguous region.

> > 1. What are the BEG and END args passed to `filter-buffer-substring'?
> >    Is BEG the smallest car of any of the zones in the noncontiguous
> >    region, and END the largest cdr of any of the zones?
> 
> They are the first and the last positions of the region for
> filter-buffer-substring to act upon.  That function is not supposed to
> process non-contiguous regions.

Yes, but where do they come from, for that call?  How do they
relate to, or how are they derived from, the noncontiguous
region? Are they point and mark?  Something else?  That's the
question.

The only arg to the function that is the value of
`region-extract-function` is METHOD.  The "region's content"
is presumably the content of the noncontiguous region.  And
presumably it is that that is "the content" that is returned
as a string.  How is that string derived from the noncontiguous
region?  That's the question.

No connection is made in this doc, AFAICT, between the
noncontiguous region and the BEG and END that are passed
to `filter-buffer-substring'.

> > 2. `filter-buffer-substring' calls the value of
> >    `filter-buffer-substring-function' with the same 3 args.  But what
> >    can that function do with BEG and END (which are what?)?  It's
> >    presumably a function that expects to use a single stretch of
> >    buffer text from BEG to END.  But here we're talking about a 
> >    noncontiguous
> 
> No, we are talking about contiguous regions when this function is
> concerned.

Sorry, but I don't understand.  What contiguous regions
are we talking about?  How/where in this doc did you
get from a noncontiguous region to contiguous regions?

I haven't see your update to the doc string, but so far
your description here doesn't give the impression that
these questions have been cleared up.

> > 3. The 3rd arg to `filter-buffer-substring' just deletes the region
> >    from BEG to END if it is non-nil, so it seems like passing that
> >    non-nil 3rd arg is useless, as the region gets deleted anyway, by
> >    `region-extract-function'.
> 
> Not sure what is the problem here.

Not sure what you're saying.  Are you saying that I'm wrong
that a non-nil 3rd arg just deletes the region?  Or are you
saying that I'm wrong that that non-nil 3rd arg is useless
because the region is deleted anyway?  This doc is not clear
to me.

> > 4. The use of `filter-buffer-substring' is also unclear.  It is passed
> >    BEG and END (and METHOD, but see #3, above).  And it filters the
> >    buffer text between BEG and END.  But see #1 above - are BEG and
> >    END buffer positions that make sense for the whole region text?
> >    Just what happens here?
> 
> See above.  It is not the job of filter-buffer-substring to DTRT when
> the region is non-contiguous, it is the job of its callers.  See
> rect.el for one example.

See above.  What are BEG and END that get passed to it?
The doc should be able to make clear what the behavior
is, without someone needing to investigate the code of
rect.el.  Plus, noncontiguous regions are more general
than rectangles.  The doc should make clear what happens
in the general case.

> > This is quite unclear to me.  And following the rabbit hole from
> > `region-extract-function' down to `filter-buffer-substring' and then
> > to `filter-buffer-substring-function' does not make things more clear.
> 
> It isn't supposed to.  If you want to see how non-contiguous regions
> are used in this context, you need to look in places that do so.

The doc should make clear in general terms what extracting
a noncontiguous region is about, and just what the value of
`region-extract-function' does: what its arguments are and
what its return value is (as a function of those arguments).

If someone has to look at the (very few, and particular
to rectangles, BTW) code where `region-extract-function'
is currently used to try to understand it, and the doc
doesn't help but at best misleads, then we might as well
have no doc for it.

I did what you suggest before filing the bug report:
checked all of the existing occurrences.  I felt that
the doc is wrong wrt what really happens, and I feel
that there's a need for a general description of this
variable which helps.

> > Or is what happens perhaps that EACH element of the noncontiguous
> > region, that is, each zone (BEG<N> . END<N>) of the list ((BEG1 .
> > END1) ...) gets filtered by `filter-buffer-substring', passing
> > its BEG END and METHOD
> 
> Yes!

Then please say that in the doc.  The function iterates
over the zones of the noncontiguous region, doing ___.

> > - so that a mapcar is applied?
> 
> Not literally, but the result is a list, yes.

If you haven't already done so, please say that in the doc.

> > In that case, how are the resulting buffer substrings assembled -
> > are they concatenated to get the return value?
> 
> No, you get a list.  Again, see rect.el.
> 
> Bottom line: I fixed the doc string of region-extract-function to say
> what are the values when the region is non-contiguous, and how
> filter-buffer-substring is invoked in that case.  But I don't think
> there's anything else that should be done here, because the details of
> using this facility for non-contiguous regions is entirely up to the
> Lisp program which implements such a feature.

Sounds like you've already corrected some, maybe all, of
what was incorrect.  See above, in case you were unclear
about some of the problems with it and you want to make
some of that clearer.

Thanks for looking at this.