Mercurial > vim
view runtime/doc/filetype.txt @ 32936:c517845bd10e v9.0.1776
patch 9.0.1776: No support for stable Python 3 ABI
Commit: https://github.com/vim/vim/commit/c13b3d1350b60b94fe87f0761ea31c0e7fb6ebf3
Author: Yee Cheng Chin <ychin.git@gmail.com>
Date: Sun Aug 20 21:18:38 2023 +0200
patch 9.0.1776: No support for stable Python 3 ABI
Problem: No support for stable Python 3 ABI
Solution: Support Python 3 stable ABI
Commits:
1) Support Python 3 stable ABI to allow mixed version interoperatbility
Vim currently supports embedding Python for use with plugins, and the
"dynamic" linking option allows the user to specify a locally installed
version of Python by setting `pythonthreedll`. However, one caveat is
that the Python 3 libs are not binary compatible across minor versions,
and mixing versions can potentially be dangerous (e.g. let's say Vim was
linked against the Python 3.10 SDK, but the user sets `pythonthreedll`
to a 3.11 lib). Usually, nothing bad happens, but in theory this could
lead to crashes, memory corruption, and other unpredictable behaviors.
It's also difficult for the user to tell something is wrong because Vim
has no way of reporting what Python 3 version Vim was linked with.
For Vim installed via a package manager, this usually isn't an issue
because all the dependencies would already be figured out. For prebuilt
Vim binaries like MacVim (my motivation for working on this), AppImage,
and Win32 installer this could potentially be an issue as usually a
single binary is distributed. This is more tricky when a new Python
version is released, as there's a chicken-and-egg issue with deciding
what Python version to build against and hard to keep in sync when a new
Python version just drops and we have a mix of users of different Python
versions, and a user just blindly upgrading to a new Python could lead to
bad interactions with Vim.
Python 3 does have a solution for this problem: stable ABI / limited API
(see https://docs.python.org/3/c-api/stable.html). The C SDK limits the
API to a set of functions that are promised to be stable across
versions. This pull request adds an ifdef config that allows us to turn
it on when building Vim. Vim binaries built with this option should be
safe to freely link with any Python 3 libraies without having the
constraint of having to use the same minor version.
Note: Python 2 has no such concept and this doesn't change how Python 2
integration works (not that there is going to be a new version of Python
2 that would cause compatibility issues in the future anyway).
---
Technical details:
======
The stable ABI can be accessed when we compile with the Python 3 limited
API (by defining `Py_LIMITED_API`). The Python 3 code (in `if_python3.c`
and `if_py_both.h`) would now handle this and switch to limited API
mode. Without it set, Vim will still use the full API as before so this
is an opt-in change.
The main difference is that `PyType_Object` is now an opaque struct that
we can't directly create "static types" out of, and we have to create
type objects as "heap types" instead. This is because the struct is not
stable and changes from version to version (e.g. 3.8 added a
`tp_vectorcall` field to it). I had to change all the types to be
allocated on the heap instead with just a pointer to them.
Other functions are also simply missing in limited API, or they are
introduced too late (e.g. `PyUnicode_AsUTF8AndSize` in 3.10) to it that
we need some other ways to do the same thing, so I had to abstract a few
things into macros, and sometimes re-implement functions like
`PyObject_NEW`.
One caveat is that in limited API, `OutputType` (used for replacing
`sys.stdout`) no longer inherits from `PyStdPrinter_Type` which I don't
think has any real issue other than minor differences in how they
convert to a string and missing a couple functions like `mode()` and
`fileno()`.
Also fixed an existing bug where `tp_basicsize` was set incorrectly for
`BufferObject`, `TabListObject, `WinListObject`.
Technically, there could be a small performance drop, there is a little
more indirection with accessing type objects, and some APIs like
`PyUnicode_AsUTF8AndSize` are missing, but in practice I didn't see any
difference, and any well-written Python plugin should try to avoid
excessing callbacks to the `vim` module in Python anyway.
I only tested limited API mode down to Python 3.7, which seemes to
compile and work fine. I haven't tried earlier Python versions.
2) Fix PyIter_Check on older Python vers / type##Ptr unused warning
For PyIter_Check, older versions exposed them as either macros (used in
full API), or a function (for use in limited API). A previous change
exposed PyIter_Check to the dynamic build because Python just moved it
to function-only in 3.10 anyway. Because of that, just make sure we
always grab the function in dynamic builds in earlier versions since
that's what Python eventually did anyway.
3) Move Py_LIMITED_API define to configure script
Can now use --with-python-stable-abi flag to customize what stable ABI
version to target. Can also use an env var to do so as well.
4) Show +python/dyn-stable in :version, and allow has() feature query
Not sure if the "/dyn-stable" suffix would break things, or whether we
should do it another way. Or just don't show it in version and rely on
has() feature checking.
5) Documentation first draft. Still need to implement v:python3_version
6) Fix PyIter_Check build breaks when compiling against Python 3.8
7) Add CI coverage stable ABI on Linux/Windows / make configurable on Windows
This adds configurable options for Windows make files (both MinGW and
MSVC). CI will also now exercise both traditional full API and stable
ABI for Linux and Windows in the matrix for coverage.
Also added a "dynamic" option to Linux matrix as a drive-by change to
make other scripting languages like Ruby / Perl testable under both
static and dynamic builds.
8) Fix inaccuracy in Windows docs
Python's own docs are confusing but you don't actually want to use
`python3.dll` for the dynamic linkage.
9) Add generated autoconf file
10) Add v:python3_version support
This variable indicates the version of Python3 that Vim was built
against (PY_VERSION_HEX), and will be useful to check whether the Python
library you are loading in dynamically actually fits it. When built with
stable ABI, it will be the limited ABI version instead
(`Py_LIMITED_API`), which indicates the minimum version of Python 3 the
user should have, rather than the exact match. When stable ABI is used,
we won't be exposing PY_VERSION_HEX in this var because it just doesn't
seem necessary to do so (the whole point of stable ABI is the promise
that it will work across versions), and I don't want to confuse the user
with too many variables.
Also, cleaned up some documentation, and added help tags.
11) Fix Python 3.7 compat issues
Fix a couple issues when using limited API < 3.8
- Crash on exit: In Python 3.7, if a heap-allocated type is destroyed
before all instances are, it would cause a crash later. This happens
when we destroyed `OptionsType` before calling `Py_Finalize` when
using the limited API. To make it worse, later versions changed the
semantics and now each instance has a strong reference to its own type
and the recommendation has changed to have each instance de-ref its
own type and have its type in GC traversal. To avoid dealing with
these cross-version variations, we just don't free the heap type. They
are static types in non-limited-API anyway and are designed to last
through the entirety of the app, and we also don't restart the Python
runtime and therefore do not need it to have absolutely 0 leaks.
See:
- https://docs.python.org/3/whatsnew/3.8.html#changes-in-the-c-api
- https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-c-api
- PyIter_Check: This function is not provided in limited APIs older than
3.8. Previously I was trying to mock it out using manual
PyType_GetSlot() but it was brittle and also does not actually work
properly for static types (it will generate a Python error). Just
return false. It does mean using limited API < 3.8 is not recommended
as you lose the functionality to handle iterators, but from playing
with plugins I couldn't find it to be an issue.
- Fix loading of PyIter_Check so it will be done when limited API < 3.8.
Otherwise loading a 3.7 Python lib will fail even if limited API was
specified to use it.
12) Make sure to only load `PyUnicode_AsUTF8AndSize` in needed in limited API
We don't use this function unless limited API >= 3.10, but we were
loading it regardless. Usually it's ok in Unix-like systems where Python
just has a single lib that we load from, but in Windows where there is a
separate python3.dll this would not work as the symbol would not have
been exposed in this more limited DLL file. This makes it much clearer
under what condition is this function needed.
closes: #12032
Signed-off-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Yee Cheng Chin <ychin.git@gmail.com>
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Sun, 20 Aug 2023 21:30:04 +0200 |
parents | 346703c4ddd1 |
children | 53bd850dd268 |
line wrap: on
line source
*filetype.txt* For Vim version 9.0. Last change: 2023 Apr 29 VIM REFERENCE MANUAL by Bram Moolenaar Filetypes *filetype* *file-type* 1. Filetypes |filetypes| 2. Filetype plugin |filetype-plugins| 3. Docs for the default filetype plugins. |ftplugin-docs| Also see |autocmd.txt|. ============================================================================== 1. Filetypes *filetypes* *file-types* Vim can detect the type of file that is edited. This is done by checking the file name and sometimes by inspecting the contents of the file for specific text. *:filetype* *:filet* To enable file type detection, use this command in your vimrc: > :filetype on Each time a new or existing file is edited, Vim will try to recognize the type of the file and set the 'filetype' option. This will trigger the FileType event, which can be used to set the syntax highlighting, set options, etc. NOTE: Filetypes and 'compatible' don't work together well, since being Vi compatible means options are global. Resetting 'compatible' is recommended, if you didn't do that already. Detail: The ":filetype on" command will load one of these files: Amiga $VIMRUNTIME/filetype.vim Mac $VIMRUNTIME:filetype.vim MS-Windows $VIMRUNTIME\filetype.vim Unix $VIMRUNTIME/filetype.vim VMS $VIMRUNTIME/filetype.vim This file is a Vim script that defines autocommands for the BufNewFile and BufRead events. If the file type is not found by the name, the file $VIMRUNTIME/scripts.vim is used to detect it from the contents of the file. When the GUI is running or will start soon, the |menu.vim| script is also sourced. See |'go-M'| about avoiding that. To add your own file types, see |new-filetype| below. To search for help on a filetype prepend "ft-" and optionally append "-syntax", "-indent" or "-plugin". For example: > :help ft-vim-indent :help ft-vim-syntax :help ft-man-plugin If the file type is not detected automatically, or it finds the wrong type, you can either set the 'filetype' option manually, or add a modeline to your file. Example, for an IDL file use the command: > :set filetype=idl or add this |modeline| to the file: /* vim: set filetype=idl : */ ~ *:filetype-plugin-on* You can enable loading the plugin files for specific file types with: > :filetype plugin on If filetype detection was not switched on yet, it will be as well. This actually loads the file "ftplugin.vim" in 'runtimepath'. The result is that when a file is edited its plugin file is loaded (if there is one for the detected filetype). |filetype-plugin| *:filetype-plugin-off* You can disable it again with: > :filetype plugin off The filetype detection is not switched off then. But if you do switch off filetype detection, the plugins will not be loaded either. This actually loads the file "ftplugof.vim" in 'runtimepath'. *:filetype-indent-on* You can enable loading the indent file for specific file types with: > :filetype indent on If filetype detection was not switched on yet, it will be as well. This actually loads the file "indent.vim" in 'runtimepath'. The result is that when a file is edited its indent file is loaded (if there is one for the detected filetype). |indent-expression| *:filetype-indent-off* You can disable it again with: > :filetype indent off The filetype detection is not switched off then. But if you do switch off filetype detection, the indent files will not be loaded either. This actually loads the file "indoff.vim" in 'runtimepath'. This disables auto-indenting for files you will open. It will keep working in already opened files. Reset 'autoindent', 'cindent', 'smartindent' and/or 'indentexpr' to disable indenting in an opened file. *:filetype-off* To disable file type detection, use this command: > :filetype off This will keep the flags for "plugin" and "indent", but since no file types are being detected, they won't work until the next ":filetype on". Overview: *:filetype-overview* command detection plugin indent ~ :filetype on on unchanged unchanged :filetype off off unchanged unchanged :filetype plugin on on on unchanged :filetype plugin off unchanged off unchanged :filetype indent on on unchanged on :filetype indent off unchanged unchanged off :filetype plugin indent on on on on :filetype plugin indent off unchanged off off To see the current status, type: > :filetype The output looks something like this: > filetype detection:ON plugin:ON indent:OFF The file types are also used for syntax highlighting. If the ":syntax on" command is used, the file type detection is installed too. There is no need to do ":filetype on" after ":syntax on". To disable one of the file types, add a line in your filetype file, see |remove-filetype|. *filetype-detect* To detect the file type again: > :filetype detect Use this if you started with an empty file and typed text that makes it possible to detect the file type. For example, when you entered this in a shell script: "#!/bin/csh". When filetype detection was off, it will be enabled first, like the "on" argument was used. *filetype-overrule* When the same extension is used for multiple filetypes, Vim tries to guess what kind of file it is. This doesn't always work. A number of global variables can be used to overrule the filetype used for certain extensions: file name variable ~ *.asa g:filetype_asa |ft-aspvbs-syntax| |ft-aspperl-syntax| *.asm g:asmsyntax |ft-asm-syntax| *.asp g:filetype_asp |ft-aspvbs-syntax| |ft-aspperl-syntax| *.bas g:filetype_bas |ft-basic-syntax| *.cfg g:filetype_cfg *.cls g:filetype_cls *.csh g:filetype_csh |ft-csh-syntax| *.dat g:filetype_dat *.frm g:filetype_frm |ft-form-syntax| *.fs g:filetype_fs |ft-forth-syntax| *.i g:filetype_i |ft-progress-syntax| *.inc g:filetype_inc *.lsl g:filetype_lsl *.m g:filetype_m |ft-mathematica-syntax| *.mod g:filetype_mod *.p g:filetype_p |ft-pascal-syntax| *.pl g:filetype_pl *.pp g:filetype_pp |ft-pascal-syntax| *.prg g:filetype_prg *.r g:filetype_r *.sig g:filetype_sig *.sql g:filetype_sql |ft-sql-syntax| *.src g:filetype_src *.sys g:filetype_sys *.sh g:bash_is_sh |ft-sh-syntax| *.tex g:tex_flavor |ft-tex-plugin| *.typ g:filetype_typ *.w g:filetype_w |ft-cweb-syntax| For a few filetypes the global variable is used only when the filetype could not be detected: *.r g:filetype_r |ft-rexx-syntax| *filetype-ignore* To avoid that certain files are being inspected, the g:ft_ignore_pat variable is used. The default value is set like this: > :let g:ft_ignore_pat = '\.\(Z\|gz\|bz2\|zip\|tgz\)$' This means that the contents of compressed files are not inspected. *new-filetype* If a file type that you want to use is not detected yet, there are four ways to add it. In any way, it's better not to modify the $VIMRUNTIME/filetype.vim file. It will be overwritten when installing a new version of Vim. A. If you want to overrule all default file type checks. This works by writing one file for each filetype. The disadvantage is that there can be many files. The advantage is that you can simply drop this file in the right directory to make it work. *ftdetect* 1. Create your user runtime directory. You would normally use the first item of the 'runtimepath' option. Then create the directory "ftdetect" inside it. Example for Unix: > :!mkdir ~/.vim :!mkdir ~/.vim/ftdetect < 2. Create a file that contains an autocommand to detect the file type. Example: > au BufRead,BufNewFile *.mine set filetype=mine < Note that there is no "augroup" command, this has already been done when sourcing your file. You could also use the pattern "*" and then check the contents of the file to recognize it. Write this file as "mine.vim" in the "ftdetect" directory in your user runtime directory. For example, for Unix: > :w ~/.vim/ftdetect/mine.vim < 3. To use the new filetype detection you must restart Vim. The files in the "ftdetect" directory are used after all the default checks, thus they can overrule a previously detected file type. But you can also use |:setfiletype| to keep a previously detected filetype. B. If you want to detect your file after the default file type checks. This works like A above, but instead of setting 'filetype' unconditionally use ":setfiletype". This will only set 'filetype' if no file type was detected yet. Example: > au BufRead,BufNewFile *.txt setfiletype text < You can also use the already detected file type in your command. For example, to use the file type "mypascal" when "pascal" has been detected: > au BufRead,BufNewFile * if &ft == 'pascal' | set ft=mypascal | endif C. If your file type can be detected by the file name. 1. Create your user runtime directory. You would normally use the first item of the 'runtimepath' option. Example for Unix: > :!mkdir ~/.vim < 2. Create a file that contains autocommands to detect the file type. Example: > " my filetype file if exists("did_load_filetypes") finish endif augroup filetypedetect au! BufRead,BufNewFile *.mine setfiletype mine au! BufRead,BufNewFile *.xyz setfiletype drawing augroup END < Write this file as "filetype.vim" in your user runtime directory. For example, for Unix: > :w ~/.vim/filetype.vim < 3. To use the new filetype detection you must restart Vim. Your filetype.vim will be sourced before the default FileType autocommands have been installed. Your autocommands will match first, and the ":setfiletype" command will make sure that no other autocommands will set 'filetype' after this. *new-filetype-scripts* D. If your filetype can only be detected by inspecting the contents of the file. 1. Create your user runtime directory. You would normally use the first item of the 'runtimepath' option. Example for Unix: > :!mkdir ~/.vim < 2. Create a vim script file for doing this. Example: > if did_filetype() " filetype already set.. finish " ..don't do these checks endif if getline(1) =~ '^#!.*\<mine\>' setfiletype mine elseif getline(1) =~? '\<drawing\>' setfiletype drawing endif < See $VIMRUNTIME/scripts.vim for more examples. Write this file as "scripts.vim" in your user runtime directory. For example, for Unix: > :w ~/.vim/scripts.vim < 3. The detection will work right away, no need to restart Vim. Your scripts.vim is loaded before the default checks for file types, which means that your rules override the default rules in $VIMRUNTIME/scripts.vim. *remove-filetype* If a file type is detected that is wrong for you, install a filetype.vim or scripts.vim to catch it (see above). You can set 'filetype' to a non-existing name to avoid that it will be set later anyway: > :set filetype=ignored If you are setting up a system with many users, and you don't want each user to add/remove the same filetypes, consider writing the filetype.vim and scripts.vim files in a runtime directory that is used for everybody. Check the 'runtimepath' for a directory to use. If there isn't one, set 'runtimepath' in the |system-vimrc|. Be careful to keep the default directories! *autocmd-osfiletypes* NOTE: this code is currently disabled, as the RISC OS implementation was removed. In the future this will use the 'filetype' option. On operating systems which support storing a file type with the file, you can specify that an autocommand should only be executed if the file is of a certain type. The actual type checking depends on which platform you are running Vim on; see your system's documentation for details. To use osfiletype checking in an autocommand you should put a list of types to match in angle brackets in place of a pattern, like this: > :au BufRead *.html,<&faf;HTML> runtime! syntax/html.vim This will match: - Any file whose name ends in ".html" - Any file whose type is "&faf" or "HTML", where the meaning of these types depends on which version of Vim you are using. Unknown types are considered NOT to match. You can also specify a type and a pattern at the same time (in which case they must both match): > :au BufRead <&fff>diff* This will match files of type "&fff" whose names start with "diff". *plugin-details* The "plugin" directory can be in any of the directories in the 'runtimepath' option. All of these directories will be searched for plugins and they are all loaded. For example, if this command: > set runtimepath produces this output: runtimepath=/etc/vim,~/.vim,/usr/local/share/vim/vim82 ~ then Vim will load all plugins in these directories and below: /etc/vim/plugin/ ~ ~/.vim/plugin/ ~ /usr/local/share/vim/vim82/plugin/ ~ Note that the last one is the value of $VIMRUNTIME which has been expanded. Note that when using a plugin manager or |packages| many directories will be added to 'runtimepath'. These plugins each require their own directory, don't put them directly in ~/.vim/plugin. What if it looks like your plugin is not being loaded? You can find out what happens when Vim starts up by using the |-V| argument: > vim -V2 You will see a lot of messages, in between them is a remark about loading the plugins. It starts with: Searching for "plugin/**/*.vim" in ~ There you can see where Vim looks for your plugin scripts. ============================================================================== 2. Filetype plugin *filetype-plugins* When loading filetype plugins has been enabled |:filetype-plugin-on|, options will be set and mappings defined. These are all local to the buffer, they will not be used for other files. Defining mappings for a filetype may get in the way of the mappings you define yourself. There are a few ways to avoid this: 1. Set the "maplocalleader" variable to the key sequence you want the mappings to start with. Example: > :let maplocalleader = "," < All mappings will then start with a comma instead of the default, which is a backslash. Also see |<LocalLeader>|. 2. Define your own mapping. Example: > :map ,p <Plug>MailQuote < You need to check the description of the plugin file below for the functionality it offers and the string to map to. You need to define your own mapping before the plugin is loaded (before editing a file of that type). The plugin will then skip installing the default mapping. *no_mail_maps* *g:no_mail_maps* 3. Disable defining mappings for a specific filetype by setting a variable, which contains the name of the filetype. For the "mail" filetype this would be: > :let no_mail_maps = 1 < *no_plugin_maps* *g:no_plugin_maps* 4. Disable defining mappings for all filetypes by setting a variable: > :let no_plugin_maps = 1 < *ftplugin-overrule* If a global filetype plugin does not do exactly what you want, there are three ways to change this: 1. Add a few settings. You must create a new filetype plugin in a directory early in 'runtimepath'. For Unix, for example you could use this file: > vim ~/.vim/ftplugin/fortran.vim < You can set those settings and mappings that you would like to add. Note that the global plugin will be loaded after this, it may overrule the settings that you do here. If this is the case, you need to use one of the following two methods. 2. Make a copy of the plugin and change it. You must put the copy in a directory early in 'runtimepath'. For Unix, for example, you could do this: > cp $VIMRUNTIME/ftplugin/fortran.vim ~/.vim/ftplugin/fortran.vim < Then you can edit the copied file to your liking. Since the b:did_ftplugin variable will be set, the global plugin will not be loaded. A disadvantage of this method is that when the distributed plugin gets improved, you will have to copy and modify it again. 3. Overrule the settings after loading the global plugin. You must create a new filetype plugin in a directory from the end of 'runtimepath'. For Unix, for example, you could use this file: > vim ~/.vim/after/ftplugin/fortran.vim < In this file you can change just those settings that you want to change. ============================================================================== 3. Docs for the default filetype plugins. *ftplugin-docs* AWK *ft-awk-plugin* Support for features specific to GNU Awk, like @include, can be enabled by setting: > let g:awk_is_gawk = 1 CHANGELOG *ft-changelog-plugin* Allows for easy entrance of Changelog entries in Changelog files. There are some commands, mappings, and variables worth exploring: Options: 'comments' is made empty to not mess up formatting. 'textwidth' is set to 78, which is standard. 'formatoptions' the 't' flag is added to wrap when inserting text. Commands: NewChangelogEntry Adds a new Changelog entry in an intelligent fashion (see below). Local mappings: <Leader>o Starts a new Changelog entry in an equally intelligent fashion (see below). Global mappings: NOTE: The global mappings are accessed by sourcing the ftplugin/changelog.vim file first, e.g. with > runtime ftplugin/changelog.vim < in your |.vimrc|. <Leader>o Switches to the ChangeLog buffer opened for the current directory, or opens it in a new buffer if it exists in the current directory. Then it does the same as the local <Leader>o described above. Variables: g:changelog_timeformat Deprecated; use g:changelog_dateformat instead. g:changelog_dateformat The date (and time) format used in ChangeLog entries. The format accepted is the same as for the |strftime()| function. The default is "%Y-%m-%d" which is the standard format for many ChangeLog layouts. g:changelog_username The name and email address of the user. The default is deduced from environment variables and system files. It searches /etc/passwd for the comment part of the current user, which informally contains the real name of the user up to the first separating comma. then it checks the $NAME environment variable and finally runs `whoami` and `hostname` to build an email address. The final form is > Full Name <user@host> < g:changelog_new_date_format The format to use when creating a new date-entry. The following table describes special tokens in the string: %% insert a single '%' character %d insert the date from above %u insert the user from above %p insert result of b:changelog_entry_prefix %c where to position cursor when done The default is "%d %u\n\n\t* %p%c\n\n", which produces something like (| is where cursor will be, unless at the start of the line where it denotes the beginning of the line) > |2003-01-14 Full Name <user@host> | | * prefix| < g:changelog_new_entry_format The format used when creating a new entry. The following table describes special tokens in the string: %p insert result of b:changelog_entry_prefix %c where to position cursor when done The default is "\t*%c", which produces something similar to > | * prefix| < g:changelog_date_entry_search The search pattern to use when searching for a date-entry. The same tokens that can be used for g:changelog_new_date_format can be used here as well. The default is '^\s*%d\_s*%u' which finds lines matching the form > |2003-01-14 Full Name <user@host> < and some similar formats. g:changelog_date_end_entry_search The search pattern to use when searching for the end of a date-entry. The same tokens that can be used for g:changelog_new_date_format can be used here as well. The default is '^\s*$' which finds lines that contain only whitespace or are completely empty. b:changelog_name *b:changelog_name* Name of the ChangeLog file to look for. The default is 'ChangeLog'. b:changelog_path Path of the ChangeLog to use for the current buffer. The default is empty, thus looking for a file named |b:changelog_name| in the same directory as the current buffer. If not found, the parent directory of the current buffer is searched. This continues recursively until a file is found or there are no more parent directories to search. b:changelog_entry_prefix Name of a function to call to generate a prefix to a new entry. This function takes no arguments and should return a string containing the prefix. Returning an empty prefix is fine. The default generates the shortest path between the ChangeLog's pathname and the current buffers pathname. In the future, it will also be possible to use other variable contexts for this variable, for example, g:. The Changelog entries are inserted where they add the least amount of text. After figuring out the current date and user, the file is searched for an entry beginning with the current date and user and if found adds another item under it. If not found, a new entry and item is prepended to the beginning of the Changelog. FORTRAN *ft-fortran-plugin* Options: 'expandtab' is switched on to avoid tabs as required by the Fortran standards unless the user has set fortran_have_tabs in .vimrc. 'textwidth' is set to 72 for fixed source format as required by the Fortran standards and to 80 for free source format. 'formatoptions' is set to break code and comment lines and to preserve long lines. You can format comments with |gq|. For further discussion of fortran_have_tabs and the method used for the detection of source format see |ft-fortran-syntax|. FREEBASIC *ft-freebasic-plugin* This plugin aims to treat the four FreeBASIC dialects, "fb", "qb", "fblite" and "deprecated", as distinct languages. The dialect will be set to the first name found in g:freebasic_forcelang, any #lang directive or $lang metacommand in the file being edited, or finally g:freebasic_lang. These global variables conceptually map to the fbc options -forcelang and -lang. If no dialect is explicitly specified "fb" will be used. For example, to set the dialect to a default of "fblite" but still allow for any #lang directive overrides, use the following command: > let g:freebasic_lang = "fblite" GIT COMMIT *ft-gitcommit-plugin* One command, :DiffGitCached, is provided to show a diff of the current commit in the preview window. It is equivalent to calling "git diff --cached" plus any arguments given to the command. GPROF *ft-gprof-plugin* The gprof filetype plugin defines a mapping <C-]> to jump from a function entry in the gprof flat profile or from a function entry in the call graph to the details of that function in the call graph. The mapping can be disabled with: > let g:no_gprof_maps = 1 MAIL *ft-mail-plugin* Options: 'modeline' is switched off to avoid the danger of trojan horses, and to avoid that a Subject line with "Vim:" in it will cause an error message. 'textwidth' is set to 72. This is often recommended for e-mail. 'formatoptions' is set to break text lines and to repeat the comment leader in new lines, so that a leading ">" for quotes is repeated. You can also format quoted text with |gq|. Local mappings: <LocalLeader>q or \\MailQuote Quotes the text selected in Visual mode, or from the cursor position to the end of the file in Normal mode. This means "> " is inserted in each line. MAN *ft-man-plugin* *:Man* *man.vim* This plugin displays a manual page in a nice way. See |find-manpage| in the user manual for more information. To start using the |:Man| command before any manual page has been loaded, source this script from your startup |vimrc| file: > runtime ftplugin/man.vim Options: 'iskeyword' The '.' character is added to support the use of CTRL-] on the manual page name. Commands: Man {name} Display the manual page for {name} in a window. Man {number} {name} Display the manual page for {name} in a section {number}. Global mapping: <Leader>K Displays the manual page for the word under the cursor. <Plug>ManPreGetPage idem, allows for using a mapping: > nmap <F1> <Plug>ManPreGetPage Local mappings: CTRL-] Jump to the manual page for the word under the cursor. CTRL-T Jump back to the previous manual page. q Same as the |:quit| command. To use a vertical split instead of horizontal: > let g:ft_man_open_mode = 'vert' To use a new tab: > let g:ft_man_open_mode = 'tab' To enable |folding|, use this: > let g:ft_man_folding_enable = 1 If you do not like the default folding, use an |autocommand| to add your desired folding style instead. For example: > autocmd FileType man setlocal foldmethod=indent foldenable If you would like :Man {number} {name} to behave like man {number} {name} by not running man {name} if no page is found, then use this: > let g:ft_man_no_sect_fallback = 1 You may also want to set 'keywordprg' to make the |K| command open a manual page in a Vim window: > set keywordprg=:Man MANPAGER *manpager.vim* The |:Man| command allows you to turn Vim into a manpager (that syntax highlights manpages and follows linked manpages on hitting CTRL-]). For bash,zsh,ksh or dash, add to the config file (.bashrc,.zshrc, ...) export MANPAGER="vim +MANPAGER --not-a-term -" For (t)csh, add to the config file setenv MANPAGER "vim +MANPAGER --not-a-term -" For fish, add to the config file set -x MANPAGER "vim +MANPAGER --not-a-term -" MARKDOWN *ft-markdown-plugin* To enable folding use this: > let g:markdown_folding = 1 'expandtab' will be set by default. If you do not want that use this: > let g:markdown_recommended_style = 0 PDF *ft-pdf-plugin* Two maps, <C-]> and <C-T>, are provided to simulate a tag stack for navigating the PDF. The following are treated as tags: - The byte offset after "startxref" to the xref table - The byte offset after the /Prev key in the trailer to an earlier xref table - A line of the form "0123456789 00000 n" in the xref table - An object reference like "1 0 R" anywhere in the PDF These maps can be disabled with > :let g:no_pdf_maps = 1 < PYTHON *ft-python-plugin* *PEP8* By default the following options are set, in accordance with PEP8: > setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8 To disable this behavior, set the following variable in your vimrc: > let g:python_recommended_style = 0 QF QUICKFIX *qf.vim* *ft-qf-plugin* The "qf" filetype is used for the quickfix window, see |quickfix-window|. The quickfix filetype plugin includes configuration for displaying the command that produced the quickfix list in the |status-line|. To disable this setting, configure as follows: > :let g:qf_disable_statusline = 1 R MARKDOWN *ft-rmd-plugin* By default ftplugin/html.vim is not sourced. If you want it sourced, add to your |vimrc|: > let rmd_include_html = 1 The 'formatexpr' option is set dynamically with different values for R code and for Markdown code. If you prefer that 'formatexpr' is not set, add to your |vimrc|: > let rmd_dynamic_comments = 0 R RESTRUCTURED TEXT *ft-rrst-plugin* The 'formatexpr' option is set dynamically with different values for R code and for ReStructured text. If you prefer that 'formatexpr' is not set, add to your |vimrc|: > let rrst_dynamic_comments = 0 RESTRUCTUREDTEXT *ft-rst-plugin* The following formatting setting are optionally available: > setlocal expandtab shiftwidth=3 softtabstop=3 tabstop=8 To enable this behavior, set the following variable in your vimrc: > let g:rst_style = 1 RPM SPEC *ft-spec-plugin* Since the text for this plugin is rather long it has been put in a separate file: |pi_spec.txt|. RUST *ft-rust* Since the text for this plugin is rather long it has been put in a separate file: |ft_rust.txt|. SQL *ft-sql* Since the text for this plugin is rather long it has been put in a separate file: |ft_sql.txt|. TEX *ft-tex-plugin* *g:tex_flavor* If the first line of a *.tex file has the form > %&<format> then this determined the file type: plaintex (for plain TeX), context (for ConTeXt), or tex (for LaTeX). Otherwise, the file is searched for keywords to choose context or tex. If no keywords are found, it defaults to plaintex. You can change the default by defining the variable g:tex_flavor to the format (not the file type) you use most. Use one of these: > let g:tex_flavor = "plain" let g:tex_flavor = "context" let g:tex_flavor = "latex" Currently no other formats are recognized. VIM *ft-vim-plugin* The Vim filetype plugin defines mappings to move to the start and end of functions with [[ and ]]. Move around comments with ]" and [". The mappings can be disabled with: > let g:no_vim_maps = 1 ZIMBU *ft-zimbu-plugin* The Zimbu filetype plugin defines mappings to move to the start and end of functions with [[ and ]]. The mappings can be disabled with: > let g:no_zimbu_maps = 1 < vim:tw=78:ts=8:noet:ft=help:norl: