Merging upstream version 2:9.1.0698.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 192 insertions, 83 deletions

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index c07c3a4..736e664 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1,4 +1,4 @@
-*syntax.txt*	For Vim version 9.1.  Last change: 2024 Jun 17
+*syntax.txt*	For Vim version 9.1.  Last change: 2024 Aug 22
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -958,6 +958,25 @@ For Visual Basic use: >
 	:let g:filetype_asa = "aspvbs"
 	:let g:filetype_asp = "aspvbs"
 
+ASYMPTOTE					*asy.vim* *ft-asy-syntax*
+
+By default, only basic Asymptote keywords are highlighted. To highlight
+extended geometry keywords: >
+
+	:let g:asy_syn_plain = 1
+
+and for highlighting keywords related to 3D constructions: >
+
+	:let g:asy_syn_three = 1
+
+By default, Asymptote-defined colors (e.g: lightblue) are highlighted. To
+highlight TeX-defined colors (e.g: BlueViolet) use: >
+
+	:let g:asy_syn_texcolors = 1
+
+or for Xorg colors (e.g: AliceBlue): >
+
+	:let g:asy_syn_x11colors = 1
 
 BAAN						    *baan.vim* *baan-syntax*
 
@@ -1221,6 +1240,21 @@ will be classified as tcsh, UNLESS the "filetype_csh" variable exists.  If the
 "filetype_csh" variable exists, the filetype will be set to the value of the
 variable.
 
+CSV							*ft-csv-syntax*
+
+If you change the delimiter of a CSV file, its syntax highlighting will no
+longer match the changed file content. You will need to unlet the following
+variable: >
+
+	:unlet b:csv_delimiter
+
+And afterwards save and reload the file: >
+
+	:w
+	:e
+
+Now the syntax engine should determine the newly changed CSV delimiter.
+
 
 CYNLIB						*cynlib.vim* *ft-cynlib-syntax*
 
@@ -1874,6 +1908,10 @@ You can also disable this rendering by adding the following line to your
 vimrc file: >
 	:let html_no_rendering=1
 
+By default Vim synchronises the syntax to 250 lines before the first displayed
+line.  This can be configured using: >
+	:let html_minlines = 500
+<
 HTML comments are rather special (see an HTML reference document for the
 details), and the syntax coloring scheme will highlight all errors.
 However, if you prefer to use the wrong style (starts with <!-- and
@@ -1993,102 +2031,142 @@ idlsyntax_showerror_soft	Use softer colours by default for errors
 
 JAVA						*java.vim* *ft-java-syntax*
 
-The java.vim syntax highlighting file offers several options:
+The java.vim syntax highlighting file offers several options.
 
-In Java 1.0.2 it was never possible to have braces inside parens, so this was
-flagged as an error.  Since Java 1.1 this is possible (with anonymous
-classes), and therefore is no longer marked as an error.  If you prefer the
-old way, put the following line into your vim startup file: >
-	:let java_mark_braces_in_parens_as_errors=1
+In Java 1.0.2, it was never possible to have braces inside parens, so this was
+flagged as an error.  Since Java 1.1, this is possible (with anonymous
+classes); and, therefore, is no longer marked as an error.  If you prefer the
+old way, put the following line into your Vim startup file: >
+	:let g:java_mark_braces_in_parens_as_errors = 1
 
-All identifiers in java.lang.* are always visible in all classes.  To
-highlight them use: >
-	:let java_highlight_java_lang_ids=1
+All (exported) public types declared in `java.lang` are always automatically
+imported and available as simple names.  To highlight them, use: >
+	:let g:java_highlight_java_lang_ids = 1
 
-You can also highlight identifiers of most standard Java packages if you
-download the javaid.vim script at http://www.fleiner.com/vim/download.html.
-If you prefer to only highlight identifiers of a certain package, say java.io
-use the following: >
-	:let java_highlight_java_io=1
+You can also highlight types of most standard Java packages if you download
+the javaid.vim script at http://www.fleiner.com/vim/download.html.  If you
+prefer to only highlight types of a certain package, say `java.io`, use the
+following: >
+	:let g:java_highlight_java_io = 1
 Check the javaid.vim file for a list of all the packages that are supported.
 
-Function names are not highlighted, as the way to find functions depends on
-how you write Java code.  The syntax file knows two possible ways to highlight
-functions:
-
-If you write function declarations that are consistently indented by either
-a tab, or a space . . . or eight space character(s), you may want to set >
-	:let java_highlight_functions="indent"
-	:let java_highlight_functions="indent1"
-	:let java_highlight_functions="indent2"
-	:let java_highlight_functions="indent3"
-	:let java_highlight_functions="indent4"
-	:let java_highlight_functions="indent5"
-	:let java_highlight_functions="indent6"
-	:let java_highlight_functions="indent7"
-	:let java_highlight_functions="indent8"
+Headers of indented function declarations can be highlighted (along with parts
+of lambda expressions and method reference expressions), but it depends on how
+you write Java code.  Two formats are recognized:
+
+1) If you write function declarations that are consistently indented by either
+a tab, or a space . . . or eight space character(s), you may want to set one
+of >
+	:let g:java_highlight_functions = "indent"
+	:let g:java_highlight_functions = "indent1"
+	:let g:java_highlight_functions = "indent2"
+	:let g:java_highlight_functions = "indent3"
+	:let g:java_highlight_functions = "indent4"
+	:let g:java_highlight_functions = "indent5"
+	:let g:java_highlight_functions = "indent6"
+	:let g:java_highlight_functions = "indent7"
+	:let g:java_highlight_functions = "indent8"
 Note that in terms of 'shiftwidth', this is the leftmost step of indentation.
-However, if you follow the Java guidelines about how functions and classes are
-supposed to be named (with respect to upper- and lowercase) and there is any
-amount of indentation, you may want to set >
-	:let java_highlight_functions="style"
-If neither setting does work for you, but you would still want function
-declarations to be highlighted, create your own definitions by changing the
-definitions in java.vim or by creating your own java.vim that includes the
-original one and then adds the code to highlight functions.
-
-In Java 1.1 the functions System.out.println() and System.err.println() should
-only be used for debugging.  Therefore it is possible to highlight debugging
-statements differently.  To do this you must add the following definition in
-your startup file: >
-	:let java_highlight_debug=1
-The result will be that those statements are highlighted as 'Special'
-characters.  If you prefer to have them highlighted differently you must define
-new highlightings for the following groups.:
-    Debug, DebugSpecial, DebugString, DebugBoolean, DebugType
-which are used for the statement itself, special characters used in debug
-strings, strings, boolean constants and types (this, super) respectively.  I
-have opted to choose another background for those statements.
+
+2) However, if you follow the Java guidelines about how functions and types
+are supposed to be named (with respect to upper- and lowercase) and there is
+any amount of indentation, you may want to set >
+	:let g:java_highlight_functions = "style"
+
+In addition, you can combine any value of "g:java_highlight_functions" with >
+	:let g:java_highlight_signature = 1
+to have the name of a function with its parameter list parens distinctly
+highlighted from its type parameters, return type, and formal parameters; and
+to have the parameter list parens of a lambda expression with its arrow
+distinctly highlighted from its formal parameters or identifiers.
+
+If neither setting does work for you, but you would still want headers of
+function declarations to be highlighted, modify the current syntax definitions
+or compose new ones.
+
+Higher-order function types can be hard to parse by eye, so uniformly toning
+down some of their components may be of value.  Provided that such type names
+conform to the Java naming guidelines, you may arrange it with >
+	:let g:java_highlight_generics = 1
+
+In Java 1.1, the functions `System.out.println()` and `System.err.println()`
+should only be used for debugging.  Consider adding the following definition
+in your startup file: >
+	:let g:java_highlight_debug = 1
+to have the bulk of those statements colored as
+	*Debug		debugging statements,
+and to make some of their own items further grouped and linked:
+	*Special	as DebugSpecial,
+	*String		as DebugString,
+	*Boolean	as DebugBoolean,
+	*Type		as DebugType,
+which are used for special characters appearing in strings, strings proper,
+boolean literals, and special instance references (`super`, `this`, `null`),
+respectively.
 
 Javadoc is a program that takes special comments out of Java program files and
 creates HTML pages.  The standard configuration will highlight this HTML code
-similarly to HTML files (see |html.vim|).  You can even add Javascript
-and CSS inside this code (see below).  There are four differences however:
-  1. The title (all characters up to the first '.' which is followed by
-     some white space or up to the first '@') is colored differently (to change
-     the color change the group CommentTitle).
-  2. The text is colored as 'Comment'.
-  3. HTML comments are colored as 'Special'
-  4. The special Javadoc tags (@see, @param, ...) are highlighted as specials
-     and the argument (for @see, @param, @exception) as Function.
-To turn this feature off add the following line to your startup file: >
-	:let java_ignore_javadoc=1
-
-If you use the special Javadoc comment highlighting described above you
-can also turn on special highlighting for Javascript, visual basic
-scripts and embedded CSS (stylesheets).  This makes only sense if you
-actually have Javadoc comments that include either Javascript or embedded
-CSS.  The options to use are >
-	:let java_javascript=1
-	:let java_css=1
-	:let java_vb=1
-
-In order to highlight nested parens with different colors define colors
-for javaParen, javaParen1 and javaParen2, for example with >
+similarly to HTML files (see |html.vim|).  You can even add JavaScript and CSS
+inside this code (see below).  The HTML rendering diverges as follows:
+  1. The first sentence (all characters up to the first period `.`, which is
+     followed by a whitespace character or a line terminator, or up to the
+     first block tag, e.g. `@param`, `@return`) is colored as
+	*SpecialComment	special comments.
+  2. The text is colored as
+	*Comment	comments.
+  3. HTML comments are colored as
+	*Special	special symbols.
+  4. The standard Javadoc tags (`@code`, `@see`, etc.) are colored as
+	*Special	special symbols
+     and some of their arguments are colored as
+	*Function	function names.
+To turn this feature off, add the following line to your startup file: >
+	:let g:java_ignore_javadoc = 1
+
+If you use the special Javadoc comment highlighting described above, you can
+also turn on special highlighting for JavaScript, Visual Basic scripts, and
+embedded CSS (stylesheets).  This only makes sense if any of these languages
+actually appear in Javadoc comments.  The variables to use are >
+	:let g:java_javascript = 1
+	:let g:java_css = 1
+	:let g:java_vb = 1
+Note that these three variables are maintained in the HTML syntax file.
+
+Numbers and strings can be recognized in non-Javadoc comments with >
+	:let g:java_comment_strings = 1
+
+When 'foldmethod' is set to "syntax", blocks of code and multi-line comments
+will be folded.  No text is usually written in the first line of a multi-line
+comment, making folded contents of Javadoc comments less informative with the
+default 'foldtext' value; you may opt for showing the contents of a second
+line for any comments written in this way, and showing the contents of a first
+line otherwise, with >
+	:let g:java_foldtext_show_first_or_second_line = 1
+
+Trailing whitespace characters or a run of space characters before a tab
+character can be marked as an error with >
+	:let g:java_space_errors = 1
+but either kind of an error can be suppressed by also defining one of >
+	:let g:java_no_trail_space_error = 1
+	:let g:java_no_tab_space_error = 1
+
+In order to highlight nested parens with different colors, define colors for
+`javaParen`, `javaParen1`, and `javaParen2`.  For example, >
 	:hi link javaParen Comment
 or >
 	:hi javaParen ctermfg=blue guifg=#0000ff
 
 If you notice highlighting errors while scrolling backwards, which are fixed
-when redrawing with CTRL-L, try setting the "java_minlines" internal variable
-to a larger number: >
-	:let java_minlines = 50
+when redrawing with CTRL-L, try setting the "g:java_minlines" variable to
+a larger number: >
+	:let g:java_minlines = 50
 This will make the syntax synchronization start 50 lines before the first
 displayed line.  The default value is 10.  The disadvantage of using a larger
 number is that redrawing can become slow.
 
 
-JSON						*json.vim* *ft-json-syntax*
+JSON			*json.vim* *ft-json-syntax* *g:vim_json_conceal*
+					       *g:vim_json_warnings*
 
 The json syntax file provides syntax highlighting with conceal support by
 default. To disable concealment: >
@@ -2231,7 +2309,7 @@ By default mail.vim synchronises syntax to 100 lines before the first
 displayed line.  If you have a slow machine, and generally deal with emails
 with short headers, you can change this to a smaller value: >
 
-    :let mail_minlines = 30
+	:let mail_minlines = 30
 
 
 MAKE						*make.vim* *ft-make-syntax*
@@ -2242,6 +2320,16 @@ feature off by using: >
 
 	:let make_no_commands = 1
 
+Comments are also highlighted by default.  You can turn this off by using: >
+
+	:let make_no_comments = 1
+
+Microsoft Makefile handles variable expansion and comments differently
+(backslashes are not used for escape).  If you see any wrong highlights
+because of this, you can try this: >
+
+	:let make_microsoft = 1
+
 
 MAPLE						*maple.vim* *ft-maple-syntax*
 
@@ -2268,7 +2356,8 @@ $VIMRUNTIME/syntax/syntax.vim).
   mv_finance	 mv_logic	mv_powseries
 
 
-MARKDOWN						*ft-markdown-syntax*
+MARKDOWN			*ft-markdown-syntax* *g:markdown_minlines*
+		 *g:markdown_fenced_languages* *g:markdown_syntax_conceal*
 
 If you have long regions there might be wrong highlighting.  At the cost of
 slowing down displaying, you can have the engine look further back to sync on
@@ -2293,6 +2382,17 @@ have the following in your .vimrc: >
 
 	let filetype_m = "mma"
 
+MEDIAWIKI					*ft-mediawiki-syntax*
+
+By default, syntax highlighting includes basic HTML tags like style and
+headers |html.vim|. For strict Mediawiki syntax highlighting: >
+
+	let g:html_no_rendering = 1
+
+If HTML highlighting is desired, terminal-based text formatting such as bold
+and italic is possible by: >
+
+	let g:html_style_rendering = 1
 
 MODULA2					*modula2.vim* *ft-modula2-syntax*
 
@@ -2507,9 +2607,9 @@ PANDOC						*ft-pandoc-syntax*
 
 By default, markdown files will be detected as filetype "markdown".
 Alternatively, you may want them to be detected as filetype "pandoc" instead.
-To do so, set the following: >
+To do so, set the *g:filetype_md* var: >
 
-	:let g:markdown_md = 'pandoc'
+	:let g:filetype_md = 'pandoc'
 
 The pandoc syntax plugin uses |conceal| for pretty highlighting. Default is 1 >
 
@@ -3784,6 +3884,15 @@ are highlighted. To disable set it to zero in your .vimrc: >
 <
 The default value is 1.
 
+TYPST						    *ft-typst-syntax*
+
+						*g:typst_embedded_languages*
+Typst files can embed syntax highlighting for other languages by setting the
+|g:typst_embedded_languages| variable. This variable is a list of language
+names whose syntax definitions will be included in Typst files. Example: >
+
+    let g:typst_embedded_languages = ['python', 'r']
+
 VIM			*vim.vim*		*ft-vim-syntax*
 			*g:vimsyn_minlines*	*g:vimsyn_maxlines*
 There is a trade-off between more accurate syntax highlighting versus screen
@@ -5044,7 +5153,7 @@ matches, nextgroup, etc.  But there are a few differences:
   line (or group of continued lines).
 - When a match with a sync pattern is found, the rest of the line (or group of
   continued lines) is searched for another match.  The last match is used.
-  This is used when a line can contain both the start end the end of a region
+  This is used when a line can contain both the start and the end of a region
   (e.g., in a C-comment like /* this */, the last "*/" is used).
 
 There are two ways how a match with a sync pattern can be used: