Softpanorama

May the source be with you, but remember the KISS principle ;-)
Contents Bulletin Scripting in shell and Perl Network troubleshooting History Humor

VIM Syntax Highlighting

News Annoying colors in vim Recommended Links VIM Configuration Color schemes in VIM Vimrc Examples
VIM Syntax Highliting Color schemes in VIM Options History of VI editor and its derivatives VIM Humor Etc

Introduction

There are two ways to add a new language syntax highlighting to vim: permanent and temporary. Suitability of particular highlighting is highly dependent of color scheme used and for some files you are  essentially forced to change the color scheme because elements are simply not visible on the background. 

For light color scheme delek or desert are not bad.

For dark blue.vim should be considered. Of course you can turn highlighting off ion such cases, but that defeats the purpose.

There are multiple default color schemes shipped with VIM 7.2 in

 /usr/share/vim//vim72/colors
Here are some description of available schemes:
evening.vim   -- grey backgroud with no clearly visible line numbers
README.txt
peachpuff.vim -- light yellow background with visible line numbers
elflord.vim   -- light yellow background line numbers not visible
pablo.vim     -- light yellow background line numbers not visible
shine.vim     -- grey background with visible line numbers
murphy.vim    -- black background with green letters like in old terminals contract color scheme
blue.vim      -- Midnight Commander style
default.vim   -- light yellow background with visible line numbers
koehler.vim   -- light yellow background with visible line numbers
slate.vim     -- light yellow background with visible line numbers
desert.vim    -- light yellow background with visible line numbers
delek.vim     -- light yellow background with visible line numbers
ron.vim       -- light yellow background, line numbers are not visible
darkblue.vim  -- blackbackgound with grey letters and green line numbers
torte.vim     -- black background high contract color scheme
morning.vim   -- grey background with non visible line numbers
zellner.vim   -- light yellow background with visible line numbers

Turn on or off color syntax highlighting in vi or vim

If syntax highlighting is disrupting you can turn it  off. Press ESC key, type : syn off

:syn off

Sometimes the situation improves if you set background dark:

:set background=dark

press ESC key, type : syntax on

:syntax on

To ensure that syntax highlighting is off by default you can add the line

syntax off

to t ~/.vimrc file

But it's better to select a better color scheme Color schemes in VIM

Permanent method

First, create the syntax highlighting file in:

 /usr/share/vim/vim63/syntax/tecrules.vim

where all the other syntax files are (This will cause this to affect all users, of course).

Next, make this addition to the

 /usr/share/vim/vim63/filetype.vim

 

Temp method

  1. CExecute command that binds a new filetype to an extension. Assuming that your language uses files ending in *.rls you would add
             au BufRead,BufNewFile *.rls set filetype=tecrules 
    

    An entry to read your syntax file is needed too:

             au! Syntax newlang source $VIM/tecrules.vim
    

    (make sure that the path is correct).
     

  2. Now create a file called tecrules.vim by copying one of the many language files already available (in this case Prolog) Make the necessary changes and save the file.
     
  3. Open a source file of your new language and enjoy the color. For a detailed descriptions of the commands used in syntax files check the vim help pages by entering
             :help syntax

    in vim.


Top updates

Bulletin Latest Past week Past month
Google Search


NEWS CONTENTS

Old News ;-)

[Nov 10, 2002] HaloStatue.ca-vim syntax highlighting by Austin Ziegler

In the descriptions of configuration changes below, all changes to $VIMRUNTIME/filetype.vim are required; the changes are for Vim 6.0 and higher. To make the changes compatible with earlier versions of Vim, change 'setf' to 'set ft='. All changes to $VIMRUNTIME/makemenu.vim are optional and only affect the Syntax menu in VIM. If changes are made here, make sure that you run :so $VIMRUNTIME/makemenu.vim. All changes to $VIMRUNTIME/syntax/synload.vim are only applicable to versions of Vim prior to Vim 6.0.

10 light vim color schemes that you should consider using - Vim plugins, tips, tricks and tutorials

Tip #53 - Better colors for syntax highlighting vim online

March 18, 2001 | vim.sourceforge.net
created: March 18, 2001 12:59 complexity: basic
author: Anonymous as of Vim: 5.7

For syntax highlighting there are two sets of default color
maps: One for a light and another one for a dark background.
If you have a black background, use the following command to
get a better color map for syntax highlighting:

:set background=dark

You have to switch off and on again syntax highlighting to
activate the new color map:

:syntax off
:syntax on

For a detailed description of syntax highlighting refer to

:help syntax.txt

See also the Vim syntax support file: $VIMRUNTIME/syntax/synload.vim

Tip #121 - Using vim as a syntax-highlighting pager vim online

If you want to use Vim's syntax highlighting in a "more"-style pager, here's
one way to set it up:

First, create a vimrc like the following -- I called mine ~/.vimrc.more

---8<---cut here---8<---
" No compatibility -- necessary for mappings to work.
set nocompatible

" Status line
set laststatus=0
set cmdheight=1
set nomodifiable " Only in version 6.0
set readonly

" Syntax colouring -- lines taken from syntax.txt discussion on colour xterms.
" See ':help color-xterm'. Use appropriate lines for your own set-up.
if has("terminfo")
set t_Co=16
set t_Sf=[3%p1%dm
set t_Sb=[4%p1%dm
else
set t_Co=16
set t_Sf=[3%dm
set t_Sb=[4%dm
endif
" My xterms have a navy-blue background, so I need this line too.
set background=dark
" Turn syntax on
syntax on

" Key bindings.
nmap b <C-B><C-G>
nmap q :q<CR>
" To type the following line, type *two* C-V's followed by two spaces. This
" is how you map the spacebar.
nmap ^V <C-F><C-G>
---8<---cut here---8<---

Then, to use this .vimrc, add an alias. If you're using tcsh, the syntax will
be something like:

alias vmore "vim -u ~/.vimrc.more"

Then you can type "vmore [filename]" to view a file in this "pager". Spacebar
will move down, 'b' will move back up, and 'q' quits. You can add mappings for
other keys if you want to, also.

Maintained VIM Syntax Files

Pro*C/C++ (proc.vim, procpp.vim)

URL: http://www.halostatue.ca/vim/files/proc.vim, http://www.halostatue.ca/vim/files/procpp.vim

These two files work together and should not be downloaded separately. They do their magic by including the appropriate language file (e.g., c.vim or cpp.vim) and then introducing the relevant Pro*C/C++ and SQL keywords for highlighting.

There is a minor problem with the highlighting and certain instances of bind variable use (it is most commonly seen with INTO clauses). If you have a statement like:

SELECT MAX (foo)
INTO : oFOO;
FROM bar;

If you're not on a CSS-enabled browser, the highlighting on INTO goes all the way to "INTO :" and it is different than the rest of the SQL statement. This is because the portion of the Pro*C/C++ syntax file inherited from the C/C++ syntax files recognises the text before the colon (':' as a label. There does not appear to be a clean way of excluding these clauses from being considered labels.

Because these syntax files are not yet in the VIM distribution, there are necessary changes to be made to up to three files to fully support Pro*C/C++ in Vim.

$VIMRUNTIME/filetype.vim

To change $VIMRUNTIME/filetype.vim to support Pro*C/C++ syntax highlighting, a couple of lines need to be found and completely replaced. Do a search for /\*\.cxx/ and replace the lines there with the following code.

" 20010722az: New variable: proc_headers. This identifies headers
" as 'capable of handling Pro*C/C++ contents'
if has("fname_case")
  if exists("proc_headers")
    au BufNewFile,BufRead *.cxx,*.c++,*.C,*.tcc setf cpp
    au BufNewFile,BufRead *.H,*.hh,*.hxx,*.hpp,*.inl setf procpp
  else
    au BufNewFile,BufRead *.cxx,*.c++,*.C,*.tcc,*.H,*.hh,*.hxx,*.hpp,*.inl setf cpp
  endif
else
  if exists("proc_headers")
    au BufNewFile,BufRead *.cxx,*.c++,*.tcc setf cpp
    au BufNewFile,BufRead *.hh,*.hxx,*.hpp,*.inl setf procpp
  else
    au BufNewFile,BufRead *.cxx,*.c++,*.tcc,*.hh,*.hxx,*.hpp,*.inl setf cpp
  endif
endif

" Pro*C/C++ files.
" 20010722az
if has("fname_case")
  au BufNewFile,BufRead *.pc setf proc
  au BufNewFile,BufRead *.PC setf procpp
else
  au BufNewFile,BufRead *.pc setf procpp
endif

Then look for /c_syntax_for_h/ and replace the line or lines there with the following:

if exists("c_syntax_for_h")
  if exists("proc_headers")
    au BufNewFile,BufRead *.h setf proc
  else
    au BufNewFile,BufRead *.h setf c
  endif
else
  if exists("proc_headers")
    au BufNewFile,BufRead *.h setf procpp
  else
    au BufNewFile,BufRead *.h setf cpp
  endif
endif

$VIMRUNTIME/makemenu.vim

When those changes are done, add the following two lines to the appropriate place in this file (you may need to change the first part of the menu to match your local settings). After making these changes, run $VIMRUNTIME/makemenu.vim.

SynMenu PQ.Pro\*C:proc
SynMenu PQ.Pro\*C\+\+:procpp

$VIMRUNTIME/syntax/synload.vim

When those changes are done, add the following two lines to the appropriate place in this file:

SynAu proc
SynAu procpp

▲Return to language list.

Pro*COBOL (procobol.vim)

URL: http://www.halostatue.ca/vim/files/procobol.vim

This is simply an opportunistic little hack of the proc.vim syntax file to load the COBOL syntax reference instead and use this. Any problems that exist with the COBOL handling of this syntax file should be reported to the maintainer of the COBOL syntax file.

The changes required to $VIMRUNTIME/filetype.vim, $VIMRUNTIME/makemenu.vim, and $VIMRUNTIME/syntax/synload.vim are less significant than they are for Pro*C/C++ syntax files.

$VIMRUNTIME/filetype.vim

Add the following lines to this file:

  " Pro*COBOL
  " 20010722az
au BufNewFile,BufRead *.pco setf procobol

$VIMRUNTIME/makemenu.vim

Add the following line to this file:

SynMenu PQ.Pro\*COBOL:procobol

$VIMRUNTIME/syntax/synload.vim

Add the following line to this file:

SynAu procobol

▲Return to language list.

PocketC (pocketc.vim)

URL: http://www.halostatue.ca/vim/files/pocketc.vim

This is simply an opportunistic little hack of the c.vim syntax file. It has been modified to support PocketC-specific structures, but is not yet complete.

The changes required to $VIMRUNTIME/filetype.vim, $VIMRUNTIME/makemenu.vim, and $VIMRUNTIME/syntax/synload.vim are minor.

$VIMRUNTIME/filetype.vim

Add the following lines to this file:

  " Pocket C
  " 20010722az
au BufNewFile,BufRead *.pkc,*.pkh setf pocketc

$VIMRUNTIME/makemenu.vim

Add the following line to this file:

SynMenu PQ.Pocket\ C:pocketc

$VIMRUNTIME/syntax/synload.vim

Add the following line to this file:

SynAu pocketc

Return to language list.

PocoScript (pocoscript.vim)

URL: http://www.halostatue.ca/vim/files/pocoscript.vim

This file is a new syntax file, created from scratch. While I haven't kept it up to date, it is still (mostly) complete. Most of the missing features are related to error handling and new features as of Poco 2.1 and Poco 2.5, and are simple keywords. PocoMail is the best and most flexible Windows mailer available for many reasons, not least of which because it is scriptable.

The changes required to $VIMRUNTIME/filetype.vim, $VIMRUNTIME/makemenu.vim, and $VIMRUNTIME/syntax/synload.vim are minor.

$VIMRUNTIME/filetype.vim

Add the following lines to this file:

  " PocoScript
  " 20010722az
au BufNewFile,BufRead *.poc,*.poco setf pocoscript

$VIMRUNTIME/makemenu.vim

Add the following line to this file:

SynMenu PQ.PocoScript:pocoscript

$VIMRUNTIME/syntax/synload.vim

Add the following line to this file:

SynAu pocoscript

▲Return to language list.

Pseudo-Language (pseudo.vim)

URL: http://www.halostatue.ca/vim/files/pseudo.vim

This little syntax file represents a simple pseudo-language that I use from time to time when coding software, in an attempt to express the logic in English. It doesn't have a formal specification, so this is a "one-off" syntax file. I recommend that changes NOT be made to $VIMRUNTIME/filetype.vim and $VIMRUNTIME/syntax/synload.vim, as this is something that should be used sparingly. You may wish to add it to a menu yourself if you use it. Additionally, I may or may not provide further updates to this.

▲Return to language list.

SQL*Forms (sqlforms.vim)

URL: http://www.halostatue.ca/vim/files/sqlforms.vim

Frankly, I don't know anyone that uses this syntax file. I last worked with someone who programmed SQL*Forms more than three years ago. I'm not an SQL*Forms programmer, and so I don't have complete assurance that this is correct. I am looking for a maintainer to take this over.

Recommended Links

Softpanorama hot topic of the month

Softpanorama Recommended

Top articles

Sites

Top articles

Sites

Vim Color Editor HOW-TO (Vi Improved with syntax color highlighting) Al Dev (Alavoor Vasudevan) alavoor@yahoo.com v17.2, 28 June 2001

This document is a guide to quickly setting up the Vim color editor on Linux or Unix systems. The information here will improve the productivity of programmers because the Vim editor supports syntax color highlighting and bold fonts, improving the "readability" of program code. A programmer's productivity improves 2 to 3 times with a color editor like Vim. The information in this document applies to all operating sytems where Vim works, such as Linux, Windows 95/NT, Apple Mac, IBM OSes, VMS, BeOS and all flavors of Unix like Solaris, HPUX, AIX, SCO, Sinix, BSD, Ultrix etc.. (it means almost all operating systems on this planet!)

Dr. Chip's Vim Page
(http://mysite.verizon.net/astronaut/vim/)

Syntax highlighting files (including for TeX/LaTeX, Maple, and Lisp), scripts, and spell-checking for Vim.

voip-info.org vim syntax highlighting

A shout out to Corydon for the rewrite, it all actually works now :)
Thanks also to Olle

If you make changes/bug fixes/add features to this file please either edit this version or paste yours at the end.


VIM syntax matching notes

  • "\s*,\s*[0-9]*\s*,\s*\zs[a-zA-Z][a-zA-Z]*\ze" matches space,comma, space, priority 0-9,space, comma, space, start-of-match, one character, any number of characters, end-of-match
  • The \zs and \ze is much like ( and ) in ordinary regexps. Parenthesis are matched *if not* escaped with backslash.

To use
paste the below into a text file called asterisk.vim and save it in your home dir
vim /usr/src/asterisk/configs/extensions.conf.sample
:syntax on
:source path/to/asterisk.vim

Assuming the file below is saved instead in ~/.vim/syntax/asterisk.vim, you can automate the commands above by adding the following line to the very bottom of each of your /etc/asterisk/*.conf files:
; vim: set ts=8 sw=2 filetype=asterisk:
This works on my latest FC2 machine without any other VIM adjustments.

or

Here's another approach to make Vim autoload the syntax file below.

First, create the file in:

/usr/share/vim/vim63/syntax/asterisk.vim

where all the other syntax files are. (This will cause this to affect all users, of course).

Next, make this addition to the

/usr/share/vim/vim63/filetype.vim

file:

" Asterisk config file
au BufNewFile,BufRead *asterisk/*.conf* setf asterisk

This will basically cause any .conf file in the /etc/asterisk directory to use the below "asterisk" type highlighting. You could make it more specific and this will naturally just pickup the .conf files in certain directories, but I found it more convenient than anything else.



" Vim syntax file
" Language:	Asterisk config file
" Maintainer:	brc007
" Last Change:	2005 Mar 7
" version 0.2
"
" Additional changes made 2005 Mar 7 by Corydon76
" * CVS priority, including n and s, and new label definitions
" * ENV( and LEN( support
" * Class patterns in extensions now match only the class pattern (instead of to a following expression)
" * anthm's functions are matched
" * Variables now appear in their own colors inside expressions

" For version 5.x: Clear all syntax items
" For version 6.x: Quit when a syntax file was already loaded
if version < 600
  syntax clear
elseif exists("b:current_syntax")
  finish
endif

"testing only
syn sync clear
syn sync fromstart


syn keyword	asteriskTodo	TODO contained
syn match	asteriskComment		";.*" contains=asteriskTodo
syn match       asteriskContext         "\[.\{-}\]"
syn match	asteriskExten		"^\s*exten\s*=>"
syn match       asteriskApp             "\s*,\s*\zs[a-zA-Z]*\ze"
" Digits plus oldlabel (newlabel)
syn match       asteriskPriority        ",[[:digit:]]\+\(+[[:alpha:]][[:alnum:]_]*\)\?\(([[:alpha:]][[:alnum:]_]*)\)\?,"
" s or n plus digits (newlabel)
syn match       asteriskPriority        ",[sn]\(+[[:digit:]]\+\)\?\(([[:alpha:]][[:alnum:]_]*)\)\?,"
syn match       asteriskIncludeBad "^\s*#\s*[[:alnum:]]*"
syn match       asteriskInclude		"^\s#\sinclude\s.*"
syn match       asteriskVar             "\${_\{0,2}[[:alpha:]][[:alnum:]_]*\(:[[:digit:]]\+\)\{0,2}}"
syn match       asteriskVarLen          "\${_\{0,2}[[:alpha:]][[:alnum:]_]*(.\{-})}" contains=asteriskVar,asteriskVarLen,asteriskExp
syn match       asteriskExp             "\$\[.\{-}\]" contains=asteriskVar,asteriskVarLen,asteriskExp
syn match       asteriskFunc            "\$([[:alpha:]][[:alnum:]_]*.*)" contains=asteriskVar,asteriskVarLen,asteriskExp

" Define the default highlighting.
" For version 5.7 and earlier: only when not done already
" For version 5.8 and later: only when an item doesn't have highlighting yet
:if version >= 508 || !exists("did_conf_syntax_inits")
  if version < 508
    let did_conf_syntax_inits = 1
    command -nargs=+ HiLink hi link <args>
  else
    command -nargs=+ HiLink hi def link <args>
  endif


  HiLink	asteriskComment	Comment
" not sure what type this should be, using String for testing.
  HiLink	asteriskExten	String
" same here
  HiLink	asteriskContext		Identifier 
  HiLink        asteriskApplication     Statement
  HiLink        asteriskInclude		Preproc 
  HiLink        asteriskIncludeBad  Error
  HiLink	asteriskPriority	Preproc	
  HiLink        asteriskVar             String
  HiLink        asteriskVarLen          Function
  HiLink        asteriskExp             Type
 delcommand HiLink
endif


let b:current_syntax = "asterisk" 

" vim: ts=8 sw=2

Reference

Vim Documentation: syntax


     For Vim version 5.0p.  Last modification: 1997 Oct 15


		  VIM REFERENCE MANUAL    by Bram Moolenaar


Syntax highlighting		     

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 file remarks	 |:syn-file-remarks|
4.  Defining a syntax	 |:syn-define|
5.  :syntax arguments	 |:syn-arguments|
6.  Syntax patterns	 |:syn-pattern|
7.  Synchronizing	 |:syn-sync|
8.  Listing syntax items |:syntax|
9.  Highlight command	 |:highlight|
10. Linking groups	 |:highlight-link|
11. Cleaning up		 |:syn-clear|
12. Highlighting tags	 |tag-highlight|
13. Color xterms	 |xterm-color|

{Vi does not have any of these commands}


1. Quick start						 

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.

What this command actually does, is executing the command
>  source $VIM/syntax/syntax.vim
If the VIM environment variable is not set, Vim will try to find
the path in another way (see |$VIM|).  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/5.0/syntax" directory, set $VIM to "/usr/vim/5.0".  You must do this
in the shell, before starting Vim.

							 
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.

If you are running in the GUI, you can get white text on a black background
with:
>  highlight Normal guibg=Black guifg=White

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.


2. Syntax 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 $VIM/syntax/c.vim

The .vim files are normally loaded with an autocommand.  For example:
>  :au BufNewFile,BufReadPost  .h source $VIM/syntax/c.vim
>  :au BufNewFile,BufReadPost *.cpp source $VIM/syntax/cpp.vim


MAKING YOUR OWN SYNTAX FILES				 

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 file when
   the right file name or extension is detected.  To prevent loading two
   syntax files (when the extension is used twice), first delete other
   autocommands for the same extension.  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:
>    augroup syntax
>    au! BufNewFile,BufReadPost *.bat
>    au  BufNewFile,BufReadPost *.bat  so ~/vim/batch.vim
>    augroup END
>    highlight Comment gui=bold
   Let's assume you write this file in "~/vim/mysyntax.vim".

2. In your .vimrc, set the "mysyntaxfile" variable to the file you just
   created.  For example:
>  :let mysyntaxfile = "~/vim/mysyntax.vim"

3. If your file type can only be detected by inspecting the contents of the
   file, create another file for doing this.  See $VIM/syntax/scripts.vim for
   examples.  Let's assume you write this file in "~/vim/myscripts.vim".
   Then set the "myscriptsfile" variable to this file name.  Example:
>  :let myscriptsfile = "~/vim/myscripts.vim"
   Note that this file is only used when no syntax file was loaded by the
   autocommands, if the file type has not been detected by the file name or
   extension.

Note that "mysyntaxfile" is sourced AFTER defining the default autocommands
for the supplied syntax files, so you can override these with your own files.
The "myscriptsfile" is loaded before the default checks for syntax files,
which also means that your rules override the supplied rules.


NAMING CONVENTIONS
							 
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

	*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

	*Error		any erroneous construct

	*Todo		anything that needs extra attention

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 file remarks					 

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


JAVA							     

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


SH							     

This covers the "normal" Unix sh, bash and the korn shell.  If you're working
on a system where bash is called sh, you will benefit to define the vim
variable 'bash_is_sh' in your '.vimrc' file:
>  let bash_is_sh = 1

To choose between the two ways to treat single-quotes inside a pair of
double-quotes, I have introduced a Vim variable "highlight_balanced_quotes".
By default (ie by not declaring this variable) single quotes can be used
inside double quotes, and are not highlighted.  If you prefer balanced single
quotes as I do you just make the statement in your .vimrc file:
>  let highlight_balanced_quotes = 1

Similar I have introduced another vim variable "highlight_function_name" to be
used to enable/disable highlighting of the function-name in function
declaration.  Default is not to highlight the function name.  If you want to
highlight functions names, include this in your .vimrc file:
>  let highlight_function_name = 1


4. Defining a syntax					 

Vim understands three types of syntax items:
1. A keyword.  It can only contain keyword characters, according to the
   'iskeyword' option.  It cannot contain other syntax items.  It will only
   be recognized when it is a complete match (there are no keyword
   characters before or after the match).  "if" would match in "if(a=b)",
   but not in "ifdef x".
2. A match.  This is a match with a single regexp pattern.  It must be within
   one line.
3. A region.  This starts at a match of the start regexp pattern and
   ends with a match with the end regexp pattern.  A skip regexp pattern can
   be used to avoid matching the end pattern.

Several syntax ITEMs can be put into one syntax GROUP.  For a syntax group
you can give highlighting attributes.  For example, you could have an item
to define a "/ /" comment and another one that defines a "// .." comment,
and put them both in the "Comment" group.  You can then specify that a
"Comment" will be in bold font and have a blue color.  You are free to make
one highlight group for one syntax item, or put all items into one group.
This depends on how you want to specify your highlighting attributes.  Putting
each item in its own group results in having to specify the highlighting
for a lot of groups.

Note that a syntax group and a highlight group are similar.  For a highlight
group you will have given highlight attributes.  These attributes will be used
for the syntax group with the same name.

In case more than one item matches at the same position, the one that was
defined LAST wins.  Thus you can override previously defined syntax items by
using an item that matches the same text.  But a keyword always goes before a
match or region.  And a keyword with matching case always goes before a
keyword with ignoring case.


DEFINING CASE						 

:syntax case [match|ignore]
	This defines if the following ":syntax" commands will work with
	matching case, when using "match", or with ignoring case, when using
	"ignore".  Note that any items before this are not affected, and all
	items until the next ":syntax case" command are affected.


DEFINING KEYWORDS					 

:syntax keyword {group-name} [{options}] {keyword} .. [{options}]

	This defines a number of keywords.

	{group-name}	Is a syntax group name such as "Comment".
	[{options}]	See |:syn-arguments| below.
	{keyword} ..	Is a list of keywords which are part of this group.

	Example:
>  :syntax keyword   Type   int long char

	The {options} can be given anywhere in the line.  They will apply to
	all keywords given, also for options that come after a keyword.
	These examples do exactly the same:
>  :syntax keyword   Type   contained int long char
>  :syntax keyword   Type   int long contained char
>  :syntax keyword   Type   int long char contained

	A keyword always has higher priority than a match or region, the
	keyword is used if more than one item matches.  Keywords do not nest
	and a keyword can't contain anything else.

	Note that when you have a keyword that is the same as an option (even
	one that isn't allowed here), you can not use it.  Use a match
	instead.

    	The maximum length of a keyword is 80 characters.

	The same keyword can be defined multiple times, when its containment
	differs.  For example, you can define the keyword once not contained
	and use one highlight group, and once contained, and use a different
	highlight group. Example:
>  :syn keyword vimCommand tag
>  :syn keyword vimSetting contained tag
	When finding "tag" outside of any syntax item, the "vimCommand"
	highlight group is used.  When finding "tag" in a syntax item that
	contains "vimSetting", the "vimSetting" group is used.


DEFINING MATCHES					 

:syntax match {group-name} [{options}] {pattern} [{options}]

	This defines one match.

	{group-name}		A syntax group name such as "Comment".
	[{options}]		See |:syn-arguments| below.
	{pattern}		The search pattern that defines the match.
				See |:syn-pattern| below.

	Example (match a character constant):
>  :syntax match Character /'.'/s+1e-1


DEFINING REGIONS	       

:syntax region {group-name} [{options}]
		[matchgroup={group_name}]
		start={start_pattern} ..
		[skip={skip_pattern}]
		end={end_pattern} ..
		[{options}]

	This defines one region.  It may span several lines.

	{group-name}		A syntax group name such as "Comment".
	[{options}]		See |:syn-arguments| below.
	[matchgroup={group-name}]  The syntax group to use for the following
				start or end pattern matches only.  Not used
				for the text in between the matched start and
				end patterns.  Use NONE to reset to not using
				a different group for the start or end match.
				See |:syn-matchgroup|.
	start={start_pattern}	The search pattern that defines the start of
				the region.  See |:syn-pattern| below.
	skip={skip_pattern}	The search pattern that defines text inside
				the region where not to look for the end
				pattern.  See |:syn-pattern| below.
	end={end_pattern}	The search pattern that defines the end of
				the region.  See |:syn-pattern| below.

	Example:
>  :syntax region String   start=+"+  skip=+\\"+  end=+"+

	The start/skip/end patterns and the options can be given in any order.
	There can be zero or one skip pattern.  There must be one or more
	start and end patterns.  This means that you can omit the skip
	pattern, but you must give at least one start and one end pattern.  It
	is allowed to have white space before and after the equal sign
	(although it mostly looks better without white space).

	When more than one start pattern is given, a match with one of these
	is sufficient.  This means there is an OR relation between the start
	patterns.  The first one that matches is used.  The same is true for
	the end patterns.

							 
	"matchgroup" can be used to highlight the start and/or end pattern
	differently than the body of the region.  Example:
>  :syntax region String matchgroup=Quote start=+"+  skip=+\\"+  end=+"+
	This will highlight the quotes with the "Quote" group, and the text in
	between with the "String" group.
	The "matchgroup" is used for all start and end patterns that follow,
	until the next "matchgroup".  Use "matchgroup=NONE" to go back to not
	using a matchgroup.

	It is not possible to have a contained match in a start or end pattern
	that is highlighted with "matchgroup".


5. :syntax arguments					 

The :syntax commands that define syntax items take a number of arguments.
The common ones are explained here.  The arguments may be given in any order
and may be mixed with patterns.

Not all commands accept all arguments.  This table shows which arguments
can be used for each command:

		 contained  nextgroup  skip*   transparent  contains  oneline
:syntax keyword	    yes	       yes	yes	    -	       -	 -
:syntax match	    yes	       yes	yes	   yes	      yes	 -
:syntax region	    yes	       yes	yes	   yes	      yes	yes


contained 						 

When the "contained" argument is given, this item will not be recognized at
the top level, but only when it is mentioned in the "contains" field of
another match.  Example:
>   :syntax keyword Todo    TODO    contained  
>   :syntax match   Comment "//.*"  contains=Todo


transparent						 

If the "transparent" argument is given, this item will not be highlighted
itself, but will take the highlighting of the item it is contained in.  This
is useful for syntax items that don't need any highlighting but are used
only to skip over a part of the text.  The same groups as the item it is
contained in are used, unless a "contains" argument is given too.


oneline							 

The "oneline" argument indicates that the region does not cross a line
boundary.  It must match completely in the current line.  However, when the
region has a contained item that does cross a line boundary, it continues on
the next line anyway.  A contained item can be used to recognize a line
continuation pattern.


contains={groupname},..					 

The "contains" argument is followed by a list of syntax group names.  These
groups will be accepted inside the item.  This allows for recursive nesting
of matches and regions.  If there is no "contains" argument, no groups will
be contained in this item.  The group names do not need to be defined before
they can be used here.

contains=ALL
		If the only item in the contains list is "ALL", then all
		groups will be accepted inside the item.

contains=ALLBUT,{group-name},..
		If the first item in the contains list is "ALLBUT", then all
		groups will be accepted inside the item, except the ones that
		are listed, and the "contained" items.  Example:
>  :syntax region Block start="{" end="}" ... contains=ALLBUT,Function

The {group-name} in the "contains" list can be a pattern.  All group names
that match the pattern will be included (or excluded, if "ALLBUT" is used).
The pattern cannot contain white space or a ','.  Example:
>  ... contains=Comment.*,Keyw[0-3]


nextgroup={groupname},..				 

The "nextgroup" argument is followed by a list of syntax group names,
separated by commas.  If the "nextgroup" argument is given, the mentioned
syntax groups will be tried for a match, after the match or region ends.  If
none of the groups have a match, highlighting continues normally.  If there is
a match, this group will used, even when it is not mentioned in the "contains"
field of the current group.  This is like giving the mentioned group priority
over all other groups.  Example:
>   :syntax match  ccFoobar  "Foo.\{-}Bar"  contains=ccFoo
>   :syntax match  ccFoo     "Foo"          contained nextgroup=ccFiller
>   :syntax region ccFiller  start="."  matchgroup=ccBar  end="Bar"  contained

This will highlight "Foo" and "Bar" differently, and only when there is a
"Bar" after "Foo".  In the text line below, "f" shows where ccFoo is used for
highlighting, and "bbb" where ccBar is used.

>   Foo asdfasd Bar asdf Foo asdf Bar asdf
>   fff         bbb      fff      bbb

Note the use of ".\{-}" to skip as little as possible until the next Bar.
when ".*" would be used, the "asdf" in between "Bar" and "Foo" would be
highlighted according to the "ccFoobar" group, because the ccFooBar match
would include the first "Foo" and the last "Bar" in the line (see |pattern|).


skipwhite						 
skipnl							 
skipempty						 

These arguments are only used in combination with "nextgroup".  They can be
used to allow the next group to match after skipping some text:
	skipwhite	skip over space and Tab characters
	skipnl		skip over the end of a line
	skipempty	skip over empty lines (implies a "skipnl")

When "skipwhite" is present, the white space is only skipped if there is no
next group that matches the white space.

When "skipnl" is present, the match with nextgroup may be found in the next
line.  This only happens when the current item ends at the end of the current
line!  When "skipnl" is not present, the nextgroup will only be found after
the current item in the same line.

When skipping text while looking for a next group, the matches for other
groups are ignored.  Only when no next group matches, other items are tried
for a match again.  This means that matching a next group and skipping white
space and newlines has a higher priority than other items.

Example:
>  syn match ifstart "if.*"     nextgroup=ifline skipwhite skipempty
>  syn match ifline  "endif"    contained
>  syn match ifline  "[^ \t].*" nextgroup=ifline skipwhite skipempty contained
Note that the last match, which matches any non-white text, is put last,
otherwise the "endif" of the indent would never match, because the "[^ \t].*"
would match first.
Note that this example doesn't work for nested "if"s.  You need to add 
"contains" arguments to make that work (omitted for simplicity of the
example).


6. Syntax patterns					 

In the syntax commands, a pattern must be surrounded by two identical
characters.  This is like it works for the ":s" command.  The most common to
use is the double quote.  But if the pattern contains a double quote, you can
use another character that is not used in the pattern.  Examples:
>  :syntax region Comment  start="/\ /"
>  :syntax region String   start=+"+    end=+"+   skip=+\\"+

See |pattern| for the explanation of what a pattern is.  Syntax patterns are
always interpreted like the 'magic' options is set, no matter what the actual
value of 'magic' is.  This was done to make syntax files portable.

Try to avoid patterns that can match an empty string, such as "[a-z]*".
This slows down the highlighting a lot, because it matches everywhere.

The pattern can be followed by a character offset.  This can be used to
change the highlighted part, and to change the text area included in the
match or region (which only matters when trying to match other items).  Both
are relative to the matched pattern.  The character offset for a skip
pattern can be used to tell where to continue looking for an end pattern.

The offset takes the form of "{what}={offset}"
The {what} can be one of six strings:

ms	Match Start	offset for the start of the matched text
me	Match End	offset for the end of the matched text
hs	Highlight Start	offset for where the highlighting starts
he	Highlight End	offset for where the highlighting ends
rs	Region Start	offset for where the body of a region starts
re	Region End	offset for where the body of a region ends

The {offset} can be:

s	start of the matched pattern
s+{nr}	start of the matched pattern plus {nr} chars to the right
s-{nr}	start of the matched pattern plus {nr} chars to the left
e	end of the matched pattern
e+{nr}	end of the matched pattern plus {nr} chars to the right
e-{nr}	end of the matched pattern plus {nr} chars to the left

Although all offsets are accepted after any pattern, they are not always
meaningful.  This table shows which offsets are actually used:

		    ms   me   hs   he   rs   re
match item          yes  yes  yes  yes  -    -
region item start   yes  -    yes  -    yes  -
region item skip    -    yes  -    -    -    -
region item end     -    yes  -    yes  -    yes

Offsets can be concatenated, with a ',' in between.  Example:
>  syn match String  /".*"/hs=s+1,he=e-1

    some "string" text
          ^^^^^^         highlighted

Notes:
- There must be no white space between the pattern and the character
  offset(s).
- The highlighted area will never be outside of the matched text.
- A negative offset for an end pattern may not always work, because the end
  pattern may be detected when the highlighting should already have stopped.

Example (match a comment but don't highlight the / /):
>  :syntax region Comment start="/\ /"he=s-1

	/ /
	  ^^^^^^^^^^^^^^^^^^^     highlighted

A more complicated Example:
>  :syn region Exa matchgroup=Foo start="foo"hs=s+2,rs=e+2 matchgroup=Bar end="bar"me=e-1,he=e-1,re=s-1

	 abcfoostringbarabc
	    mmmmmmmmmmm	    match
	      ssrrrreee	    highlight start/region/end ("Foo", "Exa" and "Bar")



7. Synchronizing					 

Vim wants to be able to start redrawing in any position in the document.  To
make this possible it needs to know the syntax item at the position where
redrawing starts.

:syntax sync [ccomment [group-name] || ...]

There are three ways to synchronize:
1. Based on C-style comments.  Vim understands how C-comments work and can
   figure out if the current line starts inside or outside a comment.
2. Jumping back a certain number of lines and start parsing there.
3. Searching backwards in the text for a pattern to sync on.

For all three methods, the line range where the parsing can start is limited
by "minlines" and "maxlines".

If the "minlines={N}" argument is given, the parsing always starts at least
that many lines backwards.  This can be used if the parsing may take a few
lines before it's correct, or when it's not possible to use syncing.

If the "maxlines={N}" argument is given, the number of lines that are searched
for a comment or syncing pattern is restricted to N lines backwards (after
adding "minlines".  This is useful if you have few things to sync on and a
slow machine.  Example:
>  :syntax sync ccomment maxlines=500


First syncing method:

For the first method, only the "ccomment" argument needs to be given.
Example:
>  :syntax sync ccomment

When Vim finds that the line where displaying starts is inside a C-style
comment, the first region syntax item with the group-name "Comment" will be
used.  This requires that there is a region with the group-name "Comment"!
An alternate group name can be specified, for example:
>  :syntax sync ccomment javaComment

The "maxlines" argument can be used to restrict the search to a number of
lines.  The "minlines" argument can be used to at least start a number of
lines back (e.g., for when there is some construct that only takes a few
lines, but it hard to sync on).

Note: Syncing on a C comment doesn't work properly when strings are used
that cross al line and contain a "*/".  Since letting strings cross a line
is a bad programming habit (many compilers give a warning message), and the
chance of a "*/" appearing inside a comment is very small, this restriction
is hardly ever noticed.


Second syncing method:

For the second method, only the "lines={N}" argument needs to be given.  Vim
will subtract {N} from the line number and start parsing there.  This means
{N} extra lines need to be parsed, which makes this method a bit slower.
Example:
>  :syntax sync lines=50

"lines" and "minlines" are equivalent.


Third syncing method:

The idea is to synchronize on the end of a few specific regions, called a
sync pattern.  Only regions can cross lines, so when we find the end of some
region, we might be able to know in which syntax item we are.  The search
starts in the line just above the one where redrawing starts.  From there
the search continues backwards in the file.

A line continuation pattern can be given here.  It is used to decide which
group of lines need to be searched like they were one line.  This means that
the search for a match with the specified items starts in the first of the
consecutive that contain the continuation pattern.

When a match with a sync pattern is found, the rest of the line (or group of
continuated 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
(e.g., in a C-comment like / /, the last "*/" is used).

There are two ways how a match with a sync pattern can be used:
1. Parsing for highlighting starts where redrawing starts (and where the
   search for the sync pattern started).  The syntax group that is expected
   to be valid there must be specified.  This works well when the regions
   that cross lines cannot contain other regions.
2. Parsing for highlighting continues just after the match.  The syntax group
   that is expected to be present just after the match must be specified.
   This can be used when the previous method doesn't work well.  It's much
   slower, because more text needs to be parsed.
Both types of sync patterns can be used at the same time.

Besides the sync patterns, other matches and regions can be specified, to
avoid finding unwanted matches.

[The reason that the sync patterns are given separately, is that mostly the
search for the sync point can be much simpler than figuring out the
highlighting.  The reduced number of patterns means it will go (much)
faster.]

    :syntax sync match {group-name} grouphere {sync-group-name} ..

	Define a match that is used for syncing.  {sync-group-name} is the
	name of a syntax group that follows just after the match.  Parsing
	of the text for highlighting starts just after the match.  A region
	must exist for this sync-group-name.  The first one defined will be
	used.  "NONE" can be used for when there is no syntax group after the
	match.

    :syntax sync match {group-name} groupthere {sync-group-name} ..

	Like "grouphere", but {sync-group-name} is the name of a syntax
	group that is to be used at the start of the line where searching
	for the sync point started.  The text between the match and the
	start of the sync pattern searching is assumed not to change the
	syntax highlighting.

    :syntax sync match ..
    :syntax sync region ..

	Define a region or match that is skipped while searching for a sync
	point.

    :syntax sync linecont {pattern}

        When {pattern} matches in a line, it is considered to continue in
	the next line.  This means that the search for a sync point will
	consider the lines to be concatenated.

If the "maxlines={N}" argument is given too, the number of lines that are
searched for a match is restricted to N.  This is useful if you have very
few things to sync on and a slow machine.  Example:
>  :syntax sync maxlines=100

You can clear sync patterns with:
>  :syntax sync clear {group-name} ..


8. Listing syntax items					 

This commands lists all the syntax items:

    :syntax [list]

To show the syntax items for one syntax group:

    :syntax list {group-name}

See above for other arguments for the ":syntax" command.


9. Highlight command					 

There are two types of highlight groups:
- The ones used for specific languages.  For these the name starts with the
  name of the language.  Many of these don't have any attributes, but are
  linked to a group of the second type.
- The ones used for all languages.  These are also used for the 'highlight'
  option.

:highlight		List all the current highlight groups that have
			attributes set.

:highlight {group-name}
			List one highlight group.

:highlight {group-name} NONE
			Disable the highlighting for one highlight group.

:highlight {group-name} {key}={arg} ..
			Add a highlight group, or change the highlighting for
			an existing group.  See below for the arguments
			|highlight-args|.

Normally a highlight group is added once, in the *.vim file.  This sets
the default values for the highlighting.  After that, you can use additional
highlight commands to change the arguments that you want to set to
non-default values.  The value "NONE" can be used to switch the value off or
go back to the default value.

						 
There are three types of terminals for highlighting:
term	a normal terminal (vt100, xterm)
cterm	a color terminal (MS-DOS console, color-xterm, these have the "Co"
	termcap entry)
gui	the GUI

For each type the highlighting can be given.  This makes it possible to use
the same syntax file on all terminals, and use the optimal highlighting.

1. highlight arguments for normal terminals

term={attr-list}				   
	attr-list is a comma separated list (without spaces) of the
	following items (in any order):
		bold
		underline
		reverse
		inverse		same as reverse
		italic
		standout
		NONE		no attributes used (used to reset it)

	Note that "bold" can be used here and by using a bold font.  They
	have the same effect.

start={term-list}				 
stop={term-list}				   
	These lists of terminal codes can be used to get
	non-standard attributes on a terminal.

	The escape sequence specified with the "start" argument
	is written before the characters in the highlighted
	area.  It can be anything that you want to send to the
	terminal to highlight this area.  The escape sequence
	specified with the "stop" argument is written after the
	highlighted area.  This should undo the "start" argument.
	Otherwise the screen will look messed up.

	The {term-list} can have two forms:

	1. A string with escape sequences.
	   This is any string of characters, except that it can't start with
	   "t_" and blanks are not allowed.  The <> notation is recognized
	   here, so you can use things like "<Esc>" and "<Space>".  Example:
		start=<Esc>[27h;<Esc>[<Space>r;

	2. A list of terminal codes.
	   Each terminal code has the form "t_xx", where "xx" is the name of
	   the termcap entry.  The codes have to be separated with commas.
	   White space is not allowed.  Example:
		start=t_C1,t_BL
	   The terminal codes must exist for this to work.


2. highlight arguments for color terminals

cterm={attr-list}					 
	See above for the description of {attr-list} |attr-list|.
	The "cterm" argument is likely to be different from "term", when
	colors are used.  For example, in a normal terminal comments could
	be underlined, in a color terminal they can be made Blue.
	Note: Many terminals (e.g., DOS console) can't mix these attributes
	with coloring.  Use only one of "cterm=" OR "ctermfg=" OR "ctermbg=".

ctermfg={color-nr}					 
ctermbg={color-nr}					 
	The {color-nr} argument is a color number.  Its range is zero to
	(not including) the number given by the termcap entry "Co".
	The actual color with this number depends on the type of terminal
	and its settings.  Sometimes the color also depends on the settings of
	"cterm".  For example, on some systems "cterm=bold ctermfg=3" gives
	another color, on others you just get color 3.
	
	For an xterm this depends on your resources, and is a bit
	unpredictable.  See your xterm documentation for the defaults.  The
	colors for a color-xterm can be changed from the .Xdefaults file.
	Unfortunately this means that it's not possible to get the same colors
	for each user.  See |xterm-color| for info about color xterms.
	
	The MSDOS standard colors are fixed (in a console window), so these
	have been used for the names.  But the meaning of color names in X11
	are fixed, so these color settings have been used, to make the
	highlighting settings portable (complicated, isn't it?).  The
	following names are recognized, with the color number used:

		NR	COLOR NAME			 

		0	Black
		1	DarkBlue
		2       DarkGreen
		3       DarkCyan
		4       DarkRed
		5       DarkMagenta
		6       Brown
		7       LightGray, LightGrey, Gray, Grey
		8	DarkGray, DarkGrey
		9	Blue, LightBlue
		10	Green, LightGreen
		11	Cyan, LighCyan
		12	Red, LightRed
		13	Magenta, LightMagenta
		14	Yellow
		15	White

	The case of the color names is ignored.
	
	Note that for some color terminals these names may result in the wrong
	colors!

3. highlight arguments for the GUI

gui={attr-list}						 
	These give the attributes to use in the GUI mode.
	See |attr-list| for a description.
	Note that "bold" can be used here and by using a bold font.  They
	have the same effect.

font={font-name}					 
	font-name is the name of a font, as it is used on the system Vim
	runs on.  For X11 this is a complicated name, for example:
>  font=-misc-fixed-bold-r-normal--14-130-75-75-c-70-iso8859-1

	The font-name "NONE" can be used to revert to the default font.
	When setting the font for the "Normal" group, this becomes the default
	font (until the 'guifont' option is changed; the last one set is
	used).  All fonts used should be of the same character size as the
	default font!  Otherwise redrawing problems will occur.

guifg={color-name}					 
guibg={color-name}					 
	These give the foreground (guifg) and background (guibg) color to
	use in the GUI.  There are a few special names:
		NONE		no color (transparant)
		bg		use normal background color
		background	use normal background color
		fg		use normal foreground color
		foreground	use normal foreground color

							 
	Suggested color names (these are available on most systems):
	    Red		LightRed	DarkRed
	    Green	LightGreen	DarkGreen	SeaGreen
	    Blue	LightBlue	DarkBlue	SlateBlue
	    Cyan	LightCyan	DarkCyan
	    Magenta	LightMagenta	DarkMagenta
	    Yellow	LightYellow	Brown
	    Gray	LightGray	DarkGray
	    Black	White
	    Orange	Purple		Violet

	In the Win32 GUI version, additional system colors are available.  See
	|win32-colors|.

	You can also specify a color by it's Red, Green and Blue values.
	The format is "#rrggbb", where
		"rr"	is the Red value
		"bb"	is the Blue value
		"gg"	is the Green value
	All values are hexadecimal, range from "00" to "ff".  Examples:
>  :highlight Comment guifg=#11f0c3 guibg=#ff00ff

							 
These are the default highlighting groups.  These groups are used by the
'highlight' option default:
    Cursor	guibg=Green				     
    Directory   term=bold ctermfg=Blue guifg=Blue	     
    ModeMsg	term=bold cterm=bold gui=bold		     
							     
    MoreMsg	term=bold cterm=bold ctermfg=Green gui=bold guifg=Green
							     
    Question    term=standout cterm=bold ctermfg=Green gui=bold guifg=Green
    SpecialKey  term=bold ctermfg=Blue guifg=Blue	     
    StatusLine  term=reverse cterm=reverse gui=reverse	     
							     
    Title	term=bold cterm=bold ctermfg=Blue gui=bold guifg=Blue
    Visual	term=reverse cterm=reverse gui=reverse	     
    WarningMsg  term=standout ctermfg=Red guifg=Red	     
    NonText	term=bold cterm=bold gui=bold guifg=Blue     

When 'background' is set to "light", these groups are used additionally:
    Normal	term=NONE cterm=NONE gui=NONE		     
    LineNr	term=underline ctermfg=Brown guifg=Brown     
    ErrorMsg    term=standout ctermbg=LightRed guibg=Orange  
    Search	term=reverse ctermbg=Yellow guibg=Yellow     

When 'background' is set to "dark", these groups are used additionally:
    Normal	term=NONE cterm=NONE guibg=Black guifg=White  
    LineNr	term=underline ctermfg=Yellow guifg=Yellow    
    ErrorMsg    term=standout ctermbg=LightRed ctermfg=Black
    				guibg=Orange guifg=Black     
    Search	term=reverse ctermbg=Yellow ctermfg=Yellow
    				guibg=Yellow guifg=Black     

For the GUI you can use these groups to set the colors for the menu and
scrollbars.  They don't have defaults.  This doesn't work for the Win32 GUI.
    Menu						     
    Scrollbar						     


10. Linking groups					 

When you want to use the same highlighting for several syntax groups, you
can do this more easily by linking the groups into one common highlight
group, and give the color attributes only for that group.

    :highlight[!] link {from-group} {to-group}

Notes:
- If the {from-group} and/or {to-group} doesn't exist, it is created.  You
  don't get an error message for a non-existing group.
- If the {to-group} is "NONE", the link is removed from the {from-group}.
- As soon as you use a ":highlight" command for a linked group, the link is
  removed.
- If there are already highlight settings for the {from-group}, the link is
  not made, unless the '!' is given.  For a ":highlight link" command in a
  sourced file, you don't get an error message.  This can be used to skip
  links for groups that already have settings.


11. Cleaning up						 

If you want to clear the syntax stuff for the current buffer, you can use this
command:
>  :syntax clear

This command should be used when you want to switch off syntax highlighting,
or when you want to switch to using another syntax.  It's a good idea to
include this command at the beginning of a syntax file.

If you want to disable syntax highlighting for all buffers, you need to remove
the autocommands that load the syntax files:
>  :syntax off

What this command actually does, is executing the command
>  source $VIM/syntax/nosyntax.vim
See the "nosyntax.vim" file for details.  Note that this only works when $VIM
must be valid.  See |$VIM|.

To clean up specific syntax groups for the current buffer:
>  :syntax clear {group-name} ..
This removes all patterns and keywords for {group-name}.


12. Highlighting tags					 

If you want to highlight all the tags in your file, you can use the following
mappings.

	<F11>	-- Generate tags.vim file, and highlight tags.
	<F12>	-- Just highlight tags based on existing tags.vim file.

>  map <F11>  :sp tags<CR>:%s/^\([^ 	:] \).*/syntax keyword Tag \2/<CR>:wq! tags.vim<CR>/^<CR><F12>
>  map <F12>  :so tags.vim<CR>

WARNING: The longer the tags file, the slower this will be, and the more
memory Vim will consume.


13. Color xterms				   

Most color xterms have only eight colors.  They should work with these
settings:
>  :set t_Co=8
>  :set t_Sf=<Esc>[3%dm
>  :set t_Sb=<Esc>[4%dm
	[<Esc> is a real escape, type CTRL-V <Esc>]

To get 16 colors, get the newest xterm version (which should be included with
Xfree86 3.3).  You can also find the latest version at:
	http://www.clark.net/pub/dickey/xterm
This one should work with these settings:
>  :set t_Co=16
>  :set t_AB=^[[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{92}%+%;%dm
>  :set t_AF=^[[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{82}%+%;%dm
Or just set the TERM environment variable to "xterm-16color" and try if that
works.

You might want to use the X resouces (put them in your .Xdefaults file):
        XTerm*color0:                   #000000
        XTerm*color1:                   #c00000
        XTerm*color2:                   #00c000
        XTerm*color3:                   #c0c000
        XTerm*color4:                   #0000c0
        XTerm*color5:                   #c000c0
        XTerm*color6:                   #00c0c0
        XTerm*color7:                   #c0c0c0
        XTerm*color8:                   #808080
        XTerm*color9:                   #ff0000
        XTerm*color10:                  #00ff00
        XTerm*color11:                  #ffff00
        XTerm*color12:                  #0000ff
        XTerm*color13:                  #ff00ff
        XTerm*color14:                  #00ffff
        XTerm*color15:                  #ffffff
	Xterm*cursorColor:		Black

[Note: The cursorColor is required to work around a bug, which changes the
cursor color to the color of the last drawn text.  This might be fixed by the
time you read this]

To get these right away, reload the .Xdefaults file to the X Option database
Manager (you only need to do this when you just changed the .Xdefaults file):
>  xrdb -merge ~/.Xdefaults

Color Definitions

  Suggested color names (these are available on most systems):
	    Red		LightRed	DarkRed
	    Green	LightGreen	DarkGreen	SeaGreen
	    Blue	LightBlue	DarkBlue	SlateBlue
	    Cyan	LightCyan	DarkCyan
	    Magenta	LightMagenta	DarkMagenta
	    Yellow	LightYellow	Brown
	    Gray	LightGray	DarkGray
	    Black	White
	    Orange	Purple		Violet

	In the Win32 GUI version, additional system colors are available.  See
	|win32-colors|.
The following names are recognized, with the color number used:

		NR	COLOR NAME			 

		0	Black
		1	DarkBlue
		2       DarkGreen
		3       DarkCyan
		4       DarkRed
		5       DarkMagenta
		6       Brown
		7       LightGray, LightGrey, Gray, Grey
		8	DarkGray, DarkGrey
		9	Blue, LightBlue
		10	Green, LightGreen
		11	Cyan, LighCyan
		12	Red, LightRed
		13	Magenta, LightMagenta
		14	Yellow
		15	White

Reference

Vim documentation usr_44*usr_44.txt* For Vim version 6.3. Last change: 2002 Oct 10

VIM USER MANUAL - by Bram Moolenaar

Your own syntax highlighted


Vim comes with highlighting for a couple of hundred different file types. If
the file you are editing isn't included, read this chapter to find out how to
get this type of file highlighted. Also see |:syn-define| in the reference
manual.

|44.1| Basic syntax commands
|44.2| Keywords
|44.3| Matches
|44.4| Regions
|44.5| Nested items
|44.6| Following groups
|44.7| Other arguments
|44.8| Clusters
|44.9| Including another syntax file
|44.10| Synchronizing
|44.11| Installing a syntax file
|44.12| Portable syntax file layout

Next chapter: |usr_45.txt| Select your language
Previous chapter: |usr_43.txt| Using filetypes
Table of contents: |usr_toc.txt|

==============================================================================

*44.1* Basic syntax commands

Using an existing syntax file to start with will save you a lot of time. Try
finding a syntax file in $VIMRUNTIME/syntax for a language that is similar.
These files will also show you the normal layout of a syntax file. To
understand it, you need to read the following.

Let's start with the basic arguments. Before we start defining any new
syntax, we need to clear out any old definitions:

:syntax clear

This isn't required in the final syntax file, but very useful when
experimenting.

There are more simplifications in this chapter. If you are writing a syntax
file to be used by others, read all the way through the end to find out the
details.


LISTING DEFINED ITEMS

To check which syntax items are currently defined, use this command:

:syntax

You can use this to check which items have actually been defined. Quite
useful when you are experimenting with a new syntax file. It also shows the
colors used for each item, which helps to find out what is what.
To list the items in a specific syntax group use:

:syntax list {group-name}

This also can be used to list clusters (explained in |44.8|). Just include
the @ in the name.


MATCHING CASE

Some languages are not case sensitive, such as Pascal. Others, such as C, are
case sensitive. You need to tell which type you have with the following
commands:
:syntax case match
:syntax case ignore

The "match" argument means that Vim will match the case of syntax elements.
Therefore, "int" differs from "Int" and "INT". If the "ignore" argument is
used, the following are equivalent: "Procedure", "PROCEDURE" and "procedure".
The ":syntax case" commands can appear anywhere in a syntax file and affect
the syntax definitions that follow. In most cases, you have only one ":syntax
case" command in your syntax file; if you work with an unusual language that
contains both case-sensitive and non-case-sensitive elements, however, you can
scatter the ":syntax case" command throughout the file.

==============================================================================

*44.2* Keywords

The most basic syntax elements are keywords. To define a keyword, use the
following form:

:syntax keyword {group} {keyword} ...

The {group} is the name of a syntax group. With the ":highlight" command you
can assign colors to a {group}. The {keyword} argument is an actual keyword.
Here are a few examples:

:syntax keyword xType int long char
:syntax keyword xStatement if then else endif

This example uses the group names "xType" and "xStatement". By convention,
each group name is prefixed by the filetype for the language being defined.
This example defines syntax for the x language (eXample language without an
interesting name). In a syntax file for "csh" scripts the name "cshType"
would be used. Thus the prefix is equal to the value of 'filetype'.
These commands cause the words "int", "long" and "char" to be highlighted
one way and the words "if", "then", "else" and "endif" to be highlighted
another way. Now you need to connect the x group names to standard Vim
names. You do this with the following commands:

:highlight link xType Type
:highlight link xStatement Statement

This tells Vim to highlight "xType" like "Type" and "xStatement" like
"Statement". See |group-name| for the standard names.


UNUSUAL KEYWORDS

The characters used in a keyword must be in the 'iskeyword' option. If you
use another character, the word will never match. Vim doesn't give a warning
message for this.
The x language uses the '-' character in keywords. This is how it's done:

:setlocal iskeyword+=-
:syntax keyword xStatement when-not

The ":setlocal" command is used to change 'iskeyword' only for the current
buffer. Still it does change the behavior of commands like "w" and "*". If
that is not wanted, don't define a keyword but use a match (explained in the
next section).

The x language allows for abbreviations. For example, "next" can be
abbreviated to "n", "ne" or "nex". You can define them by using this command:

:syntax keyword xStatement n[ext]

This doesn't match "nextone", keywords always match whole words only.

==============================================================================

*44.3* Matches

Consider defining something a bit more complex. You want to match ordinary
identifiers. To do this, you define a match syntax item. This one matches
any word consisting of only lowercase letters:

:syntax match xIdentifier /\<\l\+\>/

Note:
Keywords overrule any other syntax item. Thus the keywords "if",
"then", etc., will be keywords, as defined with the ":syntax keyword"
commands above, even though they also match the pattern for
xIdentifier.

The part at the end is a pattern, like it's used for searching. The // is
used to surround the pattern (like how it's done in a ":substitute" command).
You can use any other character, like a plus or a quote.

Now define a match for a comment. In the x language it is anything from # to
the end of a line:

:syntax match xComment /#.*/

Since you can use any search pattern, you can highlight very complex things
with a match item. See |pattern| for help on search patterns.

==============================================================================

*44.4* Regions

In the example x language, strings are enclosed in double quotation marks (").
To highlight strings you define a region. You need a region start (double
quote) and a region end (double quote). The definition is as follows:

:syntax region xString start=/"/ end=/"/

The "start" and "end" directives define the patterns used to find the start
and end of the region. But what about strings that look like this?

"A string with a double quote (\") in it"

This creates a problem: The double quotation marks in the middle of the string
will end the region. You need to tell Vim to skip over any escaped double
quotes in the string. Do this with the skip keyword:

:syntax region xString start=/"/ skip=/\\"/ end=/"/

The double backslash matches a single backslash, since the backslash is a
special character in search patterns.

When to use a region instead of a match? The main difference is that a match
item is a single pattern, which must match as a whole. A region starts as
soon as the "start" pattern matches. Whether the "end" pattern is found or
not doesn't matter. Thus when the item depends on the "end" pattern to match,
you cannot use a region. Otherwise, regions are often simpler to define. And
it is easier to use nested items, as is explained in the next section.

==============================================================================

*44.5* Nested items

Take a look at this comment:

%Get input TODO: Skip white space

You want to highlight TODO in big yellow letters, even though it is in a
comment that is highlighted blue. To let Vim know about this, you define the
following syntax groups:

:syntax keyword xTodo TODO contained
:syntax match xComment /%.*/ contains=xTodo

In the first line, the "contained" argument tells Vim that this keyword can
exist only inside another syntax item. The next line has "contains=xTodo".
This indicates that the xTodo syntax element is inside it. The result is that
the comment line as a whole is matched with "xComment" and made blue. The
word TODO inside it is matched by xTodo and highlighted yellow (highlighting
for xTodo was setup for this).


RECURSIVE NESTING

The x language defines code blocks in curly braces. And a code block may
contain other code blocks. This can be defined this way:

:syntax region xBlock start=/{/ end=/}/ contains=xBlock

Suppose you have this text:

while i < b {
if a {
b = c;
}
}

First a xBlock starts at the { in the first line. In the second line another
{ is found. Since we are inside a xBlock item, and it contains itself, a
nested xBlock item will start here. Thus the "b = c" line is inside the
second level xBlock region. Then a } is found in the next line, which matches
with the end pattern of the region. This ends the nested xBlock. Because the
} is included in the nested region, it is hidden from the first xBlock region.
Then at the last } the first xBlock region ends.


KEEPING THE END

Consider the following two syntax items:

:syntax region xComment start=/%/ end=/$/ contained
:syntax region xPreProc start=/#/ end=/$/ contains=xComment

You define a comment as anything from % to the end of the line. A
preprocessor directive is anything from # to the end of the line. Because you
can have a comment on a preprocessor line, the preprocessor definition
includes a "contains=xComment" argument. Now look what happens with this
text:

#define X = Y % Comment text
int foo = 1;

What you see is that the second line is also highlighted as xPreProc. The
preprocessor directive should end at the end of the line. That is why
you have used "end=/$/". So what is going wrong?
The problem is the contained comment. The comment starts with % and ends
at the end of the line. After the comment ends, the preprocessor syntax
continues. This is after the end of the line has been seen, so the next
line is included as well.
To avoid this problem and to avoid a contained syntax item eating a needed
end of line, use the "keepend" argument. This takes care of
the double end-of-line matching:

:syntax region xComment start=/%/ end=/$/ contained
:syntax region xPreProc start=/#/ end=/$/ contains=xComment keepend


CONTAINING MANY ITEMS

You can use the contains argument to specify that everything can be contained.
For example:

:syntax region xList start=/\[/ end=/\]/ contains=ALL

All syntax items will be contained in this one. It also contains itself, but
not at the same position (that would cause an endless loop).
You can specify that some groups are not contained. Thus contain all
groups but the ones that are listed:

:syntax region xList start=/\[/ end=/\]/ contains=ALLBUT,xString

With the "TOP" item you can include all items that don't have a "contained"
argument. "CONTAINED" is used to only include items with a "contained"
argument. See |:syn-contains| for the details.

==============================================================================

*44.6* Following groups

The x language has statements in this form:

if (condition) then

You want to highlight the three items differently. But "(condition)" and
"then" might also appear in other places, where they get different
highlighting. This is how you can do this:

:syntax match xIf /if/ nextgroup=xIfCondition skipwhite
:syntax match xIfCondition /([^)]*)/ contained nextgroup=xThen skipwhite
:syntax match xThen /then/ contained

The "nextgroup" argument specifies which item can come next. This is not
required. If none of the items that are specified are found, nothing happens.
For example, in this text:

if not (condition) then

The "if" is matched by xIf. "not" doesn't match the specified nextgroup
xIfCondition, thus only the "if" is highlighted.

The "skipwhite" argument tells Vim that white space (spaces and tabs) may
appear in between the items. Similar arguments are "skipnl", which allows a
line break in between the items, and "skipempty", which allows empty lines.
Notice that "skipnl" doesn't skip an empty line, something must match after
the line break.

==============================================================================

*44.7* Other arguments

MATCHGROUP

When you define a region, the entire region is highlighted according to the
group name specified. To highlight the text enclosed in parentheses () with
the group xInside, for example, use the following command:

:syntax region xInside start=/(/ end=/)/

Suppose, that you want to highlight the parentheses differently. You can do
this with a lot of convoluted region statements, or you can use the
"matchgroup" argument. This tells Vim to highlight the start and end of a
region with a different highlight group (in this case, the xParen group):

:syntax region xInside matchgroup=xParen start=/(/ end=/)/

The "matchgroup" argument applies to the start or end match that comes after
it. In the previous example both start and end are highlighted with xParen.
To highlight the end with xParenEnd:

:syntax region xInside matchgroup=xParen start=/(/
\ matchgroup=xParenEnd end=/)/

A side effect of using "matchgroup" is that contained items will not match in
the start or end of the region. The example for "transparent" uses this.


TRANSPARENT

In a C language file you would like to highlight the () text after a "while"
differently from the () text after a "for". In both of these there can be
nested () items, which should be highlighted in the same way. You must make
sure the () highlighting stops at the matching ). This is one way to do this:

:syntax region cWhile matchgroup=cWhile start=/while\s*(/ end=/)/
\ contains=cCondNest
:syntax region cFor matchgroup=cFor start=/for\s*(/ end=/)/
\ contains=cCondNest
:syntax region cCondNest start=/(/ end=/)/ contained transparent

Now you can give cWhile and cFor different highlighting. The cCondNest item
can appear in either of them, but take over the highlighting of the item it is
contained in. The "transparent" argument causes this.
Notice that the "matchgroup" argument has the same group as the item
itself. Why define it then? Well, the side effect of using a matchgroup is
that contained items are not found in the match with the start item then.
This avoids that the cCondNest group matches the ( just after the "while" or
"for". If this would happen, it would span the whole text until the matching
) and the region would continue after it. Now cCondNest only matches after
the match with the start pattern, thus after the first (.


OFFSETS

Suppose you want to define a region for the text between ( and ) after an
"if". But you don't want to include the "if" or the ( and ). You can do this
by specifying offsets for the patterns. Example:

:syntax region xCond start=/if\s*(/ms=e+1 end=/)/me=s-1

The offset for the start pattern is "ms=e+1". "ms" stands for Match Start.
This defines an offset for the start of the match. Normally the match starts
where the pattern matches. "e+1" means that the match now starts at the end
of the pattern match, and then one character further.
The offset for the end pattern is "me=s-1". "me" stands for Match End.
"s-1" means the start of the pattern match and then one character back. The
result is that in this text:

if (foo == bar)

Only the text "foo == bar" will be highlighted as xCond.

More about offsets here: |:syn-pattern-offset|.


ONELINE

The "oneline" argument indicates that the region does not cross a line
boundary. For example:

:syntax region xIfThen start=/if/ end=/then/ oneline

This defines a region that starts at "if" and ends at "then". But if there is
no "then" after the "if", the region doesn't match.

Note:
When using "oneline" the region doesn't start if the end pattern
doesn't match in the same line. Without "oneline" Vim does _not_
check if there is a match for the end pattern. The region starts even
when the end pattern doesn't match in the rest of the file.


CONTINUATION LINES AND AVOIDING THEM

Things now become a little more complex. Let's define a preprocessor line.
This starts with a # in the first column and continues until the end of the
line. A line that ends with \ makes the next line a continuation line. The
way you handle this is to allow the syntax item to contain a continuation
pattern:

:syntax region xPreProc start=/^#/ end=/$/ contains=xLineContinue
:syntax match xLineContinue "\\$" contained

In this case, although xPreProc normally matches a single line, the group
contained in it (namely xLineContinue) lets it go on for more than one line.
For example, it would match both of these lines:

#define SPAM spam spam spam \
bacon and spam

In this case, this is what you want. If it is not what you want, you can call
for the region to be on a single line by adding "excludenl" to the contained
pattern. For example, you want to highlight "end" in xPreProc, but only at
the end of the line. To avoid making the xPreProc continue on the next line,
like xLineContinue does, use "excludenl" like this:

:syntax region xPreProc start=/^#/ end=/$/
\ contains=xLineContinue,xPreProcEnd
:syntax match xPreProcEnd excludenl /end$/ contained
:syntax match xLineContinue "\\$" contained

"excludenl" must be placed before the pattern. Since "xLineContinue" doesn't
have "excludenl", a match with it will extend xPreProc to the next line as
before.

==============================================================================

*44.8* Clusters

One of the things you will notice as you start to write a syntax file is that
you wind up generating a lot of syntax groups. Vim enables you to define a
collection of syntax groups called a cluster.
Suppose you have a language that contains for loops, if statements, while
loops, and functions. Each of them contains the same syntax elements: numbers
and identifiers. You define them like this:

:syntax match xFor /^for.*/ contains=xNumber,xIdent
:syntax match xIf /^if.*/ contains=xNumber,xIdent
:syntax match xWhile /^while.*/ contains=xNumber,xIdent

You have to repeat the same "contains=" every time. If you want to add
another contained item, you have to add it three times. Syntax clusters
simplify these definitions by enabling you to have one cluster stand for
several syntax groups.
To define a cluster for the two items that the three groups contain, use
the following command:

:syntax cluster xState contains=xNumber,xIdent

Clusters are used inside other syntax items just like any syntax group.
Their names start with @. Thus, you can define the three groups like this:

:syntax match xFor /^for.*/ contains=@xState
:syntax match xIf /^if.*/ contains=@xState
:syntax match xWhile /^while.*/ contains=@xState

You can add new group names to this cluster with the "add" argument:

:syntax cluster xState add=xString

You can remove syntax groups from this list as well:

:syntax cluster xState remove=xNumber

==============================================================================

*44.9* Including another syntax file

The C++ language syntax is a superset of the C language. Because you do not
want to write two syntax files, you can have the C++ syntax file read in the
one for C by using the following command:

:runtime! syntax/c.vim

The ":runtime!" command searches 'runtimepath' for all "syntax/c.vim" files.
This makes the C syntax be defined like for C files. If you have replaced the
c.vim syntax file, or added items with an extra file, these will be loaded as
well.
After loading the C syntax items the specific C++ items can be defined.
For example, add keywords that are not used in C:

:syntax keyword cppStatement new delete this friend using

This works just like in any other syntax file.

Now consider the Perl language. It consists of two distinct parts: a
documentation section in POD format, and a program written in Perl itself.
The POD section starts with "=head" and ends with "=cut".
You want to define the POD syntax in one file, and use it from the Perl
syntax file. The ":syntax include" command reads in a syntax file and stores
the elements it defined in a syntax cluster. For Perl, the statements are as
follows:

:syntax include @Pod <sfile>:p:h/pod.vim
:syntax region perlPOD start=/^=head/ end=/^=cut/ contains=@Pod

When "=head" is found in a Perl file, the perlPOD region starts. In this
region the @Pod cluster is contained. All the items defined as top-level
items in the pod.vim syntax files will match here. When "=cut" is found, the
region ends and we go back to the items defined in the Perl file.
The ":syntax include" command is clever enough to ignore a ":syntax clear"
command in the included file. And an argument such as "contains=ALL" will
only contain items defined in the included file, not in the file that includes
it.
The "<sfile>:p:h/" part uses the name of the current file (<sfile>),
expands it to a full path (:p) and then takes the head (:h). This results in
the directory name of the file. This causes the pod.vim file in the same
directory to be included.

==============================================================================

*44.10* Synchronizing

Compilers have it easy. They start at the beginning of a file and parse it
straight through. Vim does not have it so easy. It must start in the middle,
where the editing is being done. So how does it tell where it is?
The secret is the ":syntax sync" command. This tells Vim how to figure out
where it is. For example, the following command tells Vim to scan backward
for the beginning or end of a C-style comment and begin syntax coloring from
there:

:syntax sync ccomment

You can tune this processing with some arguments. The "minlines" argument
tells Vim the minimum number of lines to look backward, and "maxlines" tells
the editor the maximum number of lines to scan.
For example, the following command tells Vim to look at least 10 lines
before the top of the screen:

:syntax sync ccomment minlines=10 maxlines=500

If it cannot figure out where it is in that space, it starts looking farther
and farther back until it figures out what to do. But it looks no farther
back than 500 lines. (A large "maxlines" slows down processing. A small one
might cause synchronization to fail.)
To make synchronizing go a bit faster, tell Vim which syntax items can be
skipped. Every match and region that only needs to be used when actually
displaying text can be given the "display" argument.
By default, the comment to be found will be colored as part of the Comment
syntax group. If you want to color things another way, you can specify a
different syntax group:

:syntax sync ccomment xAltComment

If your programming language does not have C-style comments in it, you can try
another method of synchronization. The simplest way is to tell Vim to space
back a number of lines and try to figure out things from there. The following
command tells Vim to go back 150 lines and start parsing from there:

:syntax sync minlines=150

A large "minlines" value can make Vim slower, especially when scrolling
backwards in the file.
Finally, you can specify a syntax group to look for by using this command:

:syntax sync match {sync-group-name}
\ grouphere {group-name} {pattern}

This tells Vim that when it sees {pattern} the syntax group named {group-name}
begins just after the pattern given. The {sync-group-name} is used to give a
name to this synchronization specification. For example, the sh scripting
language begins an if statement with "if" and ends it with "fi":

if [ --f file.txt ] ; then
echo "File exists"
fi

To define a "grouphere" directive for this syntax, you use the following
command:

:syntax sync match shIfSync grouphere shIf "\<if\>"

The "groupthere" argument tells Vim that the pattern ends a group. For
example, the end of the if/fi group is as follows:

:syntax sync match shIfSync groupthere NONE "\<fi\>"

In this example, the NONE tells Vim that you are not in any special syntax
region. In particular, you are not inside an if block.

You also can define matches and regions that are with no "grouphere" or
"groupthere" arguments. These groups are for syntax groups skipped during
synchronization. For example, the following skips over anything inside {},
even if it would normally match another synchronization method:

:syntax sync match xSpecial /{.*}/

More about synchronizing in the reference manual: |:syn-sync|.

==============================================================================

*44.11* Installing a syntax file

When your new syntax file is ready to be used, drop it in a "syntax" directory
in 'runtimepath'. For Unix that would be "~/.vim/syntax".
The name of the syntax file must be equal to the file type, with ".vim"
added. Thus for the x language, the full path of the file would be:

~/.vim/syntax/x.vim

You must also make the file type be recognized. See |43.2|.

If your file works well, you might want to make it available to other Vim
users. First read the next section to make sure your file works well for
others. Then e-mail it to the Vim maintainer: <maintainer@vim.org>. Also
explain how the filetype can be detected. With a bit of luck your file will
be included in the next Vim version!


ADDING TO AN EXISTING SYNTAX FILE

We were assuming you were adding a completely new syntax file. When an existing
syntax file works, but is missing some items, you can add items in a separate
file. That avoids changing the distributed syntax file, which will be lost
when installing a new version of Vim.
Write syntax commands in your file, possibly using group names from the
existing syntax. For example, to add new variable types to the C syntax file:

:syntax keyword cType off_t uint

Write the file with the same name as the original syntax file. In this case
"c.vim". Place it in a directory near the end of 'runtimepath'. This makes
it loaded after the original syntax file. For Unix this would be:

~/.vim/after/syntax/c.vim

==============================================================================

*44.12* Portable syntax file layout

Wouldn't it be nice if all Vim users exchange syntax files? To make this
possible, the syntax file must follow a few guidelines.

Start with a header that explains what the syntax file is for, who maintains
it and when it was last updated. Don't include too much information about
changes history, not many people will read it. Example:

" Vim syntax file
" Language: C
" Maintainer: Bram Moolenaar <Bram@vim.org>
" Last Change: 2001 Jun 18
" Remark: Included by the C++ syntax.

Use the same layout as the other syntax files. Using an existing syntax file
as an example will save you a lot of time.

Choose a good, descriptive name for your syntax file. Use lowercase letters
and digits. Don't make it too long, it is used in many places: The name of
the syntax file "name.vim", 'filetype', b:current_syntax the start of each
syntax group (nameType, nameStatement, nameString, etc).

Start with a check for "b:current_syntax". If it is defined, some other
syntax file, earlier in 'runtimepath' was already loaded. To be compatible
with Vim 5.8 use:

if version < 600
syntax clear
elseif exists("b:current_syntax")
finish
endif

Set "b:current_syntax" to the name of the syntax at the end. Don't forget
that included files do this too, you might have to reset "b:current_syntax" if
you include two files.

If you want your syntax file to work with Vim 5.x, add a check for v:version.
See yacc.vim for an example.

Do not include anything that is a user preference. Don't set 'tabstop',
'expandtab', etc. These belong in a filetype plugin.

Do not include mappings or abbreviations. Only include setting 'iskeyword' if
it is really necessary for recognizing keywords.

Avoid using specific colors. Link to the standard highlight groups whenever
possible. Don't forget that some people use a different background color, or
have only eight colors available.
For backwards compatibility with Vim 5.8 this construction is used:

if version >= 508 || !exists("did_c_syn_inits")
if version < 508
let did_c_syn_inits = 1
command -nargs=+ HiLink hi link <args>
else
command -nargs=+ HiLink hi def link <args>
endif

HiLink nameString String
HiLink nameNumber Number
... etc ...

delcommand HiLink
endif

Add the "display" argument to items that are not used when syncing, to speed
up scrolling backwards and CTRL-L.



Etc

FAIR USE NOTICE This site contains copyrighted material the use of which has not always been specifically authorized by the copyright owner. We are making such material available in our efforts to advance understanding of environmental, political, human rights, economic, democracy, scientific, and social justice issues, etc. We believe this constitutes a 'fair use' of any such copyrighted material as provided for in section 107 of the US Copyright Law. In accordance with Title 17 U.S.C. Section 107, the material on this site is distributed without profit exclusivly for research and educational purposes.   If you wish to use copyrighted material from this site for purposes of your own that go beyond 'fair use', you must obtain permission from the copyright owner. 

ABUSE: IPs or network segments from which we detect a stream of probes might be blocked for no less then 90 days. Multiple types of probes increase this period.  

Society

Groupthink : Two Party System as Polyarchy : Corruption of Regulators : Bureaucracies : Understanding Micromanagers and Control Freaks : Toxic Managers :   Harvard Mafia : Diplomatic Communication : Surviving a Bad Performance Review : Insufficient Retirement Funds as Immanent Problem of Neoliberal Regime : PseudoScience : Who Rules America : Neoliberalism  : The Iron Law of Oligarchy : Libertarian Philosophy

Quotes

War and Peace : Skeptical Finance : John Kenneth Galbraith :Talleyrand : Oscar Wilde : Otto Von Bismarck : Keynes : George Carlin : Skeptics : Propaganda  : SE quotes : Language Design and Programming Quotes : Random IT-related quotesSomerset Maugham : Marcus Aurelius : Kurt Vonnegut : Eric Hoffer : Winston Churchill : Napoleon Bonaparte : Ambrose BierceBernard Shaw : Mark Twain Quotes

Bulletin:

Vol 25, No.12 (December, 2013) Rational Fools vs. Efficient Crooks The efficient markets hypothesis : Political Skeptic Bulletin, 2013 : Unemployment Bulletin, 2010 :  Vol 23, No.10 (October, 2011) An observation about corporate security departments : Slightly Skeptical Euromaydan Chronicles, June 2014 : Greenspan legacy bulletin, 2008 : Vol 25, No.10 (October, 2013) Cryptolocker Trojan (Win32/Crilock.A) : Vol 25, No.08 (August, 2013) Cloud providers as intelligence collection hubs : Financial Humor Bulletin, 2010 : Inequality Bulletin, 2009 : Financial Humor Bulletin, 2008 : Copyleft Problems Bulletin, 2004 : Financial Humor Bulletin, 2011 : Energy Bulletin, 2010 : Malware Protection Bulletin, 2010 : Vol 26, No.1 (January, 2013) Object-Oriented Cult : Political Skeptic Bulletin, 2011 : Vol 23, No.11 (November, 2011) Softpanorama classification of sysadmin horror stories : Vol 25, No.05 (May, 2013) Corporate bullshit as a communication method  : Vol 25, No.06 (June, 2013) A Note on the Relationship of Brooks Law and Conway Law

History:

Fifty glorious years (1950-2000): the triumph of the US computer engineering : Donald Knuth : TAoCP and its Influence of Computer Science : Richard Stallman : Linus Torvalds  : Larry Wall  : John K. Ousterhout : CTSS : Multix OS Unix History : Unix shell history : VI editor : History of pipes concept : Solaris : MS DOSProgramming Languages History : PL/1 : Simula 67 : C : History of GCC developmentScripting Languages : Perl history   : OS History : Mail : DNS : SSH : CPU Instruction Sets : SPARC systems 1987-2006 : Norton Commander : Norton Utilities : Norton Ghost : Frontpage history : Malware Defense History : GNU Screen : OSS early history

Classic books:

The Peter Principle : Parkinson Law : 1984 : The Mythical Man-MonthHow to Solve It by George Polya : The Art of Computer Programming : The Elements of Programming Style : The Unix Haterís Handbook : The Jargon file : The True Believer : Programming Pearls : The Good Soldier Svejk : The Power Elite

Most popular humor pages:

Manifest of the Softpanorama IT Slacker Society : Ten Commandments of the IT Slackers Society : Computer Humor Collection : BSD Logo Story : The Cuckoo's Egg : IT Slang : C++ Humor : ARE YOU A BBS ADDICT? : The Perl Purity Test : Object oriented programmers of all nations : Financial Humor : Financial Humor Bulletin, 2008 : Financial Humor Bulletin, 2010 : The Most Comprehensive Collection of Editor-related Humor : Programming Language Humor : Goldman Sachs related humor : Greenspan humor : C Humor : Scripting Humor : Real Programmers Humor : Web Humor : GPL-related Humor : OFM Humor : Politically Incorrect Humor : IDS Humor : "Linux Sucks" Humor : Russian Musical Humor : Best Russian Programmer Humor : Microsoft plans to buy Catholic Church : Richard Stallman Related Humor : Admin Humor : Perl-related Humor : Linus Torvalds Related humor : PseudoScience Related Humor : Networking Humor : Shell Humor : Financial Humor Bulletin, 2011 : Financial Humor Bulletin, 2012 : Financial Humor Bulletin, 2013 : Java Humor : Software Engineering Humor : Sun Solaris Related Humor : Education Humor : IBM Humor : Assembler-related Humor : VIM Humor : Computer Viruses Humor : Bright tomorrow is rescheduled to a day after tomorrow : Classic Computer Humor

The Last but not Least


Copyright © 1996-2016 by Dr. Nikolai Bezroukov. www.softpanorama.org was created as a service to the UN Sustainable Development Networking Programme (SDNP) in the author free time. This document is an industrial compilation designed and created exclusively for educational use and is distributed under the Softpanorama Content License.

The site uses AdSense so you need to be aware of Google privacy policy. You you do not want to be tracked by Google please disable Javascript for this site. This site is perfectly usable without Javascript.

Original materials copyright belong to respective owners. Quotes are made for educational purposes only in compliance with the fair use doctrine.

FAIR USE NOTICE This site contains copyrighted material the use of which has not always been specifically authorized by the copyright owner. We are making such material available to advance understanding of computer science, IT technology, economic, scientific, and social issues. We believe this constitutes a 'fair use' of any such copyrighted material as provided by section 107 of the US Copyright Law according to which such material can be distributed without profit exclusively for research and educational purposes.

This is a Spartan WHYFF (We Help You For Free) site written by people for whom English is not a native language. Grammar and spelling errors should be expected. The site contain some broken links as it develops like a living tree...

You can use PayPal to make a contribution, supporting development of this site and speed up access. In case softpanorama.org is down you can use the at softpanorama.info

Disclaimer:

The statements, views and opinions presented on this web page are those of the author (or referenced source) and are not endorsed by, nor do they necessarily reflect, the opinions of the author present and former employers, SDNP or any other organization the author may be associated with. We do not warrant the correctness of the information provided or its fitness for any purpose.

Last modified: September 12, 2017