# Vimhelp User Manual Chapter 44: Your own syntax highlighted # Copyright (C) 1988-2006 Bram Moolenaar # Florian 'eix' Rehnisch , 2008 # #, fuzzy msgid "" msgstr "" "Project-Id-Version: vimhelp 7.0.122\n" "POT-Creation-Date: 2008-04-10 17:32+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf8\n" "Content-Transfer-Encoding: 8bit" # type: Plain text #: usr_44.txt:2 #, no-wrap msgid "*usr_44.txt*\tFor Vim version 7.0. Last change: 2006 Apr 24\n" msgstr "" # type: Plain text #: usr_44.txt:4 #, no-wrap msgid "\t\t VIM USER MANUAL - by Bram Moolenaar\n" msgstr "" # type: Plain text #: usr_44.txt:6 #, no-wrap msgid "\t\t\t Your own syntax highlighted\n" msgstr "" # type: Plain text #: usr_44.txt:12 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:25 msgid "" "|44.1|\tBasic syntax commands |44.2|\tKeywords |44.3|\tMatches " "|44.4|\tRegions |44.5|\tNested items |44.6|\tFollowing groups |44.7|\tOther " "arguments |44.8|\tClusters |44.9|\tIncluding another syntax file " "|44.10|\tSynchronizing |44.11|\tInstalling a syntax file |44.12|\tPortable " "syntax file layout" msgstr "" # type: Plain text #: usr_44.txt:29 #, no-wrap msgid "" " Next chapter: |usr_45.txt| Select your language\n" " Previous chapter: |usr_43.txt| Using filetypes\n" "Table of contents: |usr_toc.txt|\n" msgstr "" # type: Plain text #: usr_44.txt:30 usr_44.txt:85 usr_44.txt:139 usr_44.txt:166 usr_44.txt:196 usr_44.txt:291 usr_44.txt:321 usr_44.txt:448 usr_44.txt:486 usr_44.txt:530 usr_44.txt:609 usr_44.txt:645 usr_44.txt:715 #, no-wrap msgid "==============================================================================\n" msgstr "" # type: Plain text #: usr_44.txt:32 #, no-wrap msgid "*44.1*\tBasic syntax commands\n" msgstr "" # type: Plain text #: usr_44.txt:37 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:40 msgid "" "Let's start with the basic arguments. Before we start defining any new " "syntax, we need to clear out any old definitions: >" msgstr "" # type: Plain text #: usr_44.txt:42 #, no-wrap msgid "\t:syntax clear\n" msgstr "" # type: Plain text #: usr_44.txt:45 msgid "" "This isn't required in the final syntax file, but very useful when " "experimenting." msgstr "" # type: Plain text #: usr_44.txt:49 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:52 msgid "LISTING DEFINED ITEMS" msgstr "" # type: Plain text #: usr_44.txt:54 msgid "To check which syntax items are currently defined, use this command: >" msgstr "" # type: Plain text #: usr_44.txt:56 #, no-wrap msgid "\t:syntax\n" msgstr "" # type: Plain text #: usr_44.txt:61 #, no-wrap msgid "" "You can use this to check which items have actually been defined. Quite\n" "useful when you are experimenting with a new syntax file. It also shows " "the\n" "colors used for each item, which helps to find out what is what.\n" " To list the items in a specific syntax group use: >\n" msgstr "" # type: Plain text #: usr_44.txt:63 #, no-wrap msgid "\t:syntax list {group-name}\n" msgstr "" # type: Plain text #: usr_44.txt:66 msgid "" "This also can be used to list clusters (explained in |44.8|). Just include " "the @ in the name." msgstr "" # type: Plain text #: usr_44.txt:69 msgid "MATCHING CASE" msgstr "" # type: Plain text #: usr_44.txt:75 #, no-wrap msgid "" "Some languages are not case sensitive, such as Pascal. Others, such as C, " "are\n" "case sensitive. You need to tell which type you have with the following\n" "commands: >\n" "\t:syntax case match\n" "\t:syntax case ignore\n" msgstr "" # type: Plain text #: usr_44.txt:84 #, no-wrap msgid "" "The \"match\" argument means that Vim will match the case of syntax " "elements.\n" "Therefore, \"int\" differs from \"Int\" and \"INT\". If the \"ignore\" " "argument is\n" "used, the following are equivalent: \"Procedure\", \"PROCEDURE\" and " "\"procedure\".\n" " The \":syntax case\" commands can appear anywhere in a syntax file and " "affect\n" "the syntax definitions that follow. In most cases, you have only one " "\":syntax\n" "case\" command in your syntax file; if you work with an unusual language " "that\n" "contains both case-sensitive and non-case-sensitive elements, however, you " "can\n" "scatter the \":syntax case\" command throughout the file.\n" msgstr "" # type: Plain text #: usr_44.txt:87 #, no-wrap msgid "*44.2*\tKeywords\n" msgstr "" # type: Plain text #: usr_44.txt:90 msgid "" "The most basic syntax elements are keywords. To define a keyword, use the " "following form: >" msgstr "" # type: Plain text #: usr_44.txt:92 #, no-wrap msgid "\t:syntax keyword {group} {keyword} ...\n" msgstr "" # type: Plain text #: usr_44.txt:96 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:99 #, no-wrap msgid "" "\t:syntax keyword xType int long char\n" "\t:syntax keyword xStatement if then else endif\n" msgstr "" # type: Plain text #: usr_44.txt:109 #, no-wrap msgid "" "This example uses the group names \"xType\" and \"xStatement\". By " "convention,\n" "each group name is prefixed by the filetype for the language being " "defined.\n" "This example defines syntax for the x language (eXample language without " "an\n" "interesting name). In a syntax file for \"csh\" scripts the name " "\"cshType\"\n" "would be used. Thus the prefix is equal to the value of 'filetype'.\n" " These commands cause the words \"int\", \"long\" and \"char\" to be " "highlighted\n" "one way and the words \"if\", \"then\", \"else\" and \"endif\" to be " "highlighted\n" "another way. Now you need to connect the x group names to standard Vim\n" "names. You do this with the following commands: >\n" msgstr "" # type: Plain text #: usr_44.txt:112 #, no-wrap msgid "" "\t:highlight link xType Type\n" "\t:highlight link xStatement Statement\n" msgstr "" # type: Plain text #: usr_44.txt:115 msgid "" "This tells Vim to highlight \"xType\" like \"Type\" and \"xStatement\" like " "\"Statement\". See |group-name| for the standard names." msgstr "" # type: Plain text #: usr_44.txt:118 msgid "UNUSUAL KEYWORDS" msgstr "" # type: Plain text #: usr_44.txt:126 #, no-wrap msgid "" "The characters used in a keyword must be in the 'iskeyword' option. If " "you\n" "use another character, the word will never match. Vim doesn't give a " "warning\n" "message for this.\n" " The x language uses the '-' character in keywords. This is how it's " "done:\n" ">\n" "\t:setlocal iskeyword+=-\n" "\t:syntax keyword xStatement when-not\n" msgstr "" # type: Plain text #: usr_44.txt:131 msgid "" "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)." msgstr "" # type: Plain text #: usr_44.txt:136 #, no-wrap msgid "" "The x language allows for abbreviations. For example, \"next\" can be\n" "abbreviated to \"n\", \"ne\" or \"nex\". You can define them by using this " "command:\n" ">\n" "\t:syntax keyword xStatement n[ext]\n" msgstr "" # type: Plain text #: usr_44.txt:138 msgid "This doesn't match \"nextone\", keywords always match whole words only." msgstr "" # type: Plain text #: usr_44.txt:141 #, no-wrap msgid "*44.3*\tMatches\n" msgstr "" # type: Plain text #: usr_44.txt:145 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:153 #, no-wrap msgid "" "\t:syntax match xIdentifier /\\<\\l\\+\\>/\n" "<\n" "\tNote:\n" "\tKeywords overrule any other syntax item. Thus the keywords \"if\",\n" "\t\"then\", etc., will be keywords, as defined with the \":syntax " "keyword\"\n" "\tcommands above, even though they also match the pattern for\n" "\txIdentifier.\n" msgstr "" # type: Plain text #: usr_44.txt:157 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:160 msgid "" "Now define a match for a comment. In the x language it is anything from # " "to the end of a line: >" msgstr "" # type: Plain text #: usr_44.txt:162 #, no-wrap msgid "\t:syntax match xComment /#.*/\n" msgstr "" # type: Plain text #: usr_44.txt:165 msgid "" "Since you can use any search pattern, you can highlight very complex things " "with a match item. See |pattern| for help on search patterns." msgstr "" # type: Plain text #: usr_44.txt:168 #, no-wrap msgid "*44.4*\tRegions\n" msgstr "" # type: Plain text #: usr_44.txt:172 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:174 #, no-wrap msgid "\t:syntax region xString start=/\"/ end=/\"/\n" msgstr "" # type: Plain text #: usr_44.txt:177 msgid "" "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?" msgstr "" # type: Plain text #: usr_44.txt:179 #, no-wrap msgid "\t\"A string with a double quote (\\\") in it\" ~\n" msgstr "" # type: Plain text #: usr_44.txt:183 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:185 #, no-wrap msgid "\t:syntax region xString start=/\"/ skip=/\\\\\"/ end=/\"/\n" msgstr "" # type: Plain text #: usr_44.txt:188 msgid "" "The double backslash matches a single backslash, since the backslash is a " "special character in search patterns." msgstr "" # type: Plain text #: usr_44.txt:195 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:198 #, no-wrap msgid "*44.5*\tNested items\n" msgstr "" # type: Plain text #: usr_44.txt:200 msgid "Take a look at this comment:" msgstr "" # type: Plain text #: usr_44.txt:202 #, no-wrap msgid "\t%Get input TODO: Skip white space ~\n" msgstr "" # type: Plain text #: usr_44.txt:206 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:209 #, no-wrap msgid "" "\t:syntax keyword xTodo TODO contained\n" "\t:syntax match xComment /%.*/ contains=xTodo\n" msgstr "" # type: Plain text #: usr_44.txt:216 msgid "" "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)." msgstr "" # type: Plain text #: usr_44.txt:219 msgid "RECURSIVE NESTING" msgstr "" # type: Plain text #: usr_44.txt:222 msgid "" "The x language defines code blocks in curly braces. And a code block may " "contain other code blocks. This can be defined this way: >" msgstr "" # type: Plain text #: usr_44.txt:224 #, no-wrap msgid "\t:syntax region xBlock start=/{/ end=/}/ contains=xBlock\n" msgstr "" # type: Plain text #: usr_44.txt:226 msgid "Suppose you have this text:" msgstr "" # type: Plain text #: usr_44.txt:232 #, no-wrap msgid "" "\twhile i < b { ~\n" "\t\tif a { ~\n" "\t\t\tb = c; ~\n" "\t\t} ~\n" "\t} ~\n" msgstr "" # type: Plain text #: usr_44.txt:240 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:243 msgid "KEEPING THE END" msgstr "" # type: Plain text #: usr_44.txt:245 msgid "Consider the following two syntax items: >" msgstr "" # type: Plain text #: usr_44.txt:248 #, no-wrap msgid "" "\t:syntax region xComment start=/%/ end=/$/ contained\n" "\t:syntax region xPreProc start=/#/ end=/$/ contains=xComment\n" msgstr "" # type: Plain text #: usr_44.txt:254 msgid "" "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:" msgstr "" # type: Plain text #: usr_44.txt:257 #, no-wrap msgid "" "\t#define X = Y % Comment text ~\n" "\tint foo = 1; ~\n" msgstr "" # type: Plain text #: usr_44.txt:268 #, no-wrap msgid "" "What you see is that the second line is also highlighted as xPreProc. The\n" "preprocessor directive should end at the end of the line. That is why\n" "you have used \"end=/$/\". So what is going wrong?\n" " The problem is the contained comment. The comment starts with % and " "ends\n" "at the end of the line. After the comment ends, the preprocessor syntax\n" "continues. This is after the end of the line has been seen, so the next\n" "line is included as well.\n" " To avoid this problem and to avoid a contained syntax item eating a " "needed\n" "end of line, use the \"keepend\" argument. This takes care of\n" "the double end-of-line matching: >\n" msgstr "" # type: Plain text #: usr_44.txt:271 #, no-wrap msgid "" "\t:syntax region xComment start=/%/ end=/$/ contained\n" "\t:syntax region xPreProc start=/#/ end=/$/ contains=xComment keepend\n" msgstr "" # type: Plain text #: usr_44.txt:274 msgid "CONTAINING MANY ITEMS" msgstr "" # type: Plain text #: usr_44.txt:277 msgid "" "You can use the contains argument to specify that everything can be " "contained. For example: >" msgstr "" # type: Plain text #: usr_44.txt:279 #, no-wrap msgid "\t:syntax region xList start=/\\[/ end=/\\]/ contains=ALL\n" msgstr "" # type: Plain text #: usr_44.txt:286 #, no-wrap msgid "" "All syntax items will be contained in this one. It also contains itself, " "but\n" "not at the same position (that would cause an endless loop).\n" " You can specify that some groups are not contained. Thus contain all\n" "groups but the ones that are listed:\n" ">\n" "\t:syntax region xList start=/\\[/ end=/\\]/ contains=ALLBUT,xString\n" msgstr "" # type: Plain text #: usr_44.txt:290 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:293 #, no-wrap msgid "*44.6*\tFollowing groups\n" msgstr "" # type: Plain text #: usr_44.txt:295 msgid "The x language has statements in this form:" msgstr "" # type: Plain text #: usr_44.txt:297 #, no-wrap msgid "\tif (condition) then ~\n" msgstr "" # type: Plain text #: usr_44.txt:301 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:305 #, no-wrap msgid "" "\t:syntax match xIf /if/ nextgroup=xIfCondition skipwhite\n" "\t:syntax match xIfCondition /([^)]*)/ contained nextgroup=xThen skipwhite\n" "\t:syntax match xThen /then/ contained\n" msgstr "" # type: Plain text #: usr_44.txt:309 msgid "" "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:" msgstr "" # type: Plain text #: usr_44.txt:311 #, no-wrap msgid "\tif not (condition) then ~\n" msgstr "" # type: Plain text #: usr_44.txt:314 msgid "" "The \"if\" is matched by xIf. \"not\" doesn't match the specified nextgroup " "xIfCondition, thus only the \"if\" is highlighted." msgstr "" # type: Plain text #: usr_44.txt:320 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:323 #, no-wrap msgid "*44.7*\tOther arguments\n" msgstr "" # type: Plain text #: usr_44.txt:325 msgid "MATCHGROUP" msgstr "" # type: Plain text #: usr_44.txt:329 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:331 #, no-wrap msgid "\t:syntax region xInside start=/(/ end=/)/\n" msgstr "" # type: Plain text #: usr_44.txt:336 msgid "" "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): >" msgstr "" # type: Plain text #: usr_44.txt:338 #, no-wrap msgid "\t:syntax region xInside matchgroup=xParen start=/(/ end=/)/\n" msgstr "" # type: Plain text #: usr_44.txt:342 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:345 #, no-wrap msgid "" "\t:syntax region xInside matchgroup=xParen start=/(/\n" "\t\t\\ matchgroup=xParenEnd end=/)/\n" msgstr "" # type: Plain text #: usr_44.txt:348 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:351 msgid "TRANSPARENT" msgstr "" # type: Plain text #: usr_44.txt:362 #, no-wrap msgid "" "In a C language file you would like to highlight the () text after a " "\"while\"\n" "differently from the () text after a \"for\". In both of these there can " "be\n" "nested () items, which should be highlighted in the same way. You must " "make\n" "sure the () highlighting stops at the matching ). This is one way to do " "this:\n" ">\n" "\t:syntax region cWhile matchgroup=cWhile start=/while\\s*(/ end=/)/\n" "\t\t\\ contains=cCondNest\n" "\t:syntax region cFor matchgroup=cFor start=/for\\s*(/ end=/)/\n" "\t\t\\ contains=cCondNest\n" "\t:syntax region cCondNest start=/(/ end=/)/ contained transparent\n" msgstr "" # type: Plain text #: usr_44.txt:373 #, no-wrap msgid "" "Now you can give cWhile and cFor different highlighting. The cCondNest " "item\n" "can appear in either of them, but take over the highlighting of the item it " "is\n" "contained in. The \"transparent\" argument causes this.\n" " Notice that the \"matchgroup\" argument has the same group as the item\n" "itself. Why define it then? Well, the side effect of using a matchgroup " "is\n" "that contained items are not found in the match with the start item then.\n" "This avoids that the cCondNest group matches the ( just after the \"while\" " "or\n" "\"for\". If this would happen, it would span the whole text until the " "matching\n" ") and the region would continue after it. Now cCondNest only matches " "after\n" "the match with the start pattern, thus after the first (.\n" msgstr "" # type: Plain text #: usr_44.txt:376 msgid "OFFSETS" msgstr "" # type: Plain text #: usr_44.txt:380 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:382 #, no-wrap msgid "\t:syntax region xCond start=/if\\s*(/ms=e+1 end=/)/me=s-1\n" msgstr "" # type: Plain text #: usr_44.txt:390 #, no-wrap msgid "" "The offset for the start pattern is \"ms=e+1\". \"ms\" stands for Match " "Start.\n" "This defines an offset for the start of the match. Normally the match " "starts\n" "where the pattern matches. \"e+1\" means that the match now starts at the " "end\n" "of the pattern match, and then one character further.\n" " The offset for the end pattern is \"me=s-1\". \"me\" stands for Match " "End.\n" "\"s-1\" means the start of the pattern match and then one character back. " "The\n" "result is that in this text:\n" msgstr "" # type: Plain text #: usr_44.txt:392 #, no-wrap msgid "\tif (foo == bar) ~\n" msgstr "" # type: Plain text #: usr_44.txt:394 msgid "Only the text \"foo == bar\" will be highlighted as xCond." msgstr "" # type: Plain text #: usr_44.txt:396 msgid "More about offsets here: |:syn-pattern-offset|." msgstr "" # type: Plain text #: usr_44.txt:399 msgid "ONELINE" msgstr "" # type: Plain text #: usr_44.txt:402 msgid "" "The \"oneline\" argument indicates that the region does not cross a line " "boundary. For example: >" msgstr "" # type: Plain text #: usr_44.txt:404 #, no-wrap msgid "\t:syntax region xIfThen start=/if/ end=/then/ oneline\n" msgstr "" # type: Plain text #: usr_44.txt:407 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:413 #, no-wrap msgid "" "\tNote:\n" "\tWhen using \"oneline\" the region doesn't start if the end pattern\n" "\tdoesn't match in the same line. Without \"oneline\" Vim does _not_\n" "\tcheck if there is a match for the end pattern. The region starts even\n" "\twhen the end pattern doesn't match in the rest of the file.\n" msgstr "" # type: Plain text #: usr_44.txt:416 msgid "CONTINUATION LINES AND AVOIDING THEM" msgstr "" # type: Plain text #: usr_44.txt:422 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:425 #, no-wrap msgid "" "\t:syntax region xPreProc start=/^#/ end=/$/ contains=xLineContinue\n" "\t:syntax match xLineContinue \"\\\\$\" contained\n" msgstr "" # type: Plain text #: usr_44.txt:429 msgid "" "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:" msgstr "" # type: Plain text #: usr_44.txt:432 #, no-wrap msgid "" "\t#define SPAM spam spam spam \\ ~\n" "\t\t\tbacon and spam ~\n" msgstr "" # type: Plain text #: usr_44.txt:438 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:443 #, no-wrap msgid "" "\t:syntax region xPreProc start=/^#/ end=/$/\n" "\t\t\\ contains=xLineContinue,xPreProcEnd\n" "\t:syntax match xPreProcEnd excludenl /end$/ contained\n" "\t:syntax match xLineContinue \"\\\\$\" contained\n" msgstr "" # type: Plain text #: usr_44.txt:447 msgid "" "\"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." msgstr "" # type: Plain text #: usr_44.txt:450 #, no-wrap msgid "*44.8*\tClusters\n" msgstr "" # type: Plain text #: usr_44.txt:457 #, no-wrap msgid "" "One of the things you will notice as you start to write a syntax file is " "that\n" "you wind up generating a lot of syntax groups. Vim enables you to define " "a\n" "collection of syntax groups called a cluster.\n" " Suppose you have a language that contains for loops, if statements, " "while\n" "loops, and functions. Each of them contains the same syntax elements: " "numbers\n" "and identifiers. You define them like this: >\n" msgstr "" # type: Plain text #: usr_44.txt:461 #, no-wrap msgid "" "\t:syntax match xFor /^for.*/ contains=xNumber,xIdent\n" "\t:syntax match xIf /^if.*/ contains=xNumber,xIdent\n" "\t:syntax match xWhile /^while.*/ contains=xNumber,xIdent\n" msgstr "" # type: Plain text #: usr_44.txt:468 #, no-wrap msgid "" "You have to repeat the same \"contains=\" every time. If you want to add\n" "another contained item, you have to add it three times. Syntax clusters\n" "simplify these definitions by enabling you to have one cluster stand for\n" "several syntax groups.\n" " To define a cluster for the two items that the three groups contain, " "use\n" "the following command: >\n" msgstr "" # type: Plain text #: usr_44.txt:470 #, no-wrap msgid "\t:syntax cluster xState contains=xNumber,xIdent\n" msgstr "" # type: Plain text #: usr_44.txt:473 msgid "" "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: " ">" msgstr "" # type: Plain text #: usr_44.txt:477 #, no-wrap msgid "" "\t:syntax match xFor /^for.*/ contains=@xState\n" "\t:syntax match xIf /^if.*/ contains=@xState\n" "\t:syntax match xWhile /^while.*/ contains=@xState\n" msgstr "" # type: Plain text #: usr_44.txt:479 msgid "You can add new group names to this cluster with the \"add\" argument: >" msgstr "" # type: Plain text #: usr_44.txt:481 #, no-wrap msgid "\t:syntax cluster xState add=xString\n" msgstr "" # type: Plain text #: usr_44.txt:483 msgid "You can remove syntax groups from this list as well: >" msgstr "" # type: Plain text #: usr_44.txt:485 #, no-wrap msgid "\t:syntax cluster xState remove=xNumber\n" msgstr "" # type: Plain text #: usr_44.txt:488 #, no-wrap msgid "*44.9*\tIncluding another syntax file\n" msgstr "" # type: Plain text #: usr_44.txt:492 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:494 #, no-wrap msgid "\t:runtime! syntax/c.vim\n" msgstr "" # type: Plain text #: usr_44.txt:501 #, no-wrap msgid "" "The \":runtime!\" command searches 'runtimepath' for all \"syntax/c.vim\" " "files.\n" "This makes the C syntax be defined like for C files. If you have replaced " "the\n" "c.vim syntax file, or added items with an extra file, these will be loaded " "as\n" "well.\n" " After loading the C syntax items the specific C++ items can be defined.\n" "For example, add keywords that are not used in C: >\n" msgstr "" # type: Plain text #: usr_44.txt:503 #, no-wrap msgid "\t:syntax keyword cppStatement\tnew delete this friend using\n" msgstr "" # type: Plain text #: usr_44.txt:505 msgid "This works just like in any other syntax file." msgstr "" # type: Plain text #: usr_44.txt:513 #, no-wrap msgid "" "Now consider the Perl language. It consists of two distinct parts: a\n" "documentation section in POD format, and a program written in Perl itself.\n" "The POD section starts with \"=head\" and ends with \"=cut\".\n" " You want to define the POD syntax in one file, and use it from the Perl\n" "syntax file. The \":syntax include\" command reads in a syntax file and " "stores\n" "the elements it defined in a syntax cluster. For Perl, the statements are " "as\n" "follows: >\n" msgstr "" # type: Plain text #: usr_44.txt:516 #, no-wrap msgid "" "\t:syntax include @Pod :p:h/pod.vim\n" "\t:syntax region perlPOD start=/^=head/ end=/^=cut/ contains=@Pod\n" msgstr "" # type: Plain text #: usr_44.txt:529 #, no-wrap msgid "" "When \"=head\" is found in a Perl file, the perlPOD region starts. In " "this\n" "region the @Pod cluster is contained. All the items defined as top-level\n" "items in the pod.vim syntax files will match here. When \"=cut\" is found, " "the\n" "region ends and we go back to the items defined in the Perl file.\n" " The \":syntax include\" command is clever enough to ignore a \":syntax " "clear\"\n" "command in the included file. And an argument such as \"contains=ALL\" " "will\n" "only contain items defined in the included file, not in the file that " "includes\n" "it.\n" " The \":p:h/\" part uses the name of the current file (),\n" "expands it to a full path (:p) and then takes the head (:h). This results " "in\n" "the directory name of the file. This causes the pod.vim file in the same\n" "directory to be included.\n" msgstr "" # type: Plain text #: usr_44.txt:532 #, no-wrap msgid "*44.10*\tSynchronizing\n" msgstr "" # type: Plain text #: usr_44.txt:540 #, no-wrap msgid "" "Compilers have it easy. They start at the beginning of a file and parse " "it\n" "straight through. Vim does not have it so easy. It must start in the " "middle,\n" "where the editing is being done. So how does it tell where it is?\n" " The secret is the \":syntax sync\" command. This tells Vim how to figure " "out\n" "where it is. For example, the following command tells Vim to scan " "backward\n" "for the beginning or end of a C-style comment and begin syntax coloring " "from\n" "there: >\n" msgstr "" # type: Plain text #: usr_44.txt:542 #, no-wrap msgid "\t:syntax sync ccomment\n" msgstr "" # type: Plain text #: usr_44.txt:548 #, no-wrap msgid "" "You can tune this processing with some arguments. The \"minlines\" " "argument\n" "tells Vim the minimum number of lines to look backward, and \"maxlines\" " "tells\n" "the editor the maximum number of lines to scan.\n" " For example, the following command tells Vim to look at least 10 lines\n" "before the top of the screen: >\n" msgstr "" # type: Plain text #: usr_44.txt:550 #, no-wrap msgid "\t:syntax sync ccomment minlines=10 maxlines=500\n" msgstr "" # type: Plain text #: usr_44.txt:561 #, no-wrap msgid "" "If it cannot figure out where it is in that space, it starts looking " "farther\n" "and farther back until it figures out what to do. But it looks no farther\n" "back than 500 lines. (A large \"maxlines\" slows down processing. A small " "one\n" "might cause synchronization to fail.)\n" " To make synchronizing go a bit faster, tell Vim which syntax items can " "be\n" "skipped. Every match and region that only needs to be used when actually\n" "displaying text can be given the \"display\" argument.\n" " By default, the comment to be found will be colored as part of the " "Comment\n" "syntax group. If you want to color things another way, you can specify a\n" "different syntax group: >\n" msgstr "" # type: Plain text #: usr_44.txt:563 #, no-wrap msgid "\t:syntax sync ccomment xAltComment\n" msgstr "" # type: Plain text #: usr_44.txt:568 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:570 #, no-wrap msgid "\t:syntax sync minlines=150\n" msgstr "" # type: Plain text #: usr_44.txt:577 #, no-wrap msgid "" "A large \"minlines\" value can make Vim slower, especially when scrolling\n" "backwards in the file.\n" " Finally, you can specify a syntax group to look for by using this " "command:\n" ">\n" "\t:syntax sync match {sync-group-name}\n" "\t\t\\ grouphere {group-name} {pattern}\n" msgstr "" # type: Plain text #: usr_44.txt:582 msgid "" "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\":" msgstr "" # type: Plain text #: usr_44.txt:586 #, no-wrap msgid "" "\tif [ --f file.txt ] ; then ~\n" "\t\techo \"File exists\" ~\n" "\tfi ~\n" msgstr "" # type: Plain text #: usr_44.txt:589 msgid "" "To define a \"grouphere\" directive for this syntax, you use the following " "command: >" msgstr "" # type: Plain text #: usr_44.txt:591 #, no-wrap msgid "\t:syntax sync match shIfSync grouphere shIf \"\\\"\n" msgstr "" # type: Plain text #: usr_44.txt:594 msgid "" "The \"groupthere\" argument tells Vim that the pattern ends a group. For " "example, the end of the if/fi group is as follows: >" msgstr "" # type: Plain text #: usr_44.txt:596 #, no-wrap msgid "\t:syntax sync match shIfSync groupthere NONE \"\\\"\n" msgstr "" # type: Plain text #: usr_44.txt:599 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:604 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:606 #, no-wrap msgid "\t:syntax sync match xSpecial /{.*}/\n" msgstr "" # type: Plain text #: usr_44.txt:608 msgid "More about synchronizing in the reference manual: |:syn-sync|." msgstr "" # type: Plain text #: usr_44.txt:611 #, no-wrap msgid "*44.11*\tInstalling a syntax file\n" msgstr "" # type: Plain text #: usr_44.txt:616 #, no-wrap msgid "" "When your new syntax file is ready to be used, drop it in a \"syntax\" " "directory\n" "in 'runtimepath'. For Unix that would be \"~/.vim/syntax\".\n" " The name of the syntax file must be equal to the file type, with " "\".vim\"\n" "added. Thus for the x language, the full path of the file would be:\n" msgstr "" # type: Plain text #: usr_44.txt:618 #, no-wrap msgid "\t~/.vim/syntax/x.vim ~\n" msgstr "" # type: Plain text #: usr_44.txt:620 msgid "You must also make the file type be recognized. See |43.2|." msgstr "" # type: Plain text #: usr_44.txt:626 msgid "" "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: . Also " "explain how the filetype can be detected. With a bit of luck your file will " "be included in the next Vim version!" msgstr "" # type: Plain text #: usr_44.txt:629 msgid "ADDING TO AN EXISTING SYNTAX FILE" msgstr "" # type: Plain text #: usr_44.txt:638 #, no-wrap msgid "" "We were assuming you were adding a completely new syntax file. When an " "existing\n" "syntax file works, but is missing some items, you can add items in a " "separate\n" "file. That avoids changing the distributed syntax file, which will be " "lost\n" "when installing a new version of Vim.\n" " Write syntax commands in your file, possibly using group names from the\n" "existing syntax. For example, to add new variable types to the C syntax " "file:\n" ">\n" "\t:syntax keyword cType off_t uint\n" msgstr "" # type: Plain text #: usr_44.txt:642 msgid "" "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:" msgstr "" # type: Plain text #: usr_44.txt:644 #, no-wrap msgid "\t~/.vim/after/syntax/c.vim ~\n" msgstr "" # type: Plain text #: usr_44.txt:647 #, no-wrap msgid "*44.12*\tPortable syntax file layout\n" msgstr "" # type: Plain text #: usr_44.txt:650 msgid "" "Wouldn't it be nice if all Vim users exchange syntax files? To make this " "possible, the syntax file must follow a few guidelines." msgstr "" # type: Plain text #: usr_44.txt:654 msgid "" "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: >" msgstr "" # type: Plain text #: usr_44.txt:660 #, no-wrap msgid "" "\t\" Vim syntax file\n" "\t\" Language:\tC\n" "\t\" Maintainer:\tBram Moolenaar \n" "\t\" Last Change:\t2001 Jun 18\n" "\t\" Remark:\tIncluded by the C++ syntax.\n" msgstr "" # type: Plain text #: usr_44.txt:663 msgid "" "Use the same layout as the other syntax files. Using an existing syntax " "file as an example will save you a lot of time." msgstr "" # type: Plain text #: usr_44.txt:668 msgid "" "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)." msgstr "" # type: Plain text #: usr_44.txt:671 msgid "" "Start with a check for \"b:current_syntax\". If it is defined, some other " "syntax file, earlier in 'runtimepath' was already loaded: >" msgstr "" # type: Plain text #: usr_44.txt:675 #, no-wrap msgid "" "\tif exists(\"b:current_syntax\")\n" "\t finish\n" "\tendif\n" msgstr "" # type: Plain text #: usr_44.txt:677 msgid "To be compatible with Vim 5.8 use: >" msgstr "" # type: Plain text #: usr_44.txt:683 #, no-wrap msgid "" "\tif version < 600\n" "\t syntax clear\n" "\telseif exists(\"b:current_syntax\")\n" "\t finish\n" "\tendif\n" msgstr "" # type: Plain text #: usr_44.txt:687 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:690 msgid "" "If you want your syntax file to work with Vim 5.x, add a check for " "v:version. See yacc.vim for an example." msgstr "" # type: Plain text #: usr_44.txt:693 msgid "" "Do not include anything that is a user preference. Don't set 'tabstop', " "'expandtab', etc. These belong in a filetype plugin." msgstr "" # type: Plain text #: usr_44.txt:696 msgid "" "Do not include mappings or abbreviations. Only include setting 'iskeyword' " "if it is really necessary for recognizing keywords." msgstr "" # type: Plain text #: usr_44.txt:703 msgid "" "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." msgstr "" # type: Plain text #: usr_44.txt:706 msgid "" "For the linking use \"hi def link\", so that the user can select different " "highlighting before your syntax file is loaded. Example: >" msgstr "" # type: Plain text #: usr_44.txt:711 #, no-wrap msgid "" "\t hi def link nameString\tString\n" "\t hi def link nameNumber\tNumber\n" "\t hi def link nameCommand\tStatement\n" "\t ... etc ...\n" msgstr "" # type: Plain text #: usr_44.txt:714 msgid "" "Add the \"display\" argument to items that are not used when syncing, to " "speed up scrolling backwards and CTRL-L." msgstr "" # type: Plain text #: usr_44.txt:718 msgid "Next chapter: |usr_45.txt| Select your language" msgstr "" # type: Plain text #: usr_44.txt:719 msgid "Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:" msgstr ""