bug#57009: Obscure doc string of new variable syntax-wholeline-max

bug#57009: Obscure doc string of new variable syntax-wholeline-max

[Alan Mackenzie]

Hello, Emacs.

I came across the variable syntax-wholeline-max in reading a new bug
archive.  Its doc string, in full, is:

    syntax-wholeline-max is a variable defined in `syntax.el'.

    Its value is 10000

    Maximum line length for syntax operations.
    If lines are longer than that, syntax operations will treat them as chunks
    of this size.  Misfontification may then occur.
    This is a tradeoff between correctly applying the syntax rules,
    and avoiding major slowdown on pathologically long lines.

      Probably introduced at or before Emacs version 29.1.

..  There are several bugs here:
(i) It is not clear what is meant by "syntax operations".  These should
  be listed and if necessary, explained.
(ii) It is not clear what it means for a "syntax operation" to treat a
  line "as a chunk".  This should be explained.
(iii) "Misfontification" may well occur, but what about other bad effects
  of ignoring correct syntax?  Don't they deserve a mention?
(iv) There is no mention of a mechanism to disable this "chunking"
  effect, whatever it might be.  If there is one, it should be
  documented, if there's not, this should be stated.

I'm not asking for an explanation of these things.  I can look up the
source code and work it out.  I'm asking them to be fixed so that other
people don't also have to read the source code.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#57009: Obscure doc string of new variable syntax-wholeline-max

[Lars Ingebrigtsen]

Alan Mackenzie <acm@muc.de> writes:

>     Maximum line length for syntax operations.
>     If lines are longer than that, syntax operations will treat them as chunks
>     of this size.  Misfontification may then occur.
>     This is a tradeoff between correctly applying the syntax rules,
>     and avoiding major slowdown on pathologically long lines.
>
>       Probably introduced at or before Emacs version 29.1.
>
> ..  There are several bugs here:
> (i) It is not clear what is meant by "syntax operations".  These should
>   be listed and if necessary, explained.

You mean mention syntax-ppss?

> (ii) It is not clear what it means for a "syntax operation" to treat a
>   line "as a chunk".  This should be explained.

It's saying that it's processing the line chunk-wise.  I think that's
pretty clear?

> (iii) "Misfontification" may well occur, but what about other bad effects
>   of ignoring correct syntax?  Don't they deserve a mention?

Do they?

> (iv) There is no mention of a mechanism to disable this "chunking"
>   effect, whatever it might be.  If there is one, it should be
>   documented, if there's not, this should be stated.

That seems self-evident -- you increase the size?

There doesn't really seem to be much to alter here to me, but perhaps
others have other opinions; adding Stefan to the CCs.

bug#57009: Obscure doc string of new variable syntax-wholeline-max

[Alan Mackenzie]

Hello, Lars.

On Sat, Aug 06, 2022 at 14:56:24 +0200, Lars Ingebrigtsen wrote:
> Alan Mackenzie <acm@muc.de> writes:

> >     Maximum line length for syntax operations.
> >     If lines are longer than that, syntax operations will treat them as chunks
> >     of this size.  Misfontification may then occur.
> >     This is a tradeoff between correctly applying the syntax rules,
> >     and avoiding major slowdown on pathologically long lines.

> >       Probably introduced at or before Emacs version 29.1.

> > ..  There are several bugs here:
> > (i) It is not clear what is meant by "syntax operations".  These should
> >   be listed and if necessary, explained.

> You mean mention syntax-ppss?

Yes, if that is one of the operations involved.  Also, if pertinent,
parse-partial-sexp, forward-list and friends, syntax-propertize, ....

> > (ii) It is not clear what it means for a "syntax operation" to treat a
> >   line "as a chunk".  This should be explained.

> It's saying that it's processing the line chunk-wise.  I think that's
> pretty clear?

If it's clear to you, please explain in a way that's clear to me.  :-)

Say the chunk is 64 characters long.  Doesn't parse-partial-sexp process
that "as a chunk" anyway?  How does one determine where a "chunk" starts
and where it ends?  What does "treating a line as a chunk" do that is new
that we didn't do before?

> > (iii) "Misfontification" may well occur, but what about other bad effects
> >   of ignoring correct syntax?  Don't they deserve a mention?

> Do they?

They might, it depends how clear the rest of an amended text makes
things.  For example, will C-M-n still work?

> > (iv) There is no mention of a mechanism to disable this "chunking"
> >   effect, whatever it might be.  If there is one, it should be
> >   documented, if there's not, this should be stated.

> That seems self-evident -- you increase the size?

It is anything but self-evident.  It might be by setting the variable to
0, it might be by setting it to nil, it might be, as you suggest by
setting it to a larger size than you think will occur in practice (i.e.
there's no way to disable it).  All these ways are in use in Emacs.

> There doesn't really seem to be much to alter here to me, but perhaps
> others have other opinions; adding Stefan to the CCs.

As matters stand, I'd have to read the source code to work out what this
variable is for.  I don't think I should have to.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#57009: Obscure doc string of new variable syntax-wholeline-max

[Lars Ingebrigtsen]

Alan Mackenzie <acm@muc.de> writes:

> Say the chunk is 64 characters long.  Doesn't parse-partial-sexp process
> that "as a chunk" anyway?  How does one determine where a "chunk" starts
> and where it ends?  What does "treating a line as a chunk" do that is new
> that we didn't do before?

I interpret that as saying that the line is split into chunks (of the
length the variable says) and processed one after the other.

> It is anything but self-evident.  It might be by setting the variable to
> 0, it might be by setting it to nil, it might be, as you suggest by
> setting it to a larger size than you think will occur in practice (i.e.
> there's no way to disable it).  All these ways are in use in Emacs.

Yes, that's true.