tea-test-dao/Git/usr/share/vim/vim91/doc/syntax.txt

Hello Tea

*syntax.txt*	For Vim version 9.1.  Last change: 2023 Dec 27


		  VIM REFERENCE MANUAL	  by Bram Moolenaar


Syntax highlighting		*syntax* *syntax-highlighting* *coloring*

Syntax highlighting enables Vim to show parts of the text in another font or
color.	Those parts can be specific keywords or text matching a pattern.  Vim
doesn't parse the whole file (to keep it fast), so the highlighting has its
limitations.  Lexical highlighting might be a better name, but since everybody
calls it syntax highlighting we'll stick with that.

Vim supports syntax highlighting on all terminals.  But since most ordinary
terminals have very limited highlighting possibilities, it works best in the
GUI version, gvim.

In the User Manual:
|usr_06.txt| introduces syntax highlighting.
|usr_44.txt| introduces writing a syntax file.

1.  Quick start			|:syn-qstart|
2.  Syntax files		|:syn-files|
3.  Syntax loading procedure	|syntax-loading|
4.  Converting to HTML		|2html.vim|
5.  Syntax file remarks		|:syn-file-remarks|
6.  Defining a syntax		|:syn-define|
7.  :syntax arguments		|:syn-arguments|
8.  Syntax patterns		|:syn-pattern|
9.  Syntax clusters		|:syn-cluster|
10. Including syntax files	|:syn-include|
11. Synchronizing		|:syn-sync|
12. Listing syntax items	|:syntax|
13. Colorschemes		|color-schemes|
14. Highlight command		|:highlight|
15. Linking groups		|:highlight-link|
16. Cleaning up			|:syn-clear|
17. Highlighting tags		|tag-highlight|
18. Window-local syntax		|:ownsyntax|
19. Color xterms		|xterm-color|
20. When syntax is slow		|:syntime|

{Vi does not have any of these commands}

Syntax highlighting is not available when the |+syntax| feature has been
disabled at compile time.

==============================================================================
1. Quick start						*:syn-qstart*

						*:syn-enable* *:syntax-enable*
This command switches on syntax highlighting: >

	:syntax enable

What this command actually does is to execute the command >
	:source $VIMRUNTIME/syntax/syntax.vim

If the VIM environment variable is not set, Vim will try to find
the path in another way (see |$VIMRUNTIME|).  Usually this works just
fine.  If it doesn't, try setting the VIM environment variable to the
directory where the Vim stuff is located.  For example, if your syntax files
are in the "/usr/vim/vim82/syntax" directory, set $VIMRUNTIME to
"/usr/vim/vim82".  You must do this in the shell, before starting Vim.
This command also sources the |menu.vim| script when the GUI is running or
will start soon.  See |'go-M'| about avoiding that.

							*:syn-on* *:syntax-on*
The `:syntax enable` command will keep most of your current color settings.
This allows using `:highlight` commands to set your preferred colors before or
after using this command.  If you want Vim to overrule your settings with the
defaults, use: >
	:syntax on
<
					*:hi-normal* *:highlight-normal*
If you are running in the GUI, you can get white text on a black background
with: >
	:highlight Normal guibg=Black guifg=White
For a color terminal see |:hi-normal-cterm|.
For setting up your own colors syntax highlighting see |syncolor|.

NOTE: The syntax files on MS-Windows have lines that end in <CR><NL>.
The files for Unix end in <NL>.  This means you should use the right type of
file for your system.  Although on MS-Windows the right format is
automatically selected if the 'fileformats' option is not empty.

NOTE: When using reverse video ("gvim -fg white -bg black"), the default value
of 'background' will not be set until the GUI window is opened, which is after
reading the |gvimrc|.  This will cause the wrong default highlighting to be
used.  To set the default value of 'background' before switching on
highlighting, include the ":gui" command in the |gvimrc|: >

   :gui		" open window and set default for 'background'
   :syntax on	" start highlighting, use 'background' to set colors

NOTE: Using ":gui" in the |gvimrc| means that "gvim -f" won't start in the
foreground!  Use ":gui -f" then.

							*g:syntax_on*
You can toggle the syntax on/off with this command: >
   :if exists("g:syntax_on") | syntax off | else | syntax enable | endif

To put this into a mapping, you can use: >
   :map <F7> :if exists("g:syntax_on") <Bar>
	\   syntax off <Bar>
	\ else <Bar>
	\   syntax enable <Bar>
	\ endif <CR>
[using the |<>| notation, type this literally]

Details:
The ":syntax" commands are implemented by sourcing a file.  To see exactly how
this works, look in the file:
    command		file ~
    :syntax enable	$VIMRUNTIME/syntax/syntax.vim
    :syntax on		$VIMRUNTIME/syntax/syntax.vim
    :syntax manual	$VIMRUNTIME/syntax/manual.vim
    :syntax off		$VIMRUNTIME/syntax/nosyntax.vim
Also see |syntax-loading|.

NOTE: If displaying long lines is slow and switching off syntax highlighting
makes it fast, consider setting the 'synmaxcol' option to a lower value.

==============================================================================
2. Syntax files						*:syn-files*

The syntax and highlighting commands for one language are normally stored in
a syntax file.	The name convention is: "{name}.vim".  Where {name} is the
name of the language, or an abbreviation (to fit the name in 8.3 characters,
a requirement in case the file is used on a DOS filesystem).
Examples:
	c.vim		perl.vim	java.vim	html.vim
	cpp.vim		sh.vim		csh.vim

The syntax file can contain any Ex commands, just like a vimrc file.  But
the idea is that only commands for a specific language are included.  When a
language is a superset of another language, it may include the other one,
for example, the cpp.vim file could include the c.vim file: >
   :so $VIMRUNTIME/syntax/c.vim

The .vim files are normally loaded with an autocommand.  For example: >
   :au Syntax c	    runtime! syntax/c.vim
   :au Syntax cpp   runtime! syntax/cpp.vim
These commands are normally in the file $VIMRUNTIME/syntax/synload.vim.


MAKING YOUR OWN SYNTAX FILES				*mysyntaxfile*

When you create your own syntax files, and you want to have Vim use these
automatically with ":syntax enable", do this:

1. Create your user runtime directory.	You would normally use the first item
   of the 'runtimepath' option.  Example for Unix: >
	mkdir ~/.vim

2. Create a directory in there called "syntax".  For Unix: >
	mkdir ~/.vim/syntax

3. Write the Vim syntax file.  Or download one from the internet.  Then write
   it in your syntax directory.  For example, for the "mine" syntax: >
	:w ~/.vim/syntax/mine.vim

Now you can start using your syntax file manually: >
	:set syntax=mine
You don't have to exit Vim to use this.

If you also want Vim to detect the type of file, see |new-filetype|.

If you are setting up a system with many users and you don't want each user
to add the same syntax file, you can use another directory from 'runtimepath'.


ADDING TO AN EXISTING SYNTAX FILE		*mysyntaxfile-add*

If you are mostly satisfied with an existing syntax file, but would like to
add a few items or change the highlighting, follow these steps:

1. Create your user directory from 'runtimepath', see above.

2. Create a directory in there called "after/syntax".  For Unix: >
	mkdir ~/.vim/after
	mkdir ~/.vim/after/syntax

3. Write a Vim script that contains the commands you want to use.  For
   example, to change the colors for the C syntax: >
	highlight cComment ctermfg=Green guifg=Green

4. Write that file in the "after/syntax" directory.  Use the name of the
   syntax, with ".vim" added.  For our C syntax: >
	:w ~/.vim/after/syntax/c.vim

That's it.  The next time you edit a C file the Comment color will be
different.  You don't even have to restart Vim.

If you have multiple files, you can use the filetype as the directory name.
All the "*.vim" files in this directory will be used, for example:
	~/.vim/after/syntax/c/one.vim
	~/.vim/after/syntax/c/two.vim


REPLACING AN EXISTING SYNTAX FILE			*mysyntaxfile-replace*

If you don't like a distributed syntax file, or you have downloaded a new
version, follow the same steps as for |mysyntaxfile| above.  Just make sure
that you write the syntax file in a directory that is early in 'runtimepath'.
Vim will only load the first syntax file found, assuming that it sets
b:current_syntax.


NAMING CONVENTIONS		    *group-name* *{group-name}* *E669* *W18*

A syntax group name is to be used for syntax items that match the same kind of
thing.  These are then linked to a highlight group that specifies the color.
A syntax group name doesn't specify any color or attributes itself.

The name for a highlight or syntax group must consist of ASCII letters,
digits, underscores, dots, or hyphens.  As a regexp: "[a-zA-Z0-9_.-]*".
However, Vim does not give an error when using other characters.  The maximum
length of a group name is about 200 bytes.  *E1249*

To be able to allow each user to pick their favorite set of colors, there must
be preferred names for highlight groups that are common for many languages.
These are the suggested group names (if syntax highlighting works properly
you can see the actual color, except for "Ignore"):

	*Comment	any comment

	*Constant	any constant
	 String		a string constant: "this is a string"
	 Character	a character constant: 'c', '\n'
	 Number		a number constant: 234, 0xff
	 Boolean	a boolean constant: TRUE, false
	 Float		a floating point constant: 2.3e10

	*Identifier	any variable name
	 Function	function name (also: methods for classes)

	*Statement	any statement
	 Conditional	if, then, else, endif, switch, etc.
	 Repeat		for, do, while, etc.
	 Label		case, default, etc.
	 Operator	"sizeof", "+", "*", etc.
	 Keyword	any other keyword
	 Exception	try, catch, throw

	*PreProc	generic Preprocessor
	 Include	preprocessor #include
	 Define		preprocessor #define
	 Macro		same as Define
	 PreCondit	preprocessor #if, #else, #endif, etc.

	*Type		int, long, char, etc.
	 StorageClass	static, register, volatile, etc.
	 Structure	struct, union, enum, etc.
	 Typedef	A typedef

	*Special	any special symbol
	 SpecialChar	special character in a constant
	 Tag		you can use CTRL-] on this
	 Delimiter	character that needs attention
	 SpecialComment	special things inside a comment
	 Debug		debugging statements

	*Underlined	text that stands out, HTML links

	*Ignore		left blank, hidden  |hl-Ignore|

	*Error		any erroneous construct

	*Todo		anything that needs extra attention; mostly the
			keywords TODO FIXME and XXX

The names marked with * are the preferred groups; the others are minor groups.
For the preferred groups, the "syntax.vim" file contains default highlighting.
The minor groups are linked to the preferred groups, so they get the same
highlighting.  You can override these defaults by using ":highlight" commands
after sourcing the "syntax.vim" file.

Note that highlight group names are not case sensitive.  "String" and "string"
can be used for the same group.

The following names are reserved and cannot be used as a group name:
	NONE   ALL   ALLBUT   contains	 contained

							*hl-Ignore*
When using the Ignore group, you may also consider using the conceal
mechanism.  See |conceal|.

==============================================================================
3. Syntax loading procedure				*syntax-loading*

This explains the details that happen when the command ":syntax enable" is
issued.  When Vim initializes itself, it finds out where the runtime files are
located.  This is used here as the variable |$VIMRUNTIME|.

":syntax enable" and ":syntax on" do the following:

    Source $VIMRUNTIME/syntax/syntax.vim
    |
    +-	Clear out any old syntax by sourcing $VIMRUNTIME/syntax/nosyntax.vim
    |
    +-	Source first syntax/synload.vim in 'runtimepath'
    |	|
    |	+-  Setup the colors for syntax highlighting.  If a color scheme is
    |	|   defined it is loaded again with ":colors {name}".  Otherwise
    |	|   ":runtime! syntax/syncolor.vim" is used.  ":syntax on" overrules
    |	|   existing colors, ":syntax enable" only sets groups that weren't
    |	|   set yet.
    |	|
    |	+-  Set up syntax autocmds to load the appropriate syntax file when
    |	|   the 'syntax' option is set. *synload-1*
    |	|
    |	+-  Source the user's optional file, from the |mysyntaxfile| variable.
    |	    This is for backwards compatibility with Vim 5.x only. *synload-2*
    |
    +-	Do ":filetype on", which does ":runtime! filetype.vim".  It loads any
    |	filetype.vim files found.  It should always Source
    |	$VIMRUNTIME/filetype.vim, which does the following.
    |	|
    |	+-  Install autocmds based on suffix to set the 'filetype' option
    |	|   This is where the connection between file name and file type is
    |	|   made for known file types. *synload-3*
    |	|
    |	+-  Source the user's optional file, from the *myfiletypefile*
    |	|   variable.  This is for backwards compatibility with Vim 5.x only.
    |	|   *synload-4*
    |	|
    |	+-  Install one autocommand which sources scripts.vim when no file
    |	|   type was detected yet. *synload-5*
    |	|
    |	+-  Source $VIMRUNTIME/menu.vim, to setup the Syntax menu. |menu.vim|
    |
    +-	Install a FileType autocommand to set the 'syntax' option when a file
    |	type has been detected. *synload-6*
    |
    +-	Execute syntax autocommands to start syntax highlighting for each
	already loaded buffer.


Upon loading a file, Vim finds the relevant syntax file as follows:

    Loading the file triggers the BufReadPost autocommands.
    |
    +-	If there is a match with one of the autocommands from |synload-3|
    |	(known file types) or |synload-4| (user's file types), the 'filetype'
    |	option is set to the file type.
    |
    +-	The autocommand at |synload-5| is triggered.  If the file type was not
    |	found yet, then scripts.vim is searched for in 'runtimepath'.  This
    |	should always load $VIMRUNTIME/scripts.vim, which does the following.
    |	|
    |	+-  Source the user's optional file, from the *myscriptsfile*
    |	|   variable.  This is for backwards compatibility with Vim 5.x only.
    |	|
    |	+-  If the file type is still unknown, check the contents of the file,
    |	    again with checks like "getline(1) =~ pattern" as to whether the
    |	    file type can be recognized, and set 'filetype'.
    |
    +-	When the file type was determined and 'filetype' was set, this
    |	triggers the FileType autocommand |synload-6| above.  It sets
    |	'syntax' to the determined file type.
    |
    +-	When the 'syntax' option was set above, this triggers an autocommand
    |	from |synload-1| (and |synload-2|).  This find the main syntax file in
    |	'runtimepath', with this command:
    |		runtime! syntax/<name>.vim
    |
    +-	Any other user installed FileType or Syntax autocommands are
	triggered.  This can be used to change the highlighting for a specific
	syntax.

==============================================================================
4. Conversion to HTML				*2html.vim* *convert-to-HTML*

2html is not a syntax file itself, but a script that converts the current
window into HTML. Vim opens a new window in which it builds the HTML file.

After you save the resulting file, you can view it with any browser. The
colors should be exactly the same as you see them in Vim.  With
|g:html_line_ids| you can jump to specific lines by adding (for example) #L123
or #123 to the end of the URL in your browser's address bar. And with
|g:html_dynamic_folds| enabled, you can show or hide the text that is folded
in Vim.

You are not supposed to set the 'filetype' or 'syntax' option to "2html"!
Source the script to convert the current file: >

	:runtime! syntax/2html.vim
<
Many variables affect the output of 2html.vim; see below. Any of the on/off
options listed below can be enabled or disabled by setting them explicitly to
the desired value, or restored to their default by removing the variable using
|:unlet|.

Remarks:
- Some truly ancient browsers may not show the background colors.
- From most browsers you can also print the file (in color)!
- The latest TOhtml may actually work with older versions of Vim, but some
  features such as conceal support will not function, and the colors may be
  incorrect for an old Vim without GUI support compiled in.

Here is an example how to run the script over all .c and .h files from a
Unix shell: >
   for f in *.[ch]; do gvim -f +"syn on" +"run! syntax/2html.vim" +"wq" +"q" $f; done
<
					*g:html_start_line* *g:html_end_line*
To restrict the conversion to a range of lines, use a range with the |:TOhtml|
command below, or set "g:html_start_line" and "g:html_end_line" to the first
and last line to be converted.  Example, using the last set Visual area: >

	:let g:html_start_line = line("'<")
	:let g:html_end_line = line("'>")
	:runtime! syntax/2html.vim
<
							*:TOhtml*
:[range]TOhtml		The ":TOhtml" command is defined in a standard plugin.
			This command will source |2html.vim| for you. When a
			range is given, this command sets |g:html_start_line|
			and |g:html_end_line| to the start and end of the
			range, respectively. Default range is the entire
			buffer.

			If the current window is part of a |diff|, unless
			|g:html_diff_one_file| is set, :TOhtml will convert
			all windows which are part of the diff in the current
			tab and place them side-by-side in a <table> element
			in the generated HTML. With |g:html_line_ids| you can
			jump to lines in specific windows with (for example)
			#W1L42 for line 42 in the first diffed window, or
			#W3L87 for line 87 in the third.

			Examples: >

	:10,40TOhtml " convert lines 10-40 to html
	:'<,'>TOhtml " convert current/last visual selection
	:TOhtml      " convert entire buffer
<
							*g:html_diff_one_file*
Default: 0.
When 0, and using |:TOhtml| all windows involved in a |diff| in the current tab
page are converted to HTML and placed side-by-side in a <table> element. When
1, only the current buffer is converted.
Example: >

	let g:html_diff_one_file = 1
<
							 *g:html_whole_filler*
Default: 0.
When 0, if |g:html_diff_one_file| is 1, a sequence of more than 3 filler lines
is displayed as three lines with the middle line mentioning the total number
of inserted lines.
When 1, always display all inserted lines as if |g:html_diff_one_file| were
not set.
>
    :let g:html_whole_filler = 1
<
				     *TOhtml-performance* *g:html_no_progress*
Default: 0.
When 0, display a progress bar in the statusline for each major step in the
2html.vim conversion process.
When 1, do not display the progress bar. This offers a minor speed improvement
but you won't have any idea how much longer the conversion might take; for big
files it can take a long time!
Example: >

	let g:html_no_progress = 1
<
You can obtain better performance improvements by also instructing Vim to not
run interactively, so that too much time is not taken to redraw as the script
moves through the buffer, switches windows, and the like: >

  vim -E -s -c "let g:html_no_progress=1" -c "syntax on" -c "set ft=c" -c "runtime syntax/2html.vim" -cwqa myfile.c
<
Note that the -s flag prevents loading your .vimrc and any plugins, so you
need to explicitly source/enable anything that will affect the HTML
conversion. See |-E| and |-s-ex| for details. It is probably best to create a
script to replace all the -c commands and use it with the -u flag instead of
specifying each command separately.

				    *hl-TOhtmlProgress* *TOhtml-progress-color*
When displayed, the progress bar will show colored boxes along the statusline
as the HTML conversion proceeds. By default, the background color as the
current "DiffDelete" highlight group is used. If "DiffDelete" and "StatusLine"
have the same background color, TOhtml will automatically adjust the color to
differ. If you do not like the automatically selected colors, you can define
your own highlight colors for the progress bar. Example: >

	hi TOhtmlProgress guifg=#c0ffee ctermbg=7
<
							 *g:html_number_lines*
Default: Current 'number' setting.
When 0, buffer text is displayed in the generated HTML without line numbering.
When 1, a column of line numbers is added to the generated HTML with the same
highlighting as the line number column in Vim (|hl-LineNr|).
Force line numbers even if 'number' is not set: >
   :let g:html_number_lines = 1
Force to omit the line numbers: >
   :let g:html_number_lines = 0
Go back to the default to use 'number' by deleting the variable: >
   :unlet g:html_number_lines
<
							*g:html_line_ids*
Default: 1 if |g:html_number_lines| is set, 0 otherwise.
When 1, adds an HTML id attribute to each line number, or to an empty <span>
inserted for that purpose if no line numbers are shown. This ID attribute
takes the form of L123 for single-buffer HTML pages, or W2L123 for diff-view
pages, and is used to jump to a specific line (in a specific window of a diff
view). Javascript is inserted to open any closed dynamic folds
(|g:html_dynamic_folds|) containing the specified line before jumping. The
javascript also allows omitting the window ID in the url, and the leading L.
For example: >

	page.html#L123	jumps to line 123 in a single-buffer file
	page.html#123	does the same

	diff.html#W1L42	jumps to line 42 in the first window in a diff
	diff.html#42	does the same
<
							      *g:html_use_css*
Default: 1.
When 1, generate valid HTML 5 markup with CSS styling, supported in all modern
browsers and many old browsers.
When 0, generate <font> tags and similar outdated markup. This is not
recommended but it may work better in really old browsers, email clients,
forum posts, and similar situations where basic CSS support is unavailable.
Example: >
   :let g:html_use_css = 0
<
						       *g:html_ignore_conceal*
Default: 0.
When 0, concealed text is removed from the HTML and replaced with a character
from |:syn-cchar| or 'listchars' as appropriate, depending on the current
value of 'conceallevel'.
When 1, include all text from the buffer in the generated HTML, even if it is
|conceal|ed.

Either of the following commands will ensure that all text in the buffer is
included in the generated HTML (unless it is folded): >
   :let g:html_ignore_conceal = 1
   :setl conceallevel=0
<
						       *g:html_ignore_folding*
Default: 0.
When 0, text in a closed fold is replaced by the text shown for the fold in
Vim (|fold-foldtext|). See |g:html_dynamic_folds| if you also want to allow
the user to expand the fold as in Vim to see the text inside.
When 1, include all text from the buffer in the generated HTML; whether the
text is in a fold has no impact at all. |g:html_dynamic_folds| has no effect.

Either of these commands will ensure that all text in the buffer is included
in the generated HTML (unless it is concealed): >
   zR
   :let g:html_ignore_folding = 1
<
							*g:html_dynamic_folds*
Default: 0.
When 0, text in a closed fold is not included at all in the generated HTML.
When 1, generate javascript to open a fold and show the text within, just like
in Vim.

Setting this variable to 1 causes 2html.vim to always use CSS for styling,
regardless of what |g:html_use_css| is set to.

This variable is ignored when |g:html_ignore_folding| is set.
>
   :let g:html_dynamic_folds = 1
<
							*g:html_no_foldcolumn*
Default: 0.
When 0, if |g:html_dynamic_folds| is 1, generate a column of text similar to
Vim's foldcolumn (|fold-foldcolumn|) the user can click on to toggle folds
open or closed. The minimum width of the generated text column is the current
'foldcolumn' setting.
When 1, do not generate this column; instead, hovering the mouse cursor over
folded text will open the fold as if |g:html_hover_unfold| were set.
>
   :let g:html_no_foldcolumn = 1
<
				*TOhtml-uncopyable-text* *g:html_prevent_copy*
Default: Empty string.
This option prevents certain regions of the generated HTML from being copied,
when you select all text in document rendered in a browser and copy it. Useful
for allowing users to copy-paste only the source text even if a fold column or
line numbers are shown in the generated content. Specify regions to be
affected in this way as follows:
	f:	fold column
	n:	line numbers (also within fold text)
	t:	fold text
	d:	diff filler

Example, to make the fold column and line numbers uncopyable: >
	:let g:html_prevent_copy = "fn"
<
The method used to prevent copying in the generated page depends on the value
of |g:html_use_input_for_pc|.

						    *g:html_use_input_for_pc*
Default: "none"
If |g:html_prevent_copy| is non-empty, then:

When "all", read-only <input> elements are used in place of normal text for
uncopyable regions. In some browsers, especially older browsers, after
selecting an entire page and copying the selection, the <input> tags are not
pasted with the page text. If |g:html_no_invalid| is 0, the <input> tags have
invalid type; this works in more browsers, but the page will not validate.
Note: This method does NOT work in recent versions of Chrome and equivalent
browsers; the <input> tags get pasted with the text.

When "fallback" (default value), the same <input> elements are generated for
older browsers, but newer browsers (detected by CSS feature query) hide the
<input> elements and instead use generated content in an ::before pseudoelement
to display the uncopyable text. This method should work with the largest
number of browsers, both old and new.

When "none", the <input> elements are not generated at all. Only the
generated-content method is used. This means that old browsers, notably
Internet Explorer, will either copy the text intended not to be copyable, or
the non-copyable text may not appear at all. However, this is the most
standards-based method, and there will be much less markup.

							   *g:html_no_invalid*
Default: 0.
When 0, if |g:html_prevent_copy| is non-empty and |g:html_use_input_for_pc| is
not "none", an invalid attribute is intentionally inserted into the <input>
element for the uncopyable areas. This prevents pasting the <input> elements
in some applications. Specifically, some versions of Microsoft Word will not
paste the <input> elements if they contain this invalid attribute. When 1, no
invalid markup is inserted, and the generated page should validate. However,
<input> elements may be pasted into some applications and can be difficult to
remove afterward.

							 *g:html_hover_unfold*
Default: 0.
When 0, the only way to open a fold generated by 2html.vim with
|g:html_dynamic_folds| set, is to click on the generated fold column.
When 1, use CSS 2.0 to allow the user to open a fold by moving the mouse
cursor over the displayed fold text. This is useful to allow users with
disabled javascript to view the folded text.

Note that old browsers (notably Internet Explorer 6) will not support this
feature.  Browser-specific markup for IE6 is included to fall back to the
normal CSS1 styling so that the folds show up correctly for this browser, but
they will not be openable without a foldcolumn.
>
   :let g:html_hover_unfold = 1
<
							      *g:html_id_expr*
Default: ""
Dynamic folding and jumping to line IDs rely on unique IDs within the document
to work. If generated HTML is copied into a larger document, these IDs are no
longer guaranteed to be unique. Set g:html_id_expr to an expression Vim can
evaluate to get a unique string to append to each ID used in a given document,
so that the full IDs will be unique even when combined with other content in a
larger HTML document. Example, to append _ and the buffer number to each ID: >

	:let g:html_id_expr = '"_" .. bufnr("%")'
<
To append a string "_mystring" to the end of each ID: >

	:let g:html_id_expr = '"_mystring"'
<
Note: When converting a diff view to HTML, the expression will only be
evaluated for the first window in the diff, and the result used for all the
windows.

					  *TOhtml-wrap-text* *g:html_pre_wrap*
Default: Current 'wrap' setting.
When 0, if |g:html_no_pre| is 0 or unset, the text in the generated HTML does
not wrap at the edge of the browser window.
When 1, if |g:html_use_css| is 1, the CSS 2.0 "white-space:pre-wrap" value is
used, causing the text to wrap at whitespace at the edge of the browser
window.
Explicitly enable text wrapping: >
   :let g:html_pre_wrap = 1
Explicitly disable wrapping: >
   :let g:html_pre_wrap = 0
Go back to default, determine wrapping from 'wrap' setting: >
   :unlet g:html_pre_wrap
<
							       *g:html_no_pre*
Default: 0.
When 0, buffer text in the generated HTML is surrounded by <pre>...</pre>
tags. Series of whitespace is shown as in Vim without special markup, and tab
characters can be included literally (see |g:html_expand_tabs|).
When 1 (not recommended), the <pre> tags are omitted, and a plain <div> is
used instead. Whitespace is replaced by a series of &nbsp; character
references, and <br> is used to end each line. This is another way to allow
text in the generated HTML is wrap (see |g:html_pre_wrap|) which also works in
old browsers, but may cause noticeable differences between Vim's display and
the rendered page generated by 2html.vim.
>
   :let g:html_no_pre = 1
<
							       *g:html_no_doc*
Default: 0.
When 1 it doesn't generate a full HTML document with a DOCTYPE, <head>,
<body>, etc. If |g:html_use_css| is enabled (the default) you'll have to
define the CSS manually. The |g:html_dynamic_folds| and |g:html_line_ids|
settings (off by default) also insert some JavaScript.


							     *g:html_no_links*
Default: 0.
Don't generate <a> tags for text that looks like an URL.

							  *g:html_no_modeline*
Default: 0.
Don't generate a modeline disabling folding.

							  *g:html_expand_tabs*
Default: 0 if 'tabstop' is 8, 'expandtab' is 0, 'vartabstop' is not in use,
	       and no fold column or line numbers occur in the generated HTML;
	 1 otherwise.
When 1, <Tab> characters in the buffer text are replaced with an appropriate
number of space characters, or &nbsp; references if |g:html_no_pre| is 1.
When 0, if |g:html_no_pre| is 0 or unset, <Tab> characters in the buffer text
are included as-is in the generated HTML. This is useful for when you want to
allow copy and paste from a browser without losing the actual whitespace in
the source document. Note that this can easily break text alignment and
indentation in the HTML, unless set by default.

Force |2html.vim| to keep <Tab> characters: >
   :let g:html_expand_tabs = 0
<
Force tabs to be expanded: >
   :let g:html_expand_tabs = 1
<
				    *TOhtml-encoding-detect* *TOhtml-encoding*
It is highly recommended to set your desired encoding with
|g:html_use_encoding| for any content which will be placed on a web server.

If you do not specify an encoding, |2html.vim| uses the preferred IANA name
for the current value of 'fileencoding' if set, or 'encoding' if not.
'encoding' is always used for certain 'buftype' values. 'fileencoding' will be
set to match the chosen document encoding.

Automatic detection works for the encodings mentioned specifically by name in
|encoding-names|, but TOhtml will only automatically use those encodings with
wide browser support. However, you can override this to support specific
encodings that may not be automatically detected by default (see options
below). See http://www.iana.org/assignments/character-sets for the IANA names.

Note: By default all Unicode encodings are converted to UTF-8 with no BOM in
the generated HTML, as recommended by W3C:

	http://www.w3.org/International/questions/qa-choosing-encodings
	http://www.w3.org/International/questions/qa-byte-order-mark

							 *g:html_use_encoding*
Default: none, uses IANA name for current 'fileencoding' as above.
To overrule all automatic charset detection, set g:html_use_encoding to the
name of the charset to be used. It is recommended to set this variable to
something widely supported, like UTF-8, for anything you will be hosting on a
webserver: >
   :let g:html_use_encoding = "UTF-8"
You can also use this option to omit the line that specifies the charset
entirely, by setting g:html_use_encoding to an empty string (NOT recommended): >
   :let g:html_use_encoding = ""
To go back to the automatic mechanism, delete the |g:html_use_encoding|
variable: >
   :unlet g:html_use_encoding
<
						    *g:html_encoding_override*
Default: none, autoload/tohtml.vim contains default conversions for encodings
		mentioned by name at |encoding-names|.
This option allows |2html.vim| to detect the correct 'fileencoding' when you
specify an encoding with |g:html_use_encoding| which is not in the default
list of conversions.

This is a dictionary of charset-encoding pairs that will replace existing
pairs automatically detected by TOhtml, or supplement with new pairs.

Detect the HTML charset "windows-1252" as the encoding "8bit-cp1252": >
   :let g:html_encoding_override = {'windows-1252': '8bit-cp1252'}
<
						     *g:html_charset_override*
Default: none, autoload/tohtml.vim contains default conversions for encodings
		mentioned by name at |encoding-names| and which have wide
		browser support.
This option allows |2html.vim| to detect the HTML charset for any
'fileencoding' or 'encoding' which is not detected automatically. You can also
use it to override specific existing encoding-charset pairs. For example,
TOhtml will by default use UTF-8 for all Unicode/UCS encodings. To use UTF-16
and UTF-32 instead, use: >
   :let g:html_charset_override = {'ucs-4': 'UTF-32', 'utf-16': 'UTF-16'}

Note that documents encoded in either UTF-32 or UTF-16 have known
compatibility problems with some major browsers.

								 *g:html_font*
Default: "monospace"
You can specify the font or fonts used in the converted document using
g:html_font. If this option is set to a string, then the value will be
surrounded with single quotes. If this option is set to a list then each list
item is surrounded by single quotes and the list is joined with commas. Either
way, "monospace" is added as the fallback generic family name and the entire
result used as the font family (using CSS) or font face (if not using CSS).
Examples: >

   " font-family: 'Consolas', monospace;
   :let g:html_font = "Consolas"

   " font-family: 'DejaVu Sans Mono', 'Consolas', monospace;
   :let g:html_font = ["DejaVu Sans Mono", "Consolas"]
<
			*convert-to-XML* *convert-to-XHTML* *g:html_use_xhtml*
Default: 0.
When 0, generate standard HTML 4.01 (strict when possible).
When 1, generate XHTML 1.0 instead (XML compliant HTML).
>
    :let g:html_use_xhtml = 1
<
==============================================================================
5. Syntax file remarks					*:syn-file-remarks*

						*b:current_syntax-variable*
Vim stores the name of the syntax that has been loaded in the
"b:current_syntax" variable.  You can use this if you want to load other
settings, depending on which syntax is active.	Example: >
   :au BufReadPost * if b:current_syntax == "csh"
   :au BufReadPost *   do-some-things
   :au BufReadPost * endif



ABEL						*abel.vim* *ft-abel-syntax*

ABEL highlighting provides some user-defined options.  To enable them, assign
any value to the respective variable.  Example: >
	:let abel_obsolete_ok=1
To disable them use ":unlet".  Example: >
	:unlet abel_obsolete_ok

Variable			Highlight ~
abel_obsolete_ok		obsolete keywords are statements, not errors
abel_cpp_comments_illegal	do not interpret '//' as inline comment leader


ADA

See |ft-ada-syntax|


ANT						*ant.vim* *ft-ant-syntax*

The ant syntax file provides syntax highlighting for javascript and python
by default.  Syntax highlighting for other script languages can be installed
by the function AntSyntaxScript(), which takes the tag name as first argument
and the script syntax file name as second argument.  Example: >

	:call AntSyntaxScript('perl', 'perl.vim')

will install syntax perl highlighting for the following ant code >

	<script language = 'perl'><![CDATA[
	    # everything inside is highlighted as perl
	]]></script>

See |mysyntaxfile-add| for installing script languages permanently.


APACHE						*apache.vim* *ft-apache-syntax*

The apache syntax file provides syntax highlighting for Apache HTTP server
version 2.2.3.


		*asm.vim* *asmh8300.vim* *nasm.vim* *masm.vim* *asm68k*
ASSEMBLY	*ft-asm-syntax* *ft-asmh8300-syntax* *ft-nasm-syntax*
		*ft-masm-syntax* *ft-asm68k-syntax* *fasm.vim*

Files matching "*.i" could be Progress or Assembly.  If the automatic detection
doesn't work for you, or you don't edit Progress at all, use this in your
startup vimrc: >
   :let filetype_i = "asm"
Replace "asm" with the type of assembly you use.

There are many types of assembly languages that all use the same file name
extensions.  Therefore you will have to select the type yourself, or add a
line in the assembly file that Vim will recognize.  Currently these syntax
files are included:
	asm		GNU assembly (the default)
	asm68k		Motorola 680x0 assembly
	asmh8300	Hitachi H-8300 version of GNU assembly
	ia64		Intel Itanium 64
	fasm		Flat assembly (http://flatassembler.net)
	masm		Microsoft assembly (probably works for any 80x86)
	nasm		Netwide assembly
	tasm		Turbo Assembly (with opcodes 80x86 up to Pentium, and
			MMX)
	pic		PIC assembly (currently for PIC16F84)

The most flexible is to add a line in your assembly file containing: >
	asmsyntax=nasm
Replace "nasm" with the name of the real assembly syntax.  This line must be
one of the first five lines in the file.  No non-white text must be
immediately before or after this text.  Note that specifying asmsyntax=foo is
equivalent to setting ft=foo in a |modeline|, and that in case of a conflict
between the two settings the one from the modeline will take precedence (in
particular, if you have ft=asm in the modeline, you will get the GNU syntax
highlighting regardless of what is specified as asmsyntax).

The syntax type can always be overruled for a specific buffer by setting the
b:asmsyntax variable: >
	:let b:asmsyntax = "nasm"

If b:asmsyntax is not set, either automatically or by hand, then the value of
the global variable asmsyntax is used.	This can be seen as a default assembly
language: >
	:let asmsyntax = "nasm"

As a last resort, if nothing is defined, the "asm" syntax is used.


Netwide assembler (nasm.vim) optional highlighting ~

To enable a feature: >
	:let   {variable}=1|set syntax=nasm
To disable a feature: >
	:unlet {variable}  |set syntax=nasm

Variable		Highlight ~
nasm_loose_syntax	unofficial parser allowed syntax not as Error
			  (parser dependent; not recommended)
nasm_ctx_outside_macro	contexts outside macro not as Error
nasm_no_warn		potentially risky syntax not as ToDo


ASPPERL and ASPVBS			*ft-aspperl-syntax* *ft-aspvbs-syntax*

*.asp and *.asa files could be either Perl or Visual Basic script.  Since it's
hard to detect this you can set two global variables to tell Vim what you are
using.	For Perl script use: >
	:let g:filetype_asa = "aspperl"
	:let g:filetype_asp = "aspperl"
For Visual Basic use: >
	:let g:filetype_asa = "aspvbs"
	:let g:filetype_asp = "aspvbs"


BAAN						    *baan.vim* *baan-syntax*

The baan.vim gives syntax support for BaanC of release BaanIV up to SSA ERP LN
for both 3 GL and 4 GL programming. Large number of standard defines/constants
are supported.

Some special violation of coding standards will be signalled when one specify
in ones |.vimrc|: >
	let baan_code_stds=1

*baan-folding*

Syntax folding can be enabled at various levels through the variables
mentioned below (Set those in your |.vimrc|). The more complex folding on
source blocks and SQL can be CPU intensive.

To allow any folding and enable folding at function level use: >
	let baan_fold=1
Folding can be enabled at source block level as if, while, for ,... The
indentation preceding the begin/end keywords has to match (spaces are not
considered equal to a tab). >
	let baan_fold_block=1
Folding can be enabled for embedded SQL blocks as SELECT, SELECTDO,
SELECTEMPTY, ... The indentation preceding the begin/end keywords has to
match (spaces are not considered equal to a tab). >
	let baan_fold_sql=1
Note: Block folding can result in many small folds. It is suggested to |:set|
the options 'foldminlines' and 'foldnestmax' in |.vimrc| or use |:setlocal| in
.../after/syntax/baan.vim (see |after-directory|). Eg: >
	set foldminlines=5
	set foldnestmax=6


BASIC			*basic.vim* *vb.vim* *ft-basic-syntax* *ft-vb-syntax*

Both Visual Basic and "normal" BASIC use the extension ".bas".	To detect
which one should be used, Vim checks for the string "VB_Name" in the first
five lines of the file.  If it is not found, filetype will be "basic",
otherwise "vb".  Files with the ".frm" extension will always be seen as Visual
Basic.

If the automatic detection doesn't work for you or you only edit, for
example, FreeBASIC files, use this in your startup vimrc: >
   :let filetype_bas = "freebasic"


C							*c.vim* *ft-c-syntax*

A few things in C highlighting are optional.  To enable them assign any value
(including zero) to the respective variable.  Example: >
	:let c_comment_strings = 1
	:let c_no_bracket_error = 0
To disable them use `:unlet`.  Example: >
	:unlet c_comment_strings
Setting the value to zero doesn't work!

An alternative is to switch to the C++ highlighting: >
	:set filetype=cpp

Variable		Highlight ~
*c_gnu*			GNU gcc specific items
*c_comment_strings*	strings and numbers inside a comment
*c_space_errors*	trailing white space and spaces before a <Tab>
*c_no_trail_space_error*   ... but no trailing spaces
*c_no_tab_space_error*	 ... but no spaces before a <Tab>
*c_no_bracket_error*	don't highlight {}; inside [] as errors
*c_no_curly_error*	don't highlight {}; inside [] and () as errors;
			 ...except { and } in first column
			Default is to highlight them, otherwise you
			can't spot a missing ")".
*c_curly_error*		highlight a missing } by finding all pairs; this
			forces syncing from the start of the file, can be slow
*c_no_ansi*		don't do standard ANSI types and constants
*c_ansi_typedefs*	 ... but do standard ANSI types
*c_ansi_constants*	 ... but do standard ANSI constants
*c_no_utf*		don't highlight \u and \U in strings
*c_syntax_for_h*	for *.h files use C syntax instead of C++ and use objc
			syntax instead of objcpp
*c_no_if0*		don't highlight "#if 0" blocks as comments
*c_no_cformat*		don't highlight %-formats in strings
*c_no_c99*		don't highlight C99 standard items
*c_no_c11*		don't highlight C11 standard items
*c_no_bsd*		don't highlight BSD specific types

When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will
become a fold.  If you don't want comments to become a fold use: >
	:let c_no_comment_fold = 1
"#if 0" blocks are also folded, unless: >
	:let c_no_if0_fold = 1

If you notice highlighting errors while scrolling backwards, which are fixed
when redrawing with CTRL-L, try setting the "c_minlines" internal variable
to a larger number: >
	:let c_minlines = 100
This will make the syntax synchronization start 100 lines before the first
displayed line.  The default value is 50 (15 when c_no_if0 is set).  The
disadvantage of using a larger number is that redrawing can become slow.

When using the "#if 0" / "#endif" comment highlighting, notice that this only
works when the "#if 0" is within "c_minlines" from the top of the window.  If
you have a long "#if 0" construct it will not be highlighted correctly.

To match extra items in comments, use the cCommentGroup cluster.
Example: >
   :au Syntax c call MyCadd()
   :function MyCadd()
   :  syn keyword cMyItem contained Ni
   :  syn cluster cCommentGroup add=cMyItem
   :  hi link cMyItem Title
   :endfun

ANSI constants will be highlighted with the "cConstant" group.	This includes
"NULL", "SIG_IGN" and others.  But not "TRUE", for example, because this is
not in the ANSI standard.  If you find this confusing, remove the cConstant
highlighting: >
	:hi link cConstant NONE

If you see '{' and '}' highlighted as an error where they are OK, reset the
highlighting for cErrInParen and cErrInBracket.

If you want to use folding in your C files, you can add these lines in a file
in the "after" directory in 'runtimepath'.  For Unix this would be
~/.vim/after/syntax/c.vim. >
    syn sync fromstart
    set foldmethod=syntax

CH						*ch.vim* *ft-ch-syntax*

C/C++ interpreter.  Ch has similar syntax highlighting to C and builds upon
the C syntax file.  See |c.vim| for all the settings that are available for C.

By setting a variable you can tell Vim to use Ch syntax for *.h files, instead
of C or C++: >
	:let ch_syntax_for_h = 1


CHILL						*chill.vim* *ft-chill-syntax*

Chill syntax highlighting is similar to C.  See |c.vim| for all the settings
that are available.  Additionally there is:

chill_space_errors	like c_space_errors
chill_comment_string	like c_comment_strings
chill_minlines		like c_minlines


CHANGELOG				*changelog.vim* *ft-changelog-syntax*

ChangeLog supports highlighting spaces at the start of a line.
If you do not like this, add following line to your .vimrc: >
	let g:changelog_spacing_errors = 0
This works the next time you edit a changelog file.  You can also use
"b:changelog_spacing_errors" to set this per buffer (before loading the syntax
file).

You can change the highlighting used, e.g., to flag the spaces as an error: >
	:hi link ChangelogError Error
Or to avoid the highlighting: >
	:hi link ChangelogError NONE
This works immediately.


CLOJURE							*ft-clojure-syntax*

						*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"]
	    \ }
<
Refer to the Clojure syntax script for valid syntax group names.

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 [])`


							*g:clojure_fold*

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


						*g:clojure_discard_macro*

Set this variable to `1` to enable basic highlighting of Clojure's "discard
reader macro".
>
	#_(defn foo [x]
	    (println x))
<
Note that this option will not correctly highlight stacked discard macros
(e.g. `#_#_`).


COBOL						*cobol.vim* *ft-cobol-syntax*

COBOL highlighting has different needs for legacy code than it does for fresh
development.  This is due to differences in what is being done (maintenance
versus development) and other factors.	To enable legacy code highlighting,
add this line to your .vimrc: >
	:let cobol_legacy_code = 1
To disable it again, use this: >
	:unlet cobol_legacy_code


COLD FUSION			*coldfusion.vim* *ft-coldfusion-syntax*

The ColdFusion has its own version of HTML comments.  To turn on ColdFusion
comment highlighting, add the following line to your startup file: >

	:let html_wrong_comments = 1

The ColdFusion syntax file is based on the HTML syntax file.


CPP						*cpp.vim* *ft-cpp-syntax*

Most things are the same as |ft-c-syntax|.

Variable		Highlight ~
cpp_no_cpp11		don't highlight C++11 standard items
cpp_no_cpp14		don't highlight C++14 standard items
cpp_no_cpp17		don't highlight C++17 standard items
cpp_no_cpp20		don't highlight C++20 standard items


CSH						*csh.vim* *ft-csh-syntax*

This covers the shell named "csh".  Note that on some systems tcsh is actually
used.

Detecting whether a file is csh or tcsh is notoriously hard.  Some systems
symlink /bin/csh to /bin/tcsh, making it almost impossible to distinguish
between csh and tcsh.  In case VIM guesses wrong you can set the
"filetype_csh" variable.  For using csh:  *g:filetype_csh*
>
	:let g:filetype_csh = "csh"

For using tcsh: >

	:let g:filetype_csh = "tcsh"

Any script with a tcsh extension or a standard tcsh filename (.tcshrc,
tcsh.tcshrc, tcsh.login) will have filetype tcsh.  All other tcsh/csh scripts
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.


CYNLIB						*cynlib.vim* *ft-cynlib-syntax*

Cynlib files are C++ files that use the Cynlib class library to enable
hardware modelling and simulation using C++.  Typically Cynlib files have a .cc
or a .cpp extension, which makes it very difficult to distinguish them from a
normal C++ file.  Thus, to enable Cynlib highlighting for .cc files, add this
line to your .vimrc file: >

	:let cynlib_cyntax_for_cc=1

Similarly for cpp files (this extension is only usually used in Windows) >

	:let cynlib_cyntax_for_cpp=1

To disable these again, use this: >

	:unlet cynlib_cyntax_for_cc
	:unlet cynlib_cyntax_for_cpp
<

CWEB						*cweb.vim* *ft-cweb-syntax*

Files matching "*.w" could be Progress or cweb.  If the automatic detection
doesn't work for you, or you don't edit Progress at all, use this in your
startup vimrc: >
   :let filetype_w = "cweb"


DART						*dart.vim* *ft-dart-syntax*

Dart is an object-oriented, typed, class defined, garbage collected language
used for developing mobile, desktop, web, and back-end applications.  Dart uses
a C-like syntax derived from C, Java, and JavaScript, with features adopted
from Smalltalk, Python, Ruby, and others.

More information about the language and its development environment at the
official Dart language website at https://dart.dev

dart.vim syntax detects and highlights Dart statements, reserved words,
type declarations, storage classes, conditionals, loops, interpolated values,
and comments.  There is no support idioms from Flutter or any other Dart
framework.

Changes, fix