summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_44.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_44.txt')
-rw-r--r--runtime/doc/usr_44.txt708
1 files changed, 708 insertions, 0 deletions
diff --git a/runtime/doc/usr_44.txt b/runtime/doc/usr_44.txt
new file mode 100644
index 0000000..11a0286
--- /dev/null
+++ b/runtime/doc/usr_44.txt
@@ -0,0 +1,708 @@
+*usr_44.txt* For Vim version 9.0. Last change: 2017 May 06
+
+ 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 parts of 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. A Perl script 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 and 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
+
+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.
+
+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:noet:ft=help:norl: