Portable Syntax File Layout

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: ~/.config/nvim/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:

This section details guidelines for creating portable syntax files for Vim, emphasizing a header with file information, consistent layout with existing files, and a descriptive file name. It advises to check for 'b:current_syntax' to avoid conflicts with other syntax files, set 'b:current_syntax' at the end, and exclude user preferences like tab settings. It also stresses using distinct group names for highlighted items and linking them to standard highlight groups for color scheme compatibility, utilizing 'hi def link'. Finally, it recommends adding the 'display' argument to items not used during synchronization to improve performance.