Merge pull request #31602 from zeertzjq/vim-0a4e57f

vim-patch: doc updates

3 files changed, 47 insertions, 22 deletions

diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index 768a449581..9e44f54e6b 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -1443,18 +1443,17 @@ since formatting is highly dependent on the type of file.  It makes
 sense to use an |autoload| script, so the corresponding script is only loaded
 when actually needed and the script should be called <filetype>format.vim.
 
-For example, the XML filetype plugin distributed with Vim in the $VIMRUNTIME
-directory, sets the 'formatexpr' option to: >
+For example, the XML filetype plugin distributed with Vim in the
+$VIMRUNTIME/ftplugin directory, sets the 'formatexpr' option to: >
 
    setlocal formatexpr=xmlformat#Format()
 
 That means, you will find the corresponding script, defining the
-xmlformat#Format() function, in the directory:
-`$VIMRUNTIME/autoload/xmlformat.vim`
+xmlformat#Format() function, in the file `$VIMRUNTIME/autoload/xmlformat.vim`
 
 Here is an example script that removes trailing whitespace from the selected
-text.  Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: >
-
+text.  Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim:
+>vim
   func! format#Format()
     " only reformat on explicit gq command
     if mode() != 'n'
@@ -1487,7 +1486,7 @@ debugging it helps to set the 'debug' option.
 
 							*right-justify*
 There is no command in Vim to right justify text.  You can do it with
-an external command, like "par" (e.g.: "!}par" to format until the end of the
+an external command, like "par" (e.g.: `:.,}!par` to format until the end of the
 paragraph) or set 'formatprg' to "par".
 
 							*format-comments*
@@ -1553,7 +1552,7 @@ type of comment string.  A part consists of:
 	some indent for the start or end part that can be removed.
 
 When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
-comment string repeats at the start of each line.  The flags field may be
+comment string repeats at the start of each line.  The {flags} field may be
 empty.
 
 Any blank space in the text before and after the {string} is part of the
diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt
index b844e0ed85..9798170dbc 100644
--- a/runtime/doc/fold.txt
+++ b/runtime/doc/fold.txt
@@ -82,9 +82,11 @@ The most efficient is to call a function without arguments: >
 The function must use v:lnum.  See |expr-option-function|.
 
 These are the conditions with which the expression is evaluated:
+
 - The current buffer and window are set for the line.
 - The variable "v:lnum" is set to the line number.
-- The result is used for the fold level in this way:
+
+The result of foldexpr then determines the fold level as follows:
   value			meaning ~
   0			the line is not in a fold
   1, 2, ..		the line is in a fold with this level
@@ -99,6 +101,8 @@ These are the conditions with which the expression is evaluated:
   "<1", "<2", ..	a fold with this level ends at this line
   ">1", ">2", ..	a fold with this level starts at this line
 
+The result values "=", "s" and "a" are more expensive, please see |fold-expr-slow|.
+
 It is not required to mark the start (end) of a fold with ">1" ("<1"), a fold
 will also start (end) when the fold level is higher (lower) than the fold
 level of the previous line.
@@ -112,12 +116,6 @@ recognized, there is no error message and the fold level will be zero.
 For debugging the 'debug' option can be set to "msg", the error messages will
 be visible then.
 
-Note: Since the expression has to be evaluated for every line, this fold
-method can be very slow!
-
-Try to avoid the "=", "a" and "s" return values, since Vim often has to search
-backwards for a line for which the fold level is defined.  This can be slow.
-
 If the 'foldexpr' expression starts with s: or |<SID>|, then it is replaced
 with the script ID (|local-function|). Examples: >
 		set foldexpr=s:MyFoldExpr()
@@ -143,6 +141,35 @@ end in that line.
 It may happen that folds are not updated properly.  You can use |zx| or |zX|
 to force updating folds.
 
+Minimizing Computational Cost			             *fold-expr-slow*
+
+Due to its computational cost, this fold method can make Vim unresponsive,
+especially when the fold level of all lines have to be initially computed.
+Afterwards, after each change, Vim restricts the computation of foldlevels
+to those lines whose fold level was affected by it (and reuses the known
+foldlevels of all the others).
+
+The fold expression should therefore strive to minimize the number of dependent
+lines needed for the computation of a given line: For example, try to avoid the
+"=", "a" and "s" return values, because these will require the evaluation of the
+fold levels on previous lines until an independent fold level is found.
+
+If this proves difficult, the next best thing could be to cache all fold levels
+in a buffer-local variable (b:foldlevels) that is only updated on |b:changedtick|:
+>vim
+  func MyFoldFunc()
+    if b:lasttick == b:changedtick
+      return b:foldlevels[v:lnum - 1]
+    endif
+    let b:lasttick = b:changedtick
+    let b:foldlevels = []
+    " compute foldlevels ...
+    return b:foldlevels[v:lnum - 1]
+  enddef
+  set foldexpr=s:MyFoldFunc()
+<
+In above example further speedup was gained by using a function without
+arguments (that must still use v:lnum). See |expr-option-function|.
 
 SYNTAX						*fold-syntax*
 
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index ec4732c05a..41fcdc3e1b 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -86,13 +86,6 @@ command.  There are however, two general exceptions:
    end of the motion is moved to the end of the previous line and the motion
    becomes inclusive.  Example: "}" moves to the first line after a paragraph,
    but "d}" will not include that line.
-
-					*inclusive-motion-selection-exclusive*
-When 'selection' is "exclusive", |Visual| mode is active and an inclusive
-motion has been used, the cursor position will be adjusted by another
-character to the right, so that visual selction includes the expected text and
-can be acted upon.
-
 						*exclusive-linewise*
 2. If the motion is exclusive, the end of the motion is in column 1 and the
    start of the motion was at or before the first non-blank in the line, the
@@ -122,6 +115,12 @@ This cannot be repeated: >
 	endif<CR>
 Note that when using ":" any motion becomes charwise exclusive.
 
+					*inclusive-motion-selection-exclusive*
+When 'selection' is "exclusive", |Visual| mode is active and an inclusive
+motion has been used, the cursor position will be adjusted by another
+character to the right, so that visual selction includes the expected text and
+can be acted upon.
+
 								*forced-motion*
 FORCING A MOTION TO BE LINEWISE, CHARWISE OR BLOCKWISE