*syntax.txt*	For Vim version 7.1.  Last change: 2007 May 11  		  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 orcolor.	Those parts can be specific keywords or text matching a pattern.  Vimdoesn't parse the whole file (to keep it fast), so the highlighting has itslimitations.  Lexical highlighting might be a better name, but since everybodycalls it syntax highlighting we'll stick with that. Vim supports syntax highlighting on all terminals.  But since most ordinaryterminals have very limited highlighting possibilities, it works best in theGUI 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.  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} Syntax highlighting is not available when the |+syntax| feature has beendisabled 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 findthe path in another way (see |$VIMRUNTIME|).  Usually this works justfine.  If it doesn't, try setting the VIM environment variable to thedirectory where the Vim stuff is located.  For example, if your syntax filesare in the "/usr/vim/vim50/syntax" directory, set $VIMRUNTIME to"/usr/vim/vim50".  You must do this in the shell, before starting Vim. 							*:syn-on* *:syntax-on*The ":syntax enable" command will keep your current color settings.  Thisallows using ":highlight" commands to set your preferred colors before orafter using this command.  If you want Vim to overrule your settings with thedefaults, use: >	:syntax on<					*:hi-normal* *:highlight-normal*If you are running in the GUI, you can get white text on a black backgroundwith: >	:highlight Normal guibg=Black guifg=WhiteFor a color terminal see |:hi-normal-cterm|.For setting up your own colors syntax highlighting see |syncolor|. 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 offile for your system.  Although on MS-DOS and Windows the right format isautomatically selected if the 'fileformats' option is not empty. NOTE: When using reverse video ("gvim -fg white -bg black"), the default valueof 'background' will not be set until the GUI window is opened, which is afterreading the |gvimrc|.  This will cause the wrong default highlighting to beused.  To set the default value of 'background' before switching onhighlighting, 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 theforeground!  Use ":gui -f" then.  You can toggle the syntax on/off with this command >   :if exists("syntax_on") | syntax off | else | syntax enable | endif To put this into a mapping, you can use: >   :map <F7> :if exists("syntax_on") <Bar>	\   syntax off <Bar>	\ else <Bar>	\   syntax enable <Bar>	\ endif <CR>[using the |<>| notation, type this literally] DetailsThe ":syntax" commands are implemented by sourcing a file.  To see exactly howthis 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.vimAlso see |syntax-loading|. ==============================================================================2. Syntax files						*:syn-files* The syntax and highlighting commands for one language are normally stored ina syntax file.	The name convention is: "{name}.vim".  Where {name} is thename 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.  Butthe idea is that only commands for a specific language are included.  When alanguage 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.vimThese 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 theseautomatically 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=mineYou 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 userto 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 toadd 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 bedifferent.  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 newversion, follow the same steps as for |mysyntaxfile| above.  Just make surethat you write the syntax file in a directory that is early in 'runtimepath'.Vim will only load the first syntax file found.  NAMING CONVENTIONS				    *group-name* *{group-name}* *E669* *W18*The name for a highlight or syntax group must consist of ASCII letters, digitsand the underscore.  As a regexp: "[a-zA-Z0-9_]*" To be able to allow each user to pick his favorite set of colors, there mustbe preferred names for highlight groups that are common for many languages.These are the suggested group names (if syntax highlighting works properlyyou 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 	*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 samehighlighting.  You can override these defaults by using ":highlight" commandsafter 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 enable" isissued.  When Vim initializes itself, it finds out where the runtime files arelocated.  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. 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 othersettings, depending on which syntax is active.	Example: >   :au BufReadPost * if b:current_syntax == "csh"   :au BufReadPost *   do-some-things   :au BufReadPost * endif  2HTML						*2html.vim* *convert-to-HTML* This is not a syntax file itself, but a script that converts the currentwindow into HTML.  Vim opens a new window in which it builds the HTML file. 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<Warning: This is slow!							*:TOhtml*Or use the ":TOhtml" user command.  It is defined in a standard plugin.":TOhtml" also works with a range and in a Visual area: > 	:10,40TOhtml After you save the resulting file, you can view it with any HTML viewer, suchas Netscape.  The colors should be exactly the same as you see them in Vim. To restrict the conversion to a range of lines set "html_start_line" and"html_end_line" to the first and last line to be converted.  Example, usingthe last set Visual area: > 	:let html_start_line = line("'<")	:let html_end_line = line("'>") The lines are numbered according to 'number' option and the Numberhighlighting.  You can force lines to be numbered in the HTML output bysetting "html_number_lines" to non-zero value: >   :let html_number_lines = 1Force to omit the line numbers by using a zero value: >   :let html_number_lines = 0Go back to the default to use 'number' by deleting the variable: >   :unlet html_number_lines Closed folds are put in the HTML as they are displayed.  If you don't wantthis, use the |zR| command before invoking 2html, or use: >   :let html_ignore_folding = 1 By default, HTML optimized for old browsers is generated.  If you prefer usingcascading style sheets (CSS1) for the attributes (resulting in considerablyshorter and valid HTML 4 file), use: >   :let html_use_css = 1 By default "<pre>" and "</pre>" is used around the text.  This makes it showup as you see it in Vim, but without wrapping.	If you prefer wrapping, at therisk of making some things look a bit different, use: >   :let html_no_pre = 1This will use <br> at the end of each line and use "&nbsp;" for repeatedspaces. The current value of 'encoding' is used to specify the charset of the HTMLfile.  This only works for those values of 'encoding' that have an equivalentHTML charset name.  To overrule this set g:html_use_encoding to the name ofthe charset to be used: >   :let html_use_encoding = "foobar"To omit the line that specifies the charset, set g:html_use_encoding to anempty string: >   :let html_use_encoding = ""To go back to the automatic mechanism, delete the g:html_use_encodingvariable: >   :unlet html_use_encoding<For diff mode a sequence of more than 3 filler lines is displayed as threelines with the middle line mentioning the total number of inserted lines.  Ifyou prefer to see all the inserted lines use: >    :let html_whole_filler = 1And to go back to displaying up to three lines again: >    :unlet html_whole_filler<					    *convert-to-XML* *convert-to-XHTML*An alternative is to have the script generate XHTML (XML compliant HTML).  Todo this set the "use_xhtml" variable: >    :let use_xhtml = 1To disable it again delete the variable: >    :unlet use_xhtmlThe generated XHTML file can be used in DocBook XML documents.  See:	http://people.mech.kuleuven.ac.be/~pissaris/howto/src2db.html Remarks:- This only works in a version with GUI support.  If the GUI is not actually  running (possible for X11) it still works, but not very well (the colors  may be wrong).- Older browsers will not show the background colors.- From most browsers you can also print the file (in color)! Here is an example how to run the script over all .c and .h files from aUnix shell: >   for f in *.[ch]; do gvim -f +"syn on" +"run! syntax/2html.vim" +"wq" +"q" $f; done< ABEL						*abel.vim* *ft-abel-syntax* ABEL highlighting provides some user-defined options.  To enable them, assignany value to the respective variable.  Example: >	:let abel_obsolete_ok=1To disable them use ":unlet".  Example: >	:unlet abel_obsolete_ok Variable			Highlight ~abel_obsolete_ok		obsolete keywords are statements, not errorsabel_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 pythonby default.  Syntax highlighting for other script languages can be installedby the function AntSyntaxScript(), which takes the tag name as first argumentand 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 depending on Apache HTTPserver version, by default for 1.3.x.  Set "apache_version" to Apache version(as a string) to get highlighting for another version.	Example: > 	:let apache_version = "2.0"<

Lines 1–500 of 4530. Load more