diff options
Diffstat (limited to 'runtime/doc/syntax.txt')
| -rw-r--r-- | runtime/doc/syntax.txt | 199 |
1 files changed, 117 insertions, 82 deletions
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index bd5a4f1926..e1053b54f1 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -188,28 +188,27 @@ thing. These are then linked to a highlight group that specifies the color. A syntax group name doesn't specify any color or attributes itself. The name for a highlight or syntax group must consist of ASCII letters, -digits, underscores, periods and `@` characters. As a regexp it is -`[a-zA-Z0-9_.@]*`. The maximum length of a group name is about 200 bytes. -*E1249* +digits, underscores, dots, hyphens, or `@`. As a regexp: `[a-zA-Z0-9_.@-]*`. +The maximum length of a group name is about 200 bytes. *E1249* To be able to allow each user to pick their favorite set of colors, there must be preferred names for highlight groups that are common for many languages. These are the suggested group names (if syntax highlighting works properly you can see the actual color, except for "Ignore"): - *Comment any comment + Comment any comment - *Constant any constant + 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 + Identifier any variable name Function function name (also: methods for classes) - *Statement any statement + Statement any statement Conditional if, then, else, endif, switch, etc. Repeat for, do, while, etc. Label case, default, etc. @@ -217,31 +216,31 @@ you can see the actual color, except for "Ignore"): Keyword any other keyword Exception try, catch, throw - *PreProc generic Preprocessor + PreProc generic Preprocessor Include preprocessor #include Define preprocessor #define Macro same as Define PreCondit preprocessor #if, #else, #endif, etc. - *Type int, long, char, etc. + Type int, long, char, etc. StorageClass static, register, volatile, etc. Structure struct, union, enum, etc. Typedef A typedef - *Special any special symbol + Special any special symbol SpecialChar special character in a constant Tag you can use CTRL-] on this Delimiter character that needs attention SpecialComment special things inside a comment Debug debugging statements - *Underlined text that stands out, HTML links + Underlined text that stands out, HTML links - *Ignore left blank, hidden |hl-Ignore| + Ignore left blank, hidden |hl-Ignore| - *Error any erroneous construct + Error any erroneous construct - *Todo anything that needs extra attention; mostly the + Todo anything that needs extra attention; mostly the keywords TODO FIXME and XXX The names marked with * are the preferred groups; the others are minor groups. @@ -560,7 +559,7 @@ The method used to prevent copying in the generated page depends on the value of |g:html_use_input_for_pc|. *g:html_use_input_for_pc* -Default: "fallback" +Default: "none" If |g:html_prevent_copy| is non-empty, then: When "all", read-only <input> elements are used in place of normal text for @@ -893,7 +892,7 @@ nasm_no_warn potentially risky syntax not as ToDo ASPPERL and ASPVBS *ft-aspperl-syntax* *ft-aspvbs-syntax* -*.asp and *.asa files could be either Perl or Visual Basic script. Since it's +`*.asp` and `*.asa` files could be either Perl or Visual Basic script. Since it's hard to detect this you can set two global variables to tell Vim what you are using. For Perl script use: > :let g:filetype_asa = "aspperl" @@ -979,7 +978,7 @@ Variable Highlight ~ *c_ansi_typedefs* ... but do standard ANSI types *c_ansi_constants* ... but do standard ANSI constants *c_no_utf* don't highlight \u and \U in strings -*c_syntax_for_h* for *.h files use C syntax instead of C++ and use objc +*c_syntax_for_h* for `*.h` files use C syntax instead of C++ and use objc syntax instead of objcpp *c_no_if0* don't highlight "#if 0" blocks as comments *c_no_cformat* don't highlight %-formats in strings @@ -987,7 +986,7 @@ Variable Highlight ~ *c_no_c11* don't highlight C11 standard items *c_no_bsd* don't highlight BSD specific types -When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will +When 'foldmethod' is set to "syntax" then `/* */` comments and { } blocks will become a fold. If you don't want comments to become a fold use: > :let c_no_comment_fold = 1 "#if 0" blocks are also folded, unless: > @@ -1034,7 +1033,7 @@ CH *ch.vim* *ft-ch-syntax* C/C++ interpreter. Ch has similar syntax highlighting to C and builds upon the C syntax file. See |c.vim| for all the settings that are available for C. -By setting a variable you can tell Vim to use Ch syntax for *.h files, instead +By setting a variable you can tell Vim to use Ch syntax for `*.h` files, instead of C or C++: > :let ch_syntax_for_h = 1 @@ -1271,18 +1270,32 @@ When not set 4 is used. DOSBATCH *dosbatch.vim* *ft-dosbatch-syntax* -There is one option with highlighting DOS batch files. This covers new -extensions to the Command Interpreter introduced with Windows 2000 and -is controlled by the variable dosbatch_cmdextversion. For Windows NT -this should have the value 1, and for Windows 2000 it should be 2. +Select the set of Windows Command interpreter extensions that should be +supported with the variable dosbatch_cmdextversion. For versions of Windows +NT (before Windows 2000) this should have the value of 1. For Windows 2000 +and later it should be 2. Select the version you want with the following line: > :let dosbatch_cmdextversion = 1 If this variable is not defined it defaults to a value of 2 to support -Windows 2000. +Windows 2000 and later. -A second option covers whether *.btm files should be detected as type +The original MS-DOS supports an idiom of using a double colon (::) as an +alternative way to enter a comment line. This idiom can be used with the +current Windows Command Interpreter, but it can lead to problems when used +inside ( ... ) command blocks. You can find a discussion about this on +Stack Overflow - + +https://stackoverflow.com/questions/12407800/which-comment-style-should-i-use-in-batch-files + +To allow the use of the :: idiom for comments in the Windows Command +Interpreter or working with MS-DOS bat files, set the +dosbatch_colons_comment variable to anything: > + + :let dosbatch_colons_comment = 1 + +There is an option that covers whether `*.btm` files should be detected as type "dosbatch" (MS-DOS batch files) or type "btm" (4DOS batch files). The latter is used by default. You may select the former with the following line: > @@ -1413,13 +1426,13 @@ Euphoria version 3.1.1 (https://www.rapideuphoria.com/) is still necessary for developing applications for the DOS platform, which Euphoria version 4 (https://www.openeuphoria.org/) does not support. -The following file extensions are auto-detected as Euphoria file type: +The following file extensions are auto-detected as Euphoria file type: > *.e, *.eu, *.ew, *.ex, *.exu, *.exw *.E, *.EU, *.EW, *.EX, *.EXU, *.EXW To select syntax highlighting file for Euphoria, as well as for -auto-detecting the *.e and *.E file extensions as Euphoria file type, +auto-detecting the `*.e` and `*.E` file extensions as Euphoria file type, add the following line to your startup file: > :let g:filetype_euphoria = "euphoria3" @@ -1428,7 +1441,7 @@ add the following line to your startup file: > :let g:filetype_euphoria = "euphoria4" -Elixir and Euphoria share the *.ex file extension. If the filetype is +Elixir and Euphoria share the `*.ex` file extension. If the filetype is specifically set as Euphoria with the g:filetype_euphoria variable, or the file is determined to be Euphoria based on keywords in the file, then the filetype will be set as Euphoria. Otherwise, the filetype will default to @@ -1455,11 +1468,11 @@ ELIXIR *elixir.vim* *ft-elixir-syntax* Elixir is a dynamic, functional language for building scalable and maintainable applications. -The following file extensions are auto-detected as Elixir file types: +The following file extensions are auto-detected as Elixir file types: > *.ex, *.exs, *.eex, *.leex, *.lock -Elixir and Euphoria share the *.ex file extension. If the filetype is +Elixir and Euphoria share the `*.ex` file extension. If the filetype is specifically set as Euphoria with the g:filetype_euphoria variable, or the file is determined to be Euphoria based on keywords in the file, then the filetype will be set as Euphoria. Otherwise, the filetype will default to @@ -1529,9 +1542,10 @@ example, FORM files, use this in your startup vimrc: > FORTH *forth.vim* *ft-forth-syntax* -Files matching "*.fs" could be F# or Forth. If the automatic detection -doesn't work for you, or you don't edit F# at all, use this in your -startup vimrc: > +Files matching "*.f" could be Fortran or Forth and those matching "*.fs" could +be F# or Forth. If the automatic detection doesn't work for you, or you don't +edit F# or Fortran at all, use this in your startup vimrc: > + :let filetype_f = "forth" :let filetype_fs = "forth" @@ -1891,7 +1905,7 @@ IA64 *ia64.vim* *intel-itanium* *ft-ia64-syntax* Highlighting for the Intel Itanium 64 assembly language. See |asm.vim| for how to recognize this filetype. -To have *.inc files be recognized as IA64, add this to your vimrc file: > +To have `*.inc` files be recognized as IA64, add this to your vimrc file: > :let g:filetype_inc = "ia64" @@ -2104,18 +2118,18 @@ set "lite_minlines" to the value you desire. Example: > LPC *lpc.vim* *ft-lpc-syntax* LPC stands for a simple, memory-efficient language: Lars Pensjö C. The -file name of LPC is usually *.c. Recognizing these files as LPC would bother +file name of LPC is usually `*.c`. Recognizing these files as LPC would bother users writing only C programs. If you want to use LPC syntax in Vim, you should set a variable in your vimrc file: > :let lpc_syntax_for_c = 1 If it doesn't work properly for some particular C or LPC files, use a -modeline. For a LPC file: +modeline. For a LPC file: > // vim:set ft=lpc: -For a C file that is recognized as LPC: +For a C file that is recognized as LPC: > // vim:set ft=c: @@ -2139,7 +2153,7 @@ For LPC4 series of LPC: > For uLPC series of LPC: uLPC has been developed to Pike, so you should use Pike syntax -instead, and the name of your source file should be *.pike +instead, and the name of your source file should be `*.pike` LUA *lua.vim* *ft-lua-syntax* @@ -2147,7 +2161,7 @@ LUA *lua.vim* *ft-lua-syntax* The Lua syntax file can be used for versions 4.0, 5.0, 5.1 and 5.2 (5.2 is the default). You can select one of these versions using the global variables lua_version and lua_subversion. For example, to activate Lua -5.1 syntax highlighting, set the variables like this: +5.1 syntax highlighting, set the variables like this: > :let lua_version = 5 :let lua_subversion = 1 @@ -2216,7 +2230,7 @@ the start of a region, for example 500 lines: > MATHEMATICA *mma.vim* *ft-mma-syntax* *ft-mathematica-syntax* -Empty *.m files will automatically be presumed to be Matlab files unless you +Empty `*.m` files will automatically be presumed to be Matlab files unless you have the following in your vimrc: > let filetype_m = "mma" @@ -2423,7 +2437,7 @@ keywords, etc): > The option pascal_symbol_operator controls whether symbol operators such as +, -*, .., etc. are displayed using the Operator color or not. To colorize symbol +`*`, .., etc. are displayed using the Operator color or not. To colorize symbol operators, add the following line to your startup file: > :let pascal_symbol_operator=1 @@ -2586,7 +2600,7 @@ x = 0 to sync from start. PLAINTEX *plaintex.vim* *ft-plaintex-syntax* TeX is a typesetting language, and plaintex is the file type for the "plain" -variant of TeX. If you never want your *.tex files recognized as plain TeX, +variant of TeX. If you never want your `*.tex` files recognized as plain TeX, see |ft-tex-plugin|. This syntax file has the option > @@ -2742,17 +2756,25 @@ For highlighted doctests and code inside: > :let python_no_doctest_highlight = 1 or > :let python_no_doctest_code_highlight = 1 -(first option implies second one). +The first option implies the second one. For highlighted trailing whitespace and mix of spaces and tabs: > :let python_space_error_highlight = 1 -If you want all possible Python highlighting (the same as setting the -preceding last option and unsetting all other ones): > +If you want all possible Python highlighting: > :let python_highlight_all = 1 +This has the same effect as setting python_space_error_highlight and +unsetting all the other ones. + +If you use Python 2 or straddling code (Python 2 and 3 compatible), +you can enforce the use of an older syntax file with support for +Python 2 and up to Python 3.5. > + :let python_use_python2_syntax = 1 +This option will exclude all modern Python 3.6 or higher features. + +Note: Only existence of these options matters, not their value. + You can replace 1 above with anything. -Note: Only existence of these options matter, not their value. You can replace - 1 above with anything. QUAKE *quake.vim* *ft-quake-syntax* @@ -3127,7 +3149,7 @@ The syntax/sh.vim file provides several levels of syntax-based folding: > let g:sh_fold_enabled= 1 (enable function folding) let g:sh_fold_enabled= 2 (enable heredoc folding) let g:sh_fold_enabled= 4 (enable if/do/for folding) -> + then various syntax items (ie. HereDocuments and function bodies) become syntax-foldable (see |:syn-fold|). You also may add these together to get multiple types of folding: > @@ -3248,7 +3270,7 @@ This covers the shell named "tcsh". It is a superset of csh. See |csh.vim| for how the filetype is detected. Tcsh does not allow \" in strings unless the "backslash_quote" shell variable -is set. If you want VIM to assume that no backslash quote constructs exist +is set. If you want VIM to assume that no backslash quote constructs exist add this line to your vimrc: > :let tcsh_backslash_quote = 0 @@ -3424,8 +3446,8 @@ has a starred form (ie. eqnarray*). *tex-style* *b:tex_stylish* Tex: Starting a New Style? ~ -One may use "\makeatletter" in *.tex files, thereby making the use of "@" in -commands available. However, since the *.tex file doesn't have one of the +One may use "\makeatletter" in `*.tex` files, thereby making the use of "@" in +commands available. However, since the `*.tex` file doesn't have one of the following suffices: sty cls clo dtx ltx, the syntax highlighting will flag such use of @ as an error. To solve this: > @@ -3469,7 +3491,7 @@ substitution will not be made. Tex: Controlling iskeyword~ Normally, LaTeX keywords support 0-9, a-z, A-z, and 192-255 only. Latex -keywords don't support the underscore - except when in *.sty files. The +keywords don't support the underscore - except when in `*.sty` files. The syntax highlighting script handles this with the following logic: * If g:tex_stylish exists and is 1 @@ -3676,11 +3698,12 @@ The syntax script for zsh allows for syntax-based folding: > Vim understands three types of syntax items: 1. Keyword - It can only contain keyword characters, according to the 'iskeyword' - option. It cannot contain other syntax items. It will only match with a - complete word (there are no keyword characters before or after the match). - The keyword "if" would match in "if(a=b)", but not in "ifdef x", because - "(" is not a keyword character and "d" is. + It can only contain keyword characters, according to the characters + specified with |:syn-iskeyword| or the 'iskeyword' option. It cannot + contain other syntax items. It will only match with a complete word (there + are no keyword characters before or after the match). The keyword "if" + would match in "if(a=b)", but not in "ifdef x", because "(" is not a + keyword character and "d" is. 2. Match This is a match with a single regexp pattern. @@ -3692,7 +3715,7 @@ Vim understands three types of syntax items: 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, +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. @@ -3784,7 +3807,7 @@ SYNTAX ISKEYWORD SETTING *:syn-iskeyword* clear: Syntax specific iskeyword setting is disabled and the buffer-local 'iskeyword' setting is used. - {option} Set the syntax 'iskeyword' option to a new value. + {option} Set the syntax 'iskeyword' option to a new value. Example: > :syntax iskeyword @,48-57,192-255,$,_ @@ -4450,19 +4473,19 @@ Notes: matched. This doesn't work: "a\nb"ms=e. You can make the highlighting start in another line, this does work: "a\nb"hs=e. -Example (match a comment but don't highlight the /* and */): > +Example (match a comment but don't highlight the `/* and */`): >vim :syntax region Comment start="/\*"hs=e+1 end="\*/"he=s-1 -< +< > /* this is a comment */ ^^^^^^^^^^^^^^^^^^^ 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 < +A more complicated Example: >vim + :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 sssrrreee highlight start/region/end ("Foo", "Exa" and "Bar") - +< Leading context *:syn-lc* *:syn-leading* *:syn-context* Note: This is an obsolete feature, only included for backwards compatibility @@ -4762,7 +4785,7 @@ matches, nextgroup, etc. But there are a few differences: - When a match with a sync pattern is found, the rest of the line (or group of continued 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 /* this */, the last "*/" is used). + (e.g., in a C-comment like `/* this */`, 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 @@ -4872,8 +4895,8 @@ in their own color. output "default". :colo[rscheme] {name} Load color scheme {name}. This searches 'runtimepath' - for the file "colors/{name}.(vim|lua)". The first one that - is found is loaded. + for the file "colors/{name}.{vim,lua}". The first one + that is found is loaded. Note: "colors/{name}.vim" is tried first. Also searches all plugins in 'packpath', first below "start" and then under "opt". @@ -4997,7 +5020,7 @@ stop={term-list} *term-list* *highlight-stop* highlighted area. This should undo the "start" argument. Otherwise the screen will look messed up. - {term-list} is a a string with escape sequences. This is any string of + {term-list} is 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: @@ -5035,16 +5058,16 @@ ctermbg={color-nr} *ctermbg* The number under "NR-16" is used for 16-color terminals ('t_Co' greater than or equal to 16). The number under "NR-8" is used for - 8-color terminals ('t_Co' less than 16). The '*' indicates that the + 8-color terminals ('t_Co' less than 16). The "*" indicates that the bold attribute is set for ctermfg. In many 8-color terminals (e.g., "linux"), this causes the bright colors to appear. This doesn't work - for background colors! Without the '*' the bold attribute is removed. + for background colors! Without the "*" the bold attribute is removed. If you want to set the bold attribute in a different way, put a "cterm=" argument AFTER the "ctermfg=" or "ctermbg=" argument. Or use a number instead of a color name. Note that for 16 color ansi style terminals (including xterms), the - numbers in the NR-8 column is used. Here "*" means "add 8" so that + numbers in the NR-8 column is used. Here "*" means "add 8" so that Blue is 12, DarkGray is 8 etc. Note that for some color terminals these names may result in the wrong @@ -5165,7 +5188,7 @@ Conceal Placeholder characters substituted for concealed *hl-CurSearch* CurSearch Used for highlighting a search pattern under the cursor (see 'hlsearch'). - *hl-Cursor* + *hl-Cursor* *hl-lCursor* Cursor Character under the cursor. lCursor Character under the cursor when |language-mapping| is used (see 'guicursor'). @@ -5246,12 +5269,26 @@ NonText '@' at the end of the window, characters from 'showbreak' Normal Normal text. *hl-NormalFloat* NormalFloat Normal text in floating windows. + *hl-FloatBorder* +FloatBorder Border of floating windows. + *hl-FloatTitle* +FloatTitle Title of floating windows. + *hl-FloatFooter* +FloatFooter Footer of floating windows. *hl-NormalNC* NormalNC Normal text in non-current windows. *hl-Pmenu* Pmenu Popup menu: Normal item. *hl-PmenuSel* PmenuSel Popup menu: Selected item. + *hl-PmenuKind* +PmenuKind Popup menu: Normal item "kind". + *hl-PmenuKindSel* +PmenuKindSel Popup menu: Selected item "kind". + *hl-PmenuExtra* +PmenuExtra Popup menu: Normal item "extra text". + *hl-PmenuExtraSel* +PmenuExtraSel Popup menu: Selected item "extra text". *hl-PmenuSbar* PmenuSbar Popup menu: Scrollbar. *hl-PmenuThumb* @@ -5285,8 +5322,6 @@ SpellRare Word that is recognized by the spellchecker as one that is StatusLine Status line of current window. *hl-StatusLineNC* StatusLineNC Status lines of not-current windows. - Note: If this is equal to "StatusLine", Vim will use "^^^" in - the status line of the current window. *hl-TabLine* TabLine Tab pages line, not active tab page label. *hl-TabLineFill* @@ -5446,14 +5481,14 @@ memory Vim will consume. Only highlighting typedefs, unions and structs can be done too. For this you must use Universal Ctags (https://ctags.io) or Exuberant ctags. -Put these lines in your Makefile: +Put these lines in your Makefile: > -# Make a highlight file for types. Requires Universal/Exuberant ctags and awk -types: types.vim -types.vim: *.[ch] - ctags --c-kinds=gstu -o- *.[ch] |\ - awk 'BEGIN{printf("syntax keyword Type\t")}\ - {printf("%s ", $$1)}END{print ""}' > $@ + # Make a highlight file for types. Requires Universal/Exuberant ctags and awk + types: types.vim + types.vim: *.[ch] + ctags --c-kinds=gstu -o- *.[ch] |\ + awk 'BEGIN{printf("syntax keyword Type\t")}\ + {printf("%s ", $$1)}END{print ""}' > $@ And put these lines in your vimrc: > |