vim-patch:8.2.0865 syntax: Add command to control how foldlevel is computed

Problem:    Syntax foldlevel is taken from the start of the line.
Solution:   Add ":syn foldlevel" to be able to use the minimal foldlevel in the line.
https://github.com/vim/vim/commit/e35a52aee718c881bdfa69a47a1068df6ab6c60a

With `foldmethod=syntax` the foldlevel of a line is computed based
on syntax items on the line.  Previously we always used the level
of the syntax item containing the start of the line.  This works
well in cases such as:

    if (...) {
      ...
    }
    else if (...) {
      ...
    }
    else {
      ...
    }

which folds like this:

    +---  3 lines: if (...) {---------------------------
    +---  3 lines: else if (...) {----------------------
    +---  3 lines: else {-------------------------------

However, the code:

    if (...) {
      ...
    } else if (...) {
      ...
    } else {
      ...
    }

folds like this:

    +---  7 lines: if (...) {---------------------------

We can make the latter case fold like this:

    +---  2 lines: if (...) {---------------------------
    +---  2 lines: } else if (...) {--------------------
    +---  3 lines: } else {-----------------------------

by choosing on each line the lowest fold level that is followed
by a higher fold level.

Add a syntax command

    :syntax foldlevel [start | minimum]

to choose between these two methods of computing the foldlevel of
a line.

1 files changed, 20 insertions, 0 deletions

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 57337aeac2..7da886dabd 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -3522,6 +3522,24 @@ DEFINING CASE						*:syn-case* *E390*
 :sy[ntax] case
 	Show either "syntax case match" or "syntax case ignore" (translated).
 
+
+DEFINING FOLDLEVEL					*:syn-foldlevel*
+
+:sy[ntax] foldlevel [start | minimum]
+	This defines how the foldlevel of a line is computed when using
+	foldmethod=syntax (see |fold-syntax| and |:syn-fold|):
+
+	start:		Use level of item containing start of line.
+	minimum:	Use lowest local-minimum level of items on line.
+
+	The default is 'start'.  Use 'minimum' to search a line horizontally
+	for the lowest level contained on the line that is followed by a
+	higher level.  This produces more natural folds when syntax items
+	may close and open horizontally within a line.
+
+:sy[ntax] foldlevel
+	Show either "syntax foldlevel start" or "syntax foldlevel minimum".
+
 SPELL CHECKING						*:syn-spell*
 
 :sy[ntax] spell [toplevel | notoplevel | default]
@@ -3985,6 +4003,8 @@ This will make each {} block form one fold.
 The fold will start on the line where the item starts, and end where the item
 ends.  If the start and end are within the same line, there is no fold.
 The 'foldnestmax' option limits the nesting of syntax folds.
+See |:syn-foldlevel| to control how the foldlevel of a line is computed
+from its syntax items.
 
 
 			*:syn-contains* *E405* *E406* *E407* *E408* *E409*