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).