syntax.txt

MSYS在windows下模拟了一个类unix的终端

*syntax.txt*    For Vim version 5.8.  Last change: 2001 May 15


		  VIM REFERENCE MANUAL    by Bram Moolenaar


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

Syntax highlighting enables the possibility 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 everybody calls it syntax highlighting, so 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.

1.  Quick start			|:syn-qstart|
2.  Syntax files		|:syn-files|
3.  Syntax loading procedure	|syntax-loading|
4.  Syntax file remarks		|:syn-file-remarks|
5.  Defining a syntax		|:syn-define|
6.  :syntax arguments		|:syn-arguments|
7.  Syntax patterns		|:syn-pattern|
8.  Syntax clusters		|:syn-cluster|
9.  Including syntax files	|:syn-include|
10. Synchronizing		|:syn-sync|
11. Listing syntax items	|:syntax|
12. Highlight command		|:highlight|
13. Linking groups		|:highlight-link|
14. Cleaning up			|:syn-clear|
15. Highlighting tags		|tag-highlight|
16. Color xterms		|xterm-color|

{Vi does not have any of these commands}

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

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

							*:syn-on*
For a large number of common languages syntax files have been included.  To
start using them, type this command:
>  :syntax on

This will enable automatic syntax highlighting.  The type of highlighting will
be selected using the file name extension, and sometimes using the first line
of the file.

Include this command in your .vimrc if you always want syntax highlighting, or
put it in your .gvimrc if you only want it in the GUI.  If you don't want it
for B&W terminals, but you do want it for color terminals, put this in your
.vimrc:
>  if &t_Co > 1
>    syntax on
>  endif

What this command actually does, is executing 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|).  Normally this will work 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/vim50/syntax" directory, set $VIMRUNTIME to
"/usr/vim/vim50".  You must do this in the shell, before starting Vim.

							*:syn-default-override*
You can override the default highlight settings, by issuing ":highlight"
commands after sourcing "syntax.vim".  For example:
>  syntax on
>  highlight Constant gui=NONE guibg=grey95

This will change the GUI highlighting for the "Constant" group.  See
|:highlight| about how to specify highlighting attributes.

							*:hi-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|.

If you have a black background, use these commands to get better colors (see
'background'):
>  set background=dark
>  syntax on

NOTE: The syntax files on MS-DOS and 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-DOS and 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.


To switch off the syntax highlighting:			*:syn-off*
>  :syntax off
This will completely disable syntax highlighting and remove it immediately for
all buffers.

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

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


To make syntax highlighting work only in selected buffers:	*:syn-manual*
>   :syntax manual
This will enable the syntax highlighting, but not switch it on automatically
when starting to edit a buffer.  This is because the FileType autocommands are
not used to select a syntax.

Now you can still switch on syntax highlighting for a buffer by setting the
'syntax' option.  For example, to switch on fortran highlighting:
>   :set syntax=fortran
This can also be done with a |modeline|, so that files that include a modeline
that sets the 'syntax' option will be highlighted.  For example, this line can
be used in a Makefile:
>   # vim: syntax=make

							*syntax-printing*
If you want to print your colored text, you will have to convert it to HTML
first, and then print it from a browser.  See |2html.vim|.


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

==============================================================================
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,
which is always done, in case the file will be 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	    source $VIMRUNTIME/syntax/c.vim
>  :au Syntax cpp   source $VIMRUNTIME/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 these
automatically used with ":syntax on", do this:

1. Create a file that contains the autocommands to load your syntax files when
   the right file type is detected.  To prevent loading two syntax files (when
   the file type is used twice), first delete other autocommands for the same
   file type.  You can also include ":highlight" commands in this file, which
   override the normal highlighting (because the file is sourced after setting
   the normal highlighting).  Example:
>    au! Syntax dosbatch    so ~/vim/batch.vim
>    au! Syntax mine	    so ~/vim/mine.vim
>    highlight Comment gui=bold
   Let's assume you write this file in "~/vim/mysyntax.vim".

   Note that when you introduce a new file type, this must first be detected.
   See |myfiletypefile|.

							*mysyntaxfile-file*
2. In your .vimrc, set the "mysyntaxfile" variable to the file you just
   created.  For example:
>    let mysyntaxfile = "~/vim/mysyntax.vim"
   Put this before ":syntax on"!

If you want to use a new file type, see |new-filetype|.

Note that "mysyntaxfile" is sourced AFTER defining the default autocommands
for the supplied syntax files, so that you can override these autocommands
with your own.

If you are setting up a system with many users, and you don't want each user
to add the same syntax file, consider creating a vimrc file that is used for
all everybody.  See |system-vimrc|.


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. In your vimrc file, set "mysyntaxfile":
>	let mysyntaxfile = "/home/someone/vim/mysyntax.vim"

2. In the "mysyntax.vim" file, put an autocommand to source your extra syntax
   items:
>	" FooBar language
>	:autocmd Syntax foobar		source /home/someone/vim/foobar.vim
   Check: if you do ":autocmd Syntax foobar" you wil see both the original
   syntax file and the one you just added:
>	Syntax
>	   foobar	so $VIMRUNTIME/syntax/foobar.vim
>	   foobar	source /home/someone/vim/foobar.vim

3. In the additional language file, put the items you want to add:
>	syntax keyword foobarType	Short Long
>	hi link foobarType	Type
>	hi foobarComment guifg=Green


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 above, but at the second item add a "!" to
the autocmd:
>	" FooBar language
>	:autocmd! Syntax foobar		source /home/someone/vim/foobar.vim
Check: If you do ":autocmd Syntax foobar" you will only see the syntax file
you just added:
>	Syntax
>	   foobar	source /home/someone/vim/foobar.vim


NAMING CONVENTIONS
							*group-name*
To be able to allow each user to pick his favorite set of colors, there need
to be preferred names for highlight groups that are common for many languages.
These are the ones that are suggested to be used:

	*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

	*Ignore		left blank, hidden

	*Error		any erroneous construct

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

The ones marked with * are the preferred groups, the other 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 giving ":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

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

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

What ":syntax on" does:

    Source $VIMRUNTIME/syntax/syntax.vim
    |
    +-	Clear out any old syntax.
    |
    +-	Source $VIMRUNTIME/syntax/synload.vim
    |	|
    |	+-  Set up standard highlighting groups
    |	|
    |	+-  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 where you can add your own syntax autocommands for loading
    |	    your syntax file when the 'syntax' option is set.  You can also
    |	    modify the standard highlighting here. *synload-2*
    |
    +-	Source $VIMRUNTIME/filetype.vim
    |	|
    |	+-  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*
    |	|