summaryrefslogtreecommitdiff
path: root/runtime/doc/usr_44.txt
blob: 845ca3c6d50c4bbd930722fd9175ab918cf48e51 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
*usr_44.txt*	For Vim version 7.0f.  Last change: 2006 Apr 24

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

	if exists("b:current_syntax")
	  finish
	endif

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.

To allow users select their own preferred colors, make a different group name
for every kind of highlighted item.  Then link each of them to one of the
standard highlight groups.  That will make it work with every color scheme.
If you select specific colors it will look bad with some color schemes.  And
don't forget that some people use a different background color, or have only
eight colors available.

For the linking use "hi def link", so that the user can select different
highlighting before your syntax file is loaded.  Example: >

	  hi def link nameString	String
	  hi def link nameNumber	Number
	  hi def link nameCommand	Statement
	  ... etc ...

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

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

Next chapter: |usr_45.txt|  Select your language

Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: