syntax.txt: Update Vim 8.2.3687

Author: tsuyoshicho

en/syntax.txt

@@ -1,4 +1,4 @@
-*syntax.txt*	For Vim version 8.2.  Last change: 2021 Aug 16
+*syntax.txt*	For Vim version 8.2.  Last change: 2021 Nov 20
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -1081,33 +1081,47 @@ This works immediately.
 
 CLOJURE							*ft-clojure-syntax*
 
-The default syntax groups can be augmented through the
-*g:clojure_syntax_keywords* and *b:clojure_syntax_keywords* variables. The
-value should be a |Dictionary| of syntax group names to a |List| of custom
-identifiers:
+						*g:clojure_syntax_keywords*
+
+Syntax highlighting of public vars in "clojure.core" is provided by default,
+but additional symbols can be highlighted by adding them to the
+|g:clojure_syntax_keywords| variable.  The value should be a |Dictionary| of
+syntax group names, each containing a |List| of identifiers.
 >
 	let g:clojure_syntax_keywords = {
-	    \ 'clojureMacro': ["defproject", "defcustom"],
-	    \ 'clojureFunc': ["string/join", "string/replace"]
+	    \   'clojureMacro': ["defproject", "defcustom"],
+	    \   'clojureFunc': ["string/join", "string/replace"]
 	    \ }
 <
 Refer to the Clojure syntax script for valid syntax group names.
 
-If the |buffer-variable| *b:clojure_syntax_without_core_keywords* is set, only
-language constants and special forms are matched.
+There is also *b:clojure_syntax_keywords* which is a buffer-local variant of
+this variable intended for use by plugin authors to highlight symbols
+dynamically.
+
+By setting the *b:clojure_syntax_without_core_keywords* variable, vars from
+"clojure.core" will not be highlighted by default.  This is useful for
+namespaces that have set `(:refer-clojure :only [])`
+
 
-Setting *g:clojure_fold* enables folding Clojure code via the syntax engine.
-Any list, vector, or map that extends over more than one line can be folded
-using the standard Vim |fold-commands|.
+							*g:clojure_fold*
 
-Please note that this option does not work with scripts that redefine the
-bracket syntax regions, such as rainbow-parentheses plugins.
+Setting |g:clojure_fold| to `1` will enable the folding of Clojure code.  Any
+list, vector or map that extends over more than one line can be folded using
+the standard Vim |fold-commands|.
 
-This option is off by default.
+
+						*g:clojure_discard_macro*
+
+Set this variable to `1` to enable basic highlighting of Clojure's "discard
+reader macro".
 >
-	" Default
-	let g:clojure_fold = 0
+	#_(defn foo [x]
+	    (println x))
 <
+Note that this option will not correctly highlight stacked discard macros
+(e.g. `#_#_`).
+
 
 COBOL						*cobol.vim* *ft-cobol-syntax*
 
@@ -1519,6 +1533,14 @@ gvim display.  Here, statements are colored LightYellow instead of Yellow, and
 conditionals are LightBlue for better distinction.
 
 
+FORTH						*forth.vim* *ft-forth-syntax*
+
+Files matching "*.fs" could be F# or Forth.  If the automatic detection
+doesn't work for you, or you don't edit F# at all, use this in your
+startup vimrc: >
+   :let filetype_fs = "forth"
+
+
 FORTRAN					*fortran.vim* *ft-fortran-syntax*
 
 Default highlighting and dialect ~
@@ -1673,16 +1695,6 @@ as Fvwm2 configuration files, add the following: >
   :au! BufNewFile,BufRead /etc/X11/fvwm2/*  let b:fvwm_version = 2 |
 					 \ set filetype=fvwm
 
-If you'd like Vim to highlight all valid color names, tell it where to
-find the color database (rgb.txt) on your system.  Do this by setting
-"rgb_file" to its location.  Assuming your color database is located
-in /usr/X11/lib/X11/, you should add the line >
-
-	:let rgb_file = "/usr/X11/lib/X11/rgb.txt"
-
-to your .vimrc file.
-
-
 GSP						*gsp.vim* *ft-gsp-syntax*
 
 The default coloring style for GSP pages is defined by |html.vim|, and
@@ -4830,16 +4842,28 @@ in their own color.
 			Doesn't work recursively, thus you can't use
 			":colorscheme" in a color scheme script.
 
-			To customize a color scheme use another name, e.g.
+			You have two options for customizing a color scheme.
+			For changing the appearance of specific colors, you
+			can redefine a color name before loading the scheme.
+			The desert scheme uses the khaki color for the cursor.
+			To use a darker variation of the same color: >
+
+				let v:colornames['khaki'] = '#bdb76b'
+				colorscheme desert
+<
+			For further customization, such as changing
+			|:highlight-link| associations, use another name, e.g.
 			"~/.vim/colors/mine.vim", and use `:runtime` to load
 			the original color scheme: >
 				runtime colors/evening.vim
 				hi Statement ctermfg=Blue guifg=Blue
 
-<			Before the color scheme will be loaded the
-			|ColorSchemePre| autocommand event is triggered.
-			After the color scheme has been loaded the
-			|ColorScheme| autocommand event is triggered.
+<			Before the color scheme will be loaded all default
+			color list scripts (`colors/lists/default.vim`) will
+			be executed and then the |ColorSchemePre| autocommand
+			event is triggered.  After the color scheme has been
+			loaded the |ColorScheme| autocommand event is
+			triggered.
 			For info about writing a color scheme file: >
 				:edit $VIMRUNTIME/colors/README.txt
 
@@ -4849,6 +4873,7 @@ in their own color.
 :hi[ghlight] {group-name}
 			List one highlight group.
 
+						*highlight-clear*
 :hi[ghlight] clear	Reset all highlighting to the defaults.  Removes all
 			highlighting for groups added by the user!
 			Uses the current value of 'background' to decide which
@@ -4862,7 +4887,9 @@ in their own color.
 
 :hi[ghlight] [default] {group-name} {key}={arg} ..
 			Add a highlight group, or change the highlighting for
-			an existing group.
+			an existing group. If a given color name is not
+			recognized, each `colors/lists/default.vim` found on
+			|'runtimepath'| will be loaded.
 			See |highlight-args| for the {key}={arg} arguments.
 			See |:highlight-default| for the optional [default]
 			argument.
@@ -5143,8 +5170,35 @@ guisp={color-name}					*highlight-guisp*
 		"gg"	is the Green value
 		"bb"	is the Blue value
 	All values are hexadecimal, range from "00" to "ff".  Examples: >
-  :highlight Comment guifg=#11f0c3 guibg=#ff00ff
+            :highlight Comment guifg=#11f0c3 guibg=#ff00ff
+<
+	If you are authoring a color scheme and use the same hexademical value
+	repeatedly, you can define a name for it in |v:colornames|. For
+	example: >
+
+	    # provide a default value for this color but allow the user to
+	    # override it.
+	    :call extend(v:colornames, {'alt_turquoise': '#11f0c3'}, 'keep')
+	    :highlight Comment guifg=alt_turquoise guibg=magenta
 <
+	If you are using a color scheme that relies on named colors and you
+	would like to adjust the precise appearance of those colors, you can
+	do so by overriding the values in |v:colornames| prior to loading the
+	scheme: >
+
+	    let v:colornames['alt_turquoise'] = '#22f0d3'
+	    colorscheme alt
+<
+	If you want to develop a color list that can be relied on by others,
+	it is best to prefix your color names. By convention these color lists
+	are placed in the colors/lists directory. You can see an example in
+	'$VIMRUNTIME/colors/lists/csscolors.vim'. This list would be sourced
+	by a color scheme using: >
+
+	    :runtime colors/lists/csscolors.vim
+	    :highlight Comment guifg=css_turquoise
+<
+
 					*highlight-groups* *highlight-default*
 These are the default highlighting groups.  These groups are used by the
 'highlight' option default.  Note that the highlighting depends on the value
@@ -5205,6 +5259,10 @@ LineNrBelow	Line number for when the 'relativenumber'
 							*hl-CursorLineNr*
 CursorLineNr	Like LineNr when 'cursorline' is set and 'cursorlineopt'
 		contains "number" or is "both", for the cursor line.
+							*hl-CursorLineSign*
+CursorLineSign	Like SignColumn when 'cursorline' is set for the cursor line.
+							*hl-CursorLineFold*
+CursorLineFold	Like FoldColumn when 'cursorline' is set for the cursor line.
 							*hl-MatchParen*
 MatchParen	The character under the cursor or just before it, if it
 		is a paired bracket, and its match. |pi_paren.txt|
@@ -5431,7 +5489,7 @@ For Unix you can use the file ~/.vim/after/syntax/syncolor.vim.  Example: >
 	else
 	  highlight comment ctermfg=green guifg=green
 	endif
-
+<
 								*E679*
 Do make sure this syncolor.vim script does not use a "syntax on", set the
 'background' option or uses a "colorscheme" command, because it results in an
@@ -5444,11 +5502,11 @@ depends on the color scheme file.  See |:colorscheme|.
 							*syntax_cmd*
 The "syntax_cmd" variable is set to one of these values when the
 syntax/syncolor.vim files are loaded:
-   "on"		":syntax on" command.  Highlight colors are overruled but
+   "on"		`:syntax on` command.  Highlight colors are overruled but
 		links are kept
-   "enable"	":syntax enable" command.  Only define colors for groups that
-		don't have highlighting yet.  Use ":syntax default".
-   "reset"	":syntax reset" command or loading a color scheme.  Define all
+   "enable"	`:syntax enable` command.  Only define colors for groups that
+		don't have highlighting yet.  Use `:highlight default` .
+   "reset"	`:syntax reset` command or loading a color scheme.  Define all
 		the colors.
    "skip"	Don't define colors.  Used to skip the default settings when a
 		syncolor.vim file earlier in 'runtimepath' has already set