bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Drew Adams]

Subject line says it all.  This node says zero about multiline font
lock.  No apparent relation between the two.  If there is a relation,
then it needs to be pointed out.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-04-25 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Stefan Monnier]

> Subject line says it all.  This node says zero about multiline font
> lock.  No apparent relation between the two.  If there is a relation,
> then it needs to be pointed out.
 
I'm not sure what more you need.  It already says:

   When a buffer is changed, the region that Font Lock refontifies is
   by default the smallest sequence of whole lines that spans the change.
   While this works well most of the time, sometimes it doesn't---for
   example, when a change alters the syntactic meaning of text on an
   earlier line.


-- Stefan

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Drew Adams]

> > This node says zero about multiline font lock.  No apparent
> > relation between the two.  If there is a relation,
> > then it needs to be pointed out.
>  
> I'm not sure what more you need.  It already says:
> 
>    When a buffer is changed, the region that Font Lock refontifies is
>    by default the smallest sequence of whole lines that spans 
>    the change.
>    While this works well most of the time, sometimes it doesn't---for
>    example, when a change alters the syntactic meaning of text on an
>    earlier line.

What limits the import of this node to multiline font-lock?  Nothing that I can
see.

This text simply says that the refontification is for a set of (presumably
contiguous) whole lines.  One can read between the lines to see that it might
not work well for - among other things - multiline font-lock.  But there is
nothing about the text in this node that limits it to multiline font-lock.

This node is about refontification after buffer changes.  It is not, logically,
a subnode of `Multiline Font Lock Constructs'.

The info here belongs in or under node `Change Hooks', or possibly somewhere
else in the font-lock section of the manual.  You can link to this text from the
multiline font-lock section.

And I suggest adding explicitly, after the last line you quoted, that in
particular this is often the case for multiline font-lock.

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Stefan Monnier]

> What limits the import of this node to multiline font-lock?
> Nothing that I can see.

Maybe the problem is "your" notion of "multiline font-lock"?

There's no such thing as a "multiline font-lock" feature or
functionality, but only "Multiline Font Lock Constructs", i.e. there are
cases where a major mode needs to get font-lock to recognize elements
that span multiple lines.

> This node is about refontification after buffer changes.  It is not,
> logically, a subnode of `Multiline Font Lock Constructs'.

It is about having to extend the refontification area because
refontifying a single-line is not sufficient, presumably because the
major mode has to handle a multiline font-lock construct.


        Stefan

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Drew Adams]

> > What limits the import of this node to multiline font-lock?
> > Nothing that I can see.
> 
> Maybe the problem is "your" notion of "multiline font-lock"?
> 
> There's no such thing as a "multiline font-lock" feature or
> functionality, but only "Multiline Font Lock Constructs", 
> i.e. there are cases where a major mode needs to get font-lock
> to recognize elements that span multiple lines.

That _is_ "my" notion of "multiline font-lock" (and that's your term, not mine).

> > This node is about refontification after buffer changes.  It is not,
> > logically, a subnode of `Multiline Font Lock Constructs'.
>
> It is about having to extend the refontification area because
> refontifying a single-line is not sufficient, presumably because the
> major mode has to handle a multiline font-lock construct.

The node _says_ it is about what you say up to the comma.  You then add
"presumably...", which is _not_ part of the node content.  This info is missing.
Also missing is whether anything stronger than "presumably" applies.

The node content is about the region to refontify after a buffer change.  It
mentions that in some cases code might need to extend that region, to DTRT.
That's all that is said.

If the _only_ time this is pertinent is in the context of multiline font-lock
constructs, then please say so (and perhaps why, if helpful).  If it is not the
only time, then add that this _can_ happen, in particular, in the context of
multiline font-lock constructs.

You seem to be fighting making this text clear. Please clearly specify how and
how much the (current) node content is related to multiline font-lock
constructs.  That's what is missing.

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Stefan Monnier]

> > It is about having to extend the refontification area because
> > refontifying a single-line is not sufficient, presumably because the
> > major mode has to handle a multiline font-lock construct.
> 
> The node _says_ it is about what you say up to the comma.  You then
> add "presumably...", which is _not_ part of the node content.

It's just an application of reasoning: is "a single-line is not
sufficient", that must mean that there's more than one line involved.
I added the "presumably" because some user somewhere might decide he
likes to use this hook for something else.

> You seem to be fighting making this text clear.  Please clearly specify
> how and how much the (current) node content is related to multiline
> font-lock constructs.  That's what is missing.

I'm in a bad position to fix it, because AFAICT the text already says
very clearly what the var does, and when it makes sense to use it.
Could you provide a sample patch that would make the text clear to you?


        Stefan

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> You seem to be fighting making this text clear.  Please clearly specify
>> how and how much the (current) node content is related to multiline
>> font-lock constructs.  That's what is missing.
>
> I'm in a bad position to fix it, because AFAICT the text already says
> very clearly what the var does, and when it makes sense to use it.
> Could you provide a sample patch that would make the text clear to you?

The documentation seems clear to me, too, so I'm closing this report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8626: 24.0.50; (elisp) Region to Fontify after a Buffer Change - Why a child of Multiline Font Lock?

[Drew Adams]

If you dropped into this node from elsewhere than it parent, you would see
nothing about multiline font-lock constucts.  (And even coming from that node
you will see nothing about them.)

You would learn about refontifying the region after a buffer change, in
particular that in some cases refontifying needs to extend the region.  That's
all.

No one has yet answered the question that would unambiguously tie this to
multiline font-lock constructs: is this region extension for refontifying
pertinent _ONLY_ in the context of multi-line font-lock constructs?  As I said:

> If the _only_ time this is pertinent is in the context of 
> multiline font-lock constructs, then please say so (and
> perhaps why, if helpful).  If it is not the only time, then
> add that this _can_ happen, in particular, in 
> the context of multiline font-lock constructs.

Answer that question for readers and you've fixed this bug.