vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_51.txt (27340B)


      1 *usr_51.txt*	For Vim version 9.2.  Last change: 2026 Aug 23
      2 
      3 
      4 		     VIM USER MANUAL	by Bram Moolenaar
      5 
      6 
      7 			      Write plugins
      8 
      9 
     10 Plugins can be used to define settings for a specific type of file, syntax
     11 highlighting and many other things.  This chapter explains how to write the
     12 most common Vim plugins.
     13 
     14 |51.1|	Writing a generic plugin
     15 |51.2|	Writing a filetype plugin
     16 |51.3|	Writing a compiler plugin
     17 |51.4|	Distributing Vim scripts
     18 
     19      Next chapter: |usr_52.txt|  Write large plugins
     20  Previous chapter: |usr_50.txt|  Advanced Vim script writing
     21 Table of contents: |usr_toc.txt|
     22 
     23 ==============================================================================
     24 *51.1*	Writing a generic plugin			*write-plugin*
     25 
     26 You can write a Vim script in such a way that many people can use it.  This is
     27 called a plugin.  Vim users can drop your script in their plugin directory and
     28 use its features right away |add-plugin|.
     29 
     30 There are actually two types of plugins:
     31 
     32   global plugins: For all types of files.
     33 filetype plugins: Only for files of a specific type.
     34 
     35 In this section the first type is explained.  Most items are also relevant for
     36 writing filetype plugins.  The specifics for filetype plugins are in the next
     37 section |write-filetype-plugin|.
     38 
     39 We will use |Vim9| syntax here, the recommended way to write new plugins.
     40 Make sure the file starts with the `vim9script` command.
     41 
     42 
     43 NAME
     44 
     45 First of all you must choose a name for your plugin.  The features provided
     46 by the plugin should be clear from its name.  And it should be unlikely that
     47 someone else writes a plugin with the same name but which does something
     48 different.
     49 
     50 A script that corrects typing mistakes could be called "typecorrect.vim".  We
     51 will use it here as an example.
     52 
     53 For the plugin to work for everybody, it should follow a few guidelines.  This
     54 will be explained step-by-step.  The complete example plugin is at the end.
     55 
     56 
     57 BODY
     58 
     59 Let's start with the body of the plugin, the lines that do the actual work: >
     60 
     61  12	iabbrev teh the
     62  13	iabbrev otehr other
     63  14	iabbrev wnat want
     64  15	iabbrev synchronisation
     65  16		\ synchronization
     66 
     67 The actual list should be much longer, of course.
     68 
     69 The line numbers have only been added to explain a few things, don't put them
     70 in your plugin file!
     71 
     72 
     73 FIRST LINE
     74 >
     75   1	vim9script noclear
     76 
     77 You need to use `vim9script` as the very first command.  Best is to put it in
     78 the very first line.
     79 
     80 The script we are writing will have a `finish` command to bail out when it is
     81 loaded a second time.  To avoid that the items defined in the script are lost
     82 the "noclear" argument is used.  More info about this at |vim9-reload|.
     83 
     84 
     85 HEADER
     86 
     87 You will probably add new corrections to the plugin and soon have several
     88 versions lying around.  And when distributing this file, people will want to
     89 know who wrote this wonderful plugin and where they can send remarks.
     90 Therefore, put a header at the top of your plugin: >
     91 
     92   2	# Vim global plugin for correcting typing mistakes
     93   3	# Last Change:	2021 Dec 30
     94   4	# Maintainer:	Bram Moolenaar <Bram@vim.org>
     95 
     96 About copyright and licensing: Since plugins are very useful and it's hardly
     97 worth restricting their distribution, please consider making your plugin
     98 either public domain or use the Vim |license|.  A short note about this near
     99 the top of the plugin should be sufficient.  Example: >
    100 
    101   5	# License:	This file is placed in the public domain.
    102 
    103 
    104 NOT LOADING
    105 
    106 It is possible that a user doesn't always want to load this plugin.  Or the
    107 system administrator has dropped it in the system-wide plugin directory, but a
    108 user has their own plugin they want to use.  Then the user must have a chance
    109 to disable loading this specific plugin.  These lines will make it possible: >
    110 
    111   7	if exists("g:loaded_typecorrect")
    112   8	  finish
    113   9	endif
    114  10	g:loaded_typecorrect = 1
    115 
    116 This also avoids that when the script is loaded twice it would pointlessly
    117 redefine functions and cause trouble for autocommands that are added twice.
    118 
    119 The name is recommended to start with "g:loaded_" and then the file name of
    120 the plugin, literally.  The "g:" is prepended to make the variable global, so
    121 that other places can check whether its functionality is available.  Without
    122 "g:" it would be local to the script.
    123 
    124 Using `finish` stops Vim from reading the rest of the file, it's much quicker
    125 than using if-endif around the whole file, since Vim would still need to parse
    126 the commands to find the `endif`.
    127 
    128 
    129 MAPPING
    130 
    131 Now let's make the plugin more interesting: We will add a mapping that adds a
    132 correction for the word under the cursor.  We could just pick a key sequence
    133 for this mapping, but the user might already use it for something else.  To
    134 allow the user to define which keys a mapping in a plugin uses, the <Leader>
    135 item can be used: >
    136 
    137  20	  map <unique> <Leader>a  <Plug>(TypecorrAdd)
    138 
    139 The "<Plug>(TypecorrAdd)" thing will do the work, more about that further on.
    140 
    141 The user can set the "g:mapleader" variable to the key sequence that they want
    142 plugin mappings to start with.  Thus if the user has done: >
    143 
    144 	g:mapleader = "_"
    145 
    146 the mapping will define "_a".  If the user didn't do this, the default value
    147 will be used, which is a backslash.  Then a map for "\a" will be defined.
    148 
    149 Note that <unique> is used, this will cause an error message if the mapping
    150 already happened to exist. |:map-<unique>|
    151 
    152 But what if the user wants to define their own key sequence?  We can allow
    153 that with this mechanism: >
    154 
    155  19	if !hasmapto('<Plug>(TypecorrAdd)')
    156  20	  map <unique> <Leader>a  <Plug>(TypecorrAdd)
    157  21	endif
    158 
    159 This checks if a mapping to "<Plug>(TypecorrAdd)" already exists, and only
    160 defines the mapping from "<Leader>a" if it doesn't.  The user then has a
    161 chance of putting this in their vimrc file: >
    162 
    163 	map ,c  <Plug>(TypecorrAdd)
    164 
    165 Then the mapped key sequence will be ",c" instead of "_a" or "\a".
    166 
    167 
    168 PIECES
    169 
    170 If a script gets longer, you often want to break up the work in pieces.  You
    171 can use functions or mappings for this.  But you don't want these functions
    172 and mappings to interfere with the ones from other scripts.  For example, you
    173 could define a function Add(), but another script could try to define the same
    174 function.  To avoid this, we define the function local to the script.
    175 Fortunately, in |Vim9| script this is the default.  In a legacy script you
    176 would need to prefix the name with "s:".
    177 
    178 We will define a function that adds a new typing correction: >
    179 
    180  28	def Add(from: string, correct: bool)
    181  29	  var to = input($"type the correction for {from}: ")
    182  30	  exe $":iabbrev {from} {to}"
    183  ...
    184  34	enddef
    185 
    186 Now we can call the function Add() from within this script.  If another
    187 script also defines Add(), it will be local to that script and can only
    188 be called from that script.  There can also be a global g:Add() function,
    189 which is again another function.
    190 
    191 <SID> can be used with mappings.  It generates a script ID, which identifies
    192 the current script.  In our typing correction plugin we use it like this: >
    193 
    194  22	noremap <unique> <script> <Plug>(TypecorrAdd)  <SID>Add
    195  ...
    196  26	noremap <SID>Add  :call <SID>Add(expand("<cword>"), true)<CR>
    197 
    198 Thus when a user types "\a", this sequence is invoked: >
    199 
    200 	\a  ->  <Plug>(TypecorrAdd)  ->  <SID>Add  ->  :call <SID>Add(...)
    201 
    202 If another script also maps <SID>Add, it will get another script ID and
    203 thus define another mapping.
    204 
    205 Note that instead of Add() we use <SID>Add() here.  That is because the
    206 mapping is typed by the user, thus outside of the script context.  The <SID>
    207 is translated to the script ID, so that Vim knows in which script to look for
    208 the Add() function.
    209 
    210 This is a bit complicated, but it's required for the plugin to work together
    211 with other plugins.  The basic rule is that you use <SID>Add() in mappings and
    212 Add() in other places (the script itself, autocommands, user commands).
    213 
    214 We can also add a menu entry to do the same as the mapping: >
    215 
    216  24	noremenu <script> Plugin.Add\ Correction      <SID>Add
    217 
    218 The "Plugin" menu is recommended for adding menu items for plugins.  In this
    219 case only one item is used.  When adding more items, creating a submenu is
    220 recommended.  For example, "Plugin.CVS" could be used for a plugin that offers
    221 CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
    222 
    223 Note that in line 26 ":noremap" is used to avoid that any other mappings cause
    224 trouble.  Someone may have remapped ":call", for example.  In line 22 we also
    225 use ":noremap", but we do want "<SID>Add" to be remapped.  This is why
    226 "<script>" is used here.  This only allows mappings which are local to the
    227 script. |:map-<script>|  The same is done in line 24 for ":noremenu".
    228 |:menu-<script>|
    229 
    230 
    231 <SID> AND <Plug>					*using-<Plug>*
    232 
    233 Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
    234 with mappings that are only to be used from other mappings.  Note the
    235 difference between using <SID> and <Plug>:
    236 
    237 <Plug>	is visible outside of the script.  It is used for mappings which the
    238 	user might want to map a key sequence to.  <Plug> is a special code
    239 	that a typed key will never produce.
    240 	To make it very unlikely that other plugins use the same sequence of
    241 	characters, use this structure: <Plug> scriptname mapname
    242 	In our example the scriptname is "Typecorr" and the mapname is "Add".
    243 	We wrap the name in parentheses.  This results in
    244 	"<Plug>(TypecorrAdd)".  The convention of using PascalCase helps
    245 	telling scriptname apart from mapname.
    246 
    247 	Note: the text after "<Plug>" is chosen by the plugin author and is
    248 	entirely arbitrary.  Wrapping the name in parentheses, using
    249 	PascalCase, or adding a ";" terminator like "<Plug>TypecorrAdd;" are
    250 	only conventions to keep the name readable and unlikely to clash with
    251 	other plugins.  None of them are required: all that matters is that
    252 	the sequence starts with "<Plug>" and is unique.
    253 	A mapping whose {lhs} starts with <Plug> is always applied to the
    254 	{rhs} of another mapping, even if remapping is explicitly disallowed.
    255 	|:nore|
    256 
    257 <SID>	is the script ID, a unique identifier for a script.
    258 	Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
    259 	number.  Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
    260 	in one script, and "<SNR>22_Add()" in another.  You can see this if
    261 	you use the ":function" command to get a list of functions.  The
    262 	translation of <SID> in mappings is exactly the same, that's how you
    263 	can call a script-local function from a mapping.
    264 	Note: when <SID> appears in the {rhs} of a mapping, you might consider
    265 	using <script>. |:map-<script>|
    266 
    267 
    268 USER COMMAND
    269 
    270 Now let's add a user command to add a correction: >
    271 
    272  36	if !exists(":Correct")
    273  37	  command -nargs=1  Correct  :call Add(<q-args>, false)
    274  38	endif
    275 
    276 The user command is defined only if no command with the same name already
    277 exists.  Otherwise we would get an error here.  Overriding the existing user
    278 command with ":command!" is not a good idea, this would probably make the user
    279 wonder why the command they defined themselves doesn't work.  |:command|
    280 If it did happen you can find out who to blame with: >
    281 
    282 	verbose command Correct
    283 
    284 
    285 SCRIPT VARIABLES
    286 
    287 When a variable starts with "s:" it is a script variable.  It can only be used
    288 inside a script.  Outside the script it's not visible.  This avoids trouble
    289 with using the same variable name in different scripts.  The variables will be
    290 kept as long as Vim is running.  And the same variables are used when sourcing
    291 the same script again. |s:var|
    292 
    293 The nice thing about |Vim9| script is that variables are local to the script
    294 by default.  You can prepend "s:" if you like, but you do not need to.  And
    295 functions in the script can also use the script variables without a prefix
    296 (they must be declared before the function for this to work).
    297 
    298 Script-local variables can also be used in functions, autocommands and user
    299 commands that are defined in the script.  Thus they are the perfect way to
    300 share information between parts of your plugin, without it leaking out.  In
    301 our example we can add a few lines to count the number of corrections: >
    302 
    303  17	var count = 4
    304  ...
    305  28	def Add(from: string, correct: bool)
    306  ...
    307  32	  count += 1
    308  33	  echo "you now have " .. count .. " corrections"
    309  34	enddef
    310 
    311 "count" is declared and initialized to 4 in the script itself.  When later
    312 the Add() function is called, it increments "count".  It doesn't matter from
    313 where the function was called, since it has been defined in the script, it
    314 will use the local variables from this script.
    315 
    316 
    317 THE RESULT
    318 
    319 Here is the resulting complete example: >
    320 
    321   1	vim9script noclear
    322   2	# Vim global plugin for correcting typing mistakes
    323   3	# Last Change:	2021 Dec 30
    324   4	# Maintainer:	Bram Moolenaar <Bram@vim.org>
    325   5	# License:	This file is placed in the public domain.
    326   6
    327   7	if exists("g:loaded_typecorrect")
    328   8	  finish
    329   9	endif
    330  10	g:loaded_typecorrect = 1
    331  11
    332  12	iabbrev teh the
    333  13	iabbrev otehr other
    334  14	iabbrev wnat want
    335  15	iabbrev synchronisation
    336  16		\ synchronization
    337  17	var count = 4
    338  18
    339  19	if !hasmapto('<Plug>(TypecorrAdd)')
    340  20	  map <unique> <Leader>a  <Plug>(TypecorrAdd)
    341  21	endif
    342  22	noremap <unique> <script> <Plug>(TypecorrAdd)  <SID>Add
    343  23
    344  24	noremenu <script> Plugin.Add\ Correction      <SID>Add
    345  25
    346  26	noremap <SID>Add  :call <SID>Add(expand("<cword>"), true)<CR>
    347  27
    348  28	def Add(from: string, correct: bool)
    349  29	  var to = input($"type the correction for {from}: ")
    350  30	  exe $":iabbrev {from} {to}"
    351  31	  if correct | exe "normal viws\<C-R>\" \b\e" | endif
    352  32	  count += 1
    353  33	  echo "you now have " .. count .. " corrections"
    354  34	enddef
    355  35
    356  36	if !exists(":Correct")
    357  37	  command -nargs=1  Correct  call Add(<q-args>, false)
    358  38	endif
    359 
    360 Line 31 wasn't explained yet.  It applies the new correction to the word under
    361 the cursor.  The |:normal| command is used to use the new abbreviation.  Note
    362 that mappings and abbreviations are expanded here, even though the function
    363 was called from a mapping defined with ":noremap".
    364 
    365 
    366 DOCUMENTATION						*write-local-help*
    367 
    368 It's a good idea to also write some documentation for your plugin.  Especially
    369 when its behavior can be changed by the user.  See |help-writing| for the
    370 syntax used by the help files and |add-local-help| for how local help files
    371 are installed.
    372 
    373 Here is a simple example for a plugin help file, called "typecorrect.txt": >
    374 
    375   1	*typecorrect.txt*	Plugin for correcting typing mistakes
    376   2
    377   3	If you make typing mistakes, this plugin will have them corrected
    378   4	automatically.
    379   5
    380   6	There are currently only a few corrections.  Add your own if you like.
    381   7
    382   8	Mappings:
    383   9	<Leader>a   or   <Plug>(TypecorrAdd)
    384  10		Add a correction for the word under the cursor.
    385  11
    386  12	Commands:
    387  13	:Correct {word}
    388  14		Add a correction for {word}.
    389  15
    390  16							*typecorrect-settings*
    391  17	This plugin doesn't have any settings.
    392 
    393 The first line is actually the only one for which the format matters.  It will
    394 be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
    395 help.txt |local-additions|.  The first "*" must be in the first column of the
    396 first line.  After adding your help file do ":help" and check that the entries
    397 line up nicely.
    398 
    399 You can add more tags inside ** in your help file.  But be careful not to use
    400 existing help tags.  You would probably use the name of your plugin in most of
    401 them, like "typecorrect-settings" in the example.
    402 
    403 Using references to other parts of the help in || is recommended.  This makes
    404 it easy for the user to find associated help.
    405 
    406 
    407 SUMMARY							*plugin-special*
    408 
    409 Summary of special things to use in a plugin:
    410 
    411 var name		Variable local to the script.
    412 
    413 <SID>			Script-ID, used for mappings and functions local to
    414 			the script.
    415 
    416 hasmapto()		Function to test if the user already defined a mapping
    417 			for functionality the script offers.
    418 
    419 <Leader>		Value of "mapleader", which the user defines as the
    420 			keys that plugin mappings start with.
    421 
    422 map <unique>		Give a warning if a mapping already exists.
    423 
    424 noremap <script>	Only remap mappings defined in this script that start
    425 			with <SID>.
    426 
    427 exists(":Cmd")		Check if a user command already exists.
    428 
    429 ==============================================================================
    430 *51.2*	Writing a filetype plugin	*write-filetype-plugin* *ftplugin*
    431 
    432 A filetype plugin is like a global plugin, except that it sets options and
    433 defines mappings for the current buffer only.  See |add-filetype-plugin| for
    434 how this type of plugin is used.
    435 
    436 First read the section on global plugins above |51.1|.  All that is said there
    437 also applies to filetype plugins.  There are a few extras, which are explained
    438 here.  The essential thing is that a filetype plugin should only have an
    439 effect on the current buffer.
    440 
    441 
    442 DISABLING
    443 
    444 If you are writing a filetype plugin to be used by many people, they need a
    445 chance to disable loading it.  Put this at the top of the plugin: >
    446 
    447 	# Only do this when not done yet for this buffer
    448 	if exists("b:did_ftplugin")
    449 	  finish
    450 	endif
    451 	b:did_ftplugin = 1
    452 
    453 This also needs to be used to avoid that the same plugin is executed twice for
    454 the same buffer (happens when using an ":edit" command without arguments).
    455 
    456 Now users can disable loading the default plugin completely by making a
    457 filetype plugin with only these lines: >
    458 
    459 	vim9script
    460 	b:did_ftplugin = 1
    461 
    462 This does require that the filetype plugin directory comes before $VIMRUNTIME
    463 in 'runtimepath'!
    464 
    465 If you do want to use the default plugin, but overrule one of the settings,
    466 you can write the different setting in a script: >
    467 
    468 	setlocal textwidth=70
    469 
    470 Now write this in the "after" directory, so that it gets sourced after the
    471 distributed "vim.vim" ftplugin |after-directory|.  For Unix this would be
    472 "~/.vim/after/ftplugin/vim.vim".  Note that the default plugin will have set
    473 "b:did_ftplugin", it is ignored here.
    474 
    475 
    476 OPTIONS
    477 
    478 To make sure the filetype plugin only affects the current buffer use the >
    479 
    480 	setlocal
    481 
    482 command to set options.  And only set options which are local to a buffer (see
    483 the help for the option to check that).  When using `:setlocal` for global
    484 options or options local to a window, the value will change for many buffers,
    485 and that is not what a filetype plugin should do.
    486 
    487 When an option has a value that is a list of flags or items, consider using
    488 "+=" and "-=" to keep the existing value.  Be aware that the user may have
    489 changed an option value already.  First resetting to the default value and
    490 then changing it is often a good idea.  Example: >
    491 
    492 	setlocal formatoptions& formatoptions+=ro
    493 
    494 
    495 MAPPINGS
    496 
    497 To make sure mappings will only work in the current buffer use the >
    498 
    499 	map <buffer>
    500 
    501 command.  This needs to be combined with the two-step mapping explained above.
    502 An example of how to define functionality in a filetype plugin: >
    503 
    504 	if !hasmapto('<Plug>JavaImport;')
    505 	  map <buffer> <unique> <LocalLeader>i <Plug>JavaImport;
    506 	endif
    507 	noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc>
    508 
    509 |hasmapto()| is used to check if the user has already defined a map to
    510 <Plug>JavaImport;.  If not, then the filetype plugin defines the default
    511 mapping.  This starts with |<LocalLeader>|, which allows the user to select
    512 the key(s) they want filetype plugin mappings to start with.  The default is a
    513 backslash.
    514 "<unique>" is used to give an error message if the mapping already exists or
    515 overlaps with an existing mapping.
    516 |:noremap| is used to avoid that any other mappings that the user has defined
    517 interferes.  You might want to use ":noremap <script>" to allow remapping
    518 mappings defined in this script that start with <SID>.
    519 
    520 The user must have a chance to disable the mappings in a filetype plugin,
    521 without disabling everything.  Here is an example of how this is done for a
    522 plugin for the mail filetype: >
    523 
    524 	# Add mappings, unless the user didn't want this.
    525 	if !exists("g:no_plugin_maps") && !exists("g:no_mail_maps")
    526 	  # Quote text by inserting "> "
    527 	  if !hasmapto('<Plug>MailQuote;')
    528 	    vmap <buffer> <LocalLeader>q <Plug>MailQuote;
    529 	    nmap <buffer> <LocalLeader>q <Plug>MailQuote;
    530 	  endif
    531 	  vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR>
    532 	  nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR>
    533 	endif
    534 
    535 Two global variables are used:
    536 |g:no_plugin_maps|	disables mappings for all filetype plugins
    537 |g:no_mail_maps|	disables mappings for the "mail" filetype
    538 
    539 
    540 USER COMMANDS
    541 
    542 To add a user command for a specific file type, so that it can only be used in
    543 one buffer, use the "-buffer" argument to |:command|.  Example: >
    544 
    545 	command -buffer  Make  make %:r.s
    546 
    547 
    548 VARIABLES
    549 
    550 A filetype plugin will be sourced for each buffer of the type it's for.  Local
    551 script variables will be shared between all invocations.  Use local buffer
    552 variables |b:var| if you want a variable specifically for one buffer.
    553 
    554 
    555 FUNCTIONS
    556 
    557 When defining a function, this only needs to be done once.  But the filetype
    558 plugin will be sourced every time a file with this filetype will be opened.
    559 This construct makes sure the function is only defined once: >
    560 
    561 	if !exists("*Func")
    562 	  def Func(arg)
    563 	    ...
    564 	  enddef
    565 	endif
    566 <
    567 Don't forget to use "noclear" with the `vim9script` command to avoid that the
    568 function is deleted when the script is sourced a second time.
    569 
    570 
    571 UNDO						*undo_indent* *undo_ftplugin*
    572 
    573 When the user does ":setfiletype xyz" the effect of the previous filetype
    574 should be undone.  Set the b:undo_ftplugin variable to the commands that will
    575 undo the settings in your filetype plugin.  Example: >
    576 
    577 	b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
    578 		\ .. "| unlet b:match_ignorecase b:match_words b:match_skip"
    579 
    580 Using ":setlocal" with "<" after the option name resets the option to its
    581 global value.  That is mostly the best way to reset the option value.
    582 
    583 For undoing the effect of an indent script, the b:undo_indent variable should
    584 be set accordingly.
    585 
    586 Both these variables use legacy script syntax, not |Vim9| syntax.
    587 
    588 RECOMMENDED STYLE				*ft_recommended_style*
    589 
    590 A filetype plugin or indent script may set options that reflect a
    591 recommended or commonly used style for that filetype, rather than a strict
    592 requirement of the language.  Since not every user wants these stylistic
    593 settings, guard them so they can be disabled.
    594 
    595 Check two variables, the filetype-specific one first, then the general one,
    596 defaulting to enabled (1): >
    597 
    598 	if get(g:, '<filetype>_recommended_style',
    599 		\ get(g:, 'filetype_recommended_style', 1))
    600 	  " set the recommended style options here
    601 	endif
    602 
    603 Replace <filetype> with the actual filetype name, e.g. "python" gives
    604 g:python_recommended_style.
    605 
    606 This lets the user turn recommended style settings off for all filetypes: >
    607 
    608 	let g:filetype_recommended_style = 0
    609 
    610 or for one filetype while leaving the rest enabled: >
    611 
    612 	let g:python_recommended_style = 0
    613 
    614 The filetype-specific variable takes precedence over the general one, so a
    615 user can disable styling everywhere with g:filetype_recommended_style and
    616 re-enable it for a single filetype by setting g:<filetype>_recommended_style
    617 to 1 (or vice versa).
    618 
    619 Settings that are required for the language to work correctly (not merely
    620 stylistic) should not be placed behind this guard.
    621 
    622 FILE NAME
    623 
    624 The filetype must be included in the file name |ftplugin-name|.  Use one of
    625 these three forms:
    626 
    627 	.../ftplugin/stuff.vim
    628 	.../ftplugin/stuff_foo.vim
    629 	.../ftplugin/stuff/bar.vim
    630 
    631 "stuff" is the filetype, "foo" and "bar" are arbitrary names.
    632 
    633 
    634 FILETYPE DETECTION					*plugin-filetype*
    635 
    636 If your filetype is not already detected by Vim, you should create a filetype
    637 detection snippet in a separate file.  It is usually in the form of an
    638 autocommand that sets the filetype when the file name matches a pattern.
    639 Example: >
    640 
    641 	au BufNewFile,BufRead *.foo		setlocal filetype=foofoo
    642 
    643 Write this single-line file as "ftdetect/foofoo.vim" in the first directory
    644 that appears in 'runtimepath'.  For Unix that would be
    645 "~/.vim/ftdetect/foofoo.vim".  The convention is to use the name of the
    646 filetype for the script name.
    647 
    648 You can make more complicated checks if you like, for example to inspect the
    649 contents of the file to recognize the language.  Also see |new-filetype|.
    650 
    651 
    652 SUMMARY							*ftplugin-special*
    653 
    654 Summary of special things to use in a filetype plugin:
    655 
    656 <LocalLeader>		Value of "maplocalleader", which the user defines as
    657 			the keys that filetype plugin mappings start with.
    658 
    659 map <buffer>		Define a mapping local to the buffer.
    660 
    661 noremap <script>	Only remap mappings defined in this script that start
    662 			with <SID>.
    663 
    664 setlocal		Set an option for the current buffer only.
    665 
    666 command -buffer		Define a user command local to the buffer.
    667 
    668 exists("*s:Func")	Check if a function was already defined.
    669 
    670 Also see |plugin-special|, the special things used for all plugins.
    671 
    672 ==============================================================================
    673 *51.3*	Writing a compiler plugin		*write-compiler-plugin*
    674 
    675 A compiler plugin sets options for use with a specific compiler.  The user can
    676 load it with the |:compiler| command.  The main use is to set the
    677 'errorformat' and 'makeprg' options.
    678 
    679 Easiest is to have a look at examples.  This command will edit all the default
    680 compiler plugins: >
    681 
    682 	next $VIMRUNTIME/compiler/*.vim
    683 
    684 Type `:next` to go to the next plugin file.
    685 
    686 There are two special items about these files.  First is a mechanism to allow
    687 a user to overrule or add to the default file.  The default files start with: >
    688 
    689 	vim9script
    690 	if exists("g:current_compiler")
    691 	  finish
    692 	endif
    693 	g:current_compiler = "mine"
    694 
    695 When you write a compiler file and put it in your personal runtime directory
    696 (e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
    697 make the default file skip the settings.
    698 							*:CompilerSet*
    699 The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
    700 ":compiler".  Vim defines the ":CompilerSet" user command for this.  This is
    701 an example: >
    702 
    703   CompilerSet errorformat&		" use the default 'errorformat'
    704   CompilerSet makeprg=nmake
    705 
    706 Note: arguments need to be escaped according to |option-backslash|.
    707 
    708 When you write a compiler plugin for the Vim distribution or for a system-wide
    709 runtime directory, use the mechanism mentioned above.  When
    710 "current_compiler" was already set by a user plugin nothing will be done.
    711 
    712 When you write a compiler plugin to overrule settings from a default plugin,
    713 don't check "current_compiler".  This plugin is supposed to be loaded
    714 last, thus it should be in a directory at the end of 'runtimepath'.  For Unix
    715 that could be ~/.vim/after/compiler.
    716 
    717 ==============================================================================
    718 *51.4*	Distributing Vim scripts			*distribute-script*
    719 
    720 Vim users will look for scripts on the Vim website: http://www.vim.org.
    721 If you made something that is useful for others, share it!
    722 
    723 Another place is github.  But there you need to know where to find it!  The
    724 advantage is that most plugin managers fetch plugins from github.  You'll have
    725 to use your favorite search engine to find them.
    726 
    727 Vim scripts can be used on any system.  However, there might not be a tar or
    728 gzip command.  If you want to pack files together and/or compress them the
    729 "zip" utility is recommended.
    730 
    731 For utmost portability use Vim itself to pack scripts together.  This can be
    732 done with the Vimball utility.  See |vimball|.
    733 
    734 It's good if you add a line to allow automatic updating.  See |glvs-plugins|.
    735 
    736 ==============================================================================
    737 
    738 Next chapter: |usr_52.txt|  Write large plugins
    739 
    740 Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: