Merge remote-tracking branch 'upstream/master' into userreguserreg

1 files changed, 10127 insertions, 2888 deletions

diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index a7f7ca2cf7..0e2bd83806 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -1,2912 +1,10151 @@
--- {
---  {
---    full_name='aleph', abbreviation='al',
---    short_desc="ASCII code of the letter Aleph (Hebrew)",
---    varname='p_aleph', pv_name=nil,
---    type='number', list=nil, scope={'global'},
---    deny_duplicates=nil,
---    enable_if=nil,
---    defaults={condition=nil, if_true=224, if_false=nil},
---    secure=nil, gettext=nil, noglob=nil, normal_fname_chars=nil,
---    pri_mkrc=nil, deny_in_modelines=nil, normal_dname_chars=nil,
---    modelineexpr=nil,
---    func=nil,
---    expand=nil, nodefault=nil, no_mkrc=nil,
---    alloced=nil,
---    save_pv_indir=nil,
---    redraw={'curswant'},
---  }
--- }
--- types: bool, number, string
--- lists: (nil), comma, onecomma, flags, flagscomma
--- scopes: global, buffer, window
--- redraw options: statuslines, tabline, current_window, current_window_only,
---                 current_buffer, all_windows, curswant
--- defaults: {condition=#if condition, if_true=default, if_false=default}
--- #if condition:
---    string: #ifdef string
---    !string: #ifndef string
---    {string, string}: #if defined(string) && defined(string)
---    {!string, !string}: #if !defined(string) && !defined(string)
-local cstr = function(s)
+--- @class vim.option_meta
+--- @field full_name string
+--- @field desc? string
+--- @field abbreviation? string
+--- @field short_desc? string|fun(): string
+--- @field varname? string
+--- @field pv_name? string
+--- @field type 'bool'|'number'|'string'
+--- @field immutable? boolean
+--- @field list? 'comma'|'onecomma'|'commacolon'|'onecommacolon'|'flags'|'flagscomma'
+--- @field scope vim.option_scope[]
+--- @field deny_duplicates? boolean
+--- @field enable_if? string|false
+--- @field defaults? vim.option_defaults
+--- @field secure? true
+--- @field noglob? true
+--- @field normal_fname_chars? true
+--- @field pri_mkrc? true
+--- @field deny_in_modelines? true
+--- @field normal_dname_chars? true
+--- @field modelineexpr? true
+--- @field func? true
+--- @field expand? string|true
+--- @field nodefault? true
+--- @field no_mkrc? true
+--- @field alloced? true
+--- @field redraw? vim.option_redraw[]
+--- @field cb? string
+--- @field expand_cb? string
+--- @field tags? string[]
+
+--- @class vim.option_defaults
+--- @field condition? string
+---    string: #ifdef string
+---    !string: #ifndef string
+--- @field if_true integer|boolean|string|fun(): string
+--- @field if_false? integer|boolean|string
+--- @field doc? string Default to show in options.txt
+--- @field meta? integer|boolean|string Default to use in Lua meta files
+
+--- @alias vim.option_scope 'global'|'buffer'|'window'
+
+--- @alias vim.option_redraw
+--- |'statuslines'
+--- |'tabline'
+--- |'current_window'
+--- |'current_window_only'
+--- |'current_buffer'
+--- |'all_windows'
+--- |'curswant'
+--- |'ui_option'
+
+--- @param s string
+--- @return string
+local function cstr(s)
   return '"' .. s:gsub('["\\]', '\\%0'):gsub('\t', '\\t') .. '"'
 end
-local macros=function(s)
+
+--- @param s string
+--- @return fun(): string
+local function macros(s)
   return function()
     return s
   end
 end
-local imacros=function(s)
+
+--- @param s string
+--- @return fun(): string
+local function imacros(s)
   return function()
     return '(intptr_t)' .. s
   end
 end
-local N_=function(s) -- luacheck: ignore 211 (currently unused)
+
+--- @param s string
+--- @return fun(): string
+local function N_(s) -- luacheck: ignore 211 (currently unused)
   return function()
     return 'N_(' .. cstr(s) .. ')'
   end
 end
--- used for 'cinkeys' and 'indentkeys'
-local indentkeys_default = '0{,0},0),0],:,0#,!^F,o,O,e';
+
+-- luacheck: ignore 621
 return {
-  cstr=cstr,
-  options={
-    {
-      full_name='aleph', abbreviation='al',
-      short_desc=N_("ASCII code of the letter Aleph (Hebrew)"),
-      type='number', scope={'global'},
-      redraw={'curswant'},
-      varname='p_aleph',
-      defaults={if_true=224}
-    },
-    {
-      full_name='arabic', abbreviation='arab',
-      short_desc=N_("Arabic as a default second language"),
-      type='bool', scope={'window'},
-      redraw={'curswant'},
-      defaults={if_true=false}
-    },
-    {
-      full_name='arabicshape', abbreviation='arshape',
-      short_desc=N_("do shaping for Arabic characters"),
-      type='bool', scope={'global'},
-      redraw={'all_windows', 'ui_option'},
+  cstr = cstr,
+  --- @type vim.option_meta[]
+  options = {
+    {
+      abbreviation = 'al',
+      defaults = { if_true = 224 },
+      full_name = 'aleph',
+      scope = { 'global' },
+      short_desc = N_('ASCII code of the letter Aleph (Hebrew)'),
+      type = 'number',
+    },
+    {
+      abbreviation = 'arab',
+      cb = 'did_set_arabic',
+      defaults = { if_true = false },
+      desc = [=[
+        This option can be set to start editing Arabic text.
+        Setting this option will:
+        - Set the 'rightleft' option, unless 'termbidi' is set.
+        - Set the 'arabicshape' option, unless 'termbidi' is set.
+        - Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles
+          between typing English and Arabic key mapping.
+        - Set the 'delcombine' option
 
-      varname='p_arshape',
-      defaults={if_true=true}
-    },
-    {
-      full_name='allowrevins', abbreviation='ari',
-      short_desc=N_("allow CTRL-_ in Insert and Command-line mode"),
-      type='bool', scope={'global'},
-      varname='p_ari',
-      defaults={if_true=false}
-    },
-    {
-      full_name='ambiwidth', abbreviation='ambw',
-      short_desc=N_("what to do with Unicode chars of ambiguous width"),
-      type='string', scope={'global'},
-      redraw={'all_windows', 'ui_option'},
-      varname='p_ambw',
-      defaults={if_true="single"}
-    },
-    {
-      full_name='autochdir', abbreviation='acd',
-      short_desc=N_("change directory to the file in the current window"),
-      type='bool', scope={'global'},
-      varname='p_acd',
-      defaults={if_true=false}
-    },
-    {
-      full_name='autoindent', abbreviation='ai',
-      short_desc=N_("take indent for new line from previous line"),
-      type='bool', scope={'buffer'},
-      varname='p_ai',
-      defaults={if_true=true}
-    },
-    {
-      full_name='autoread', abbreviation='ar',
-      short_desc=N_("autom. read file when changed outside of Vim"),
-      type='bool', scope={'global', 'buffer'},
-      varname='p_ar',
-      defaults={if_true=true}
-    },
-    {
-      full_name='autowrite', abbreviation='aw',
-      short_desc=N_("automatically write file if changed"),
-      type='bool', scope={'global'},
-      varname='p_aw',
-      defaults={if_true=false}
-    },
-    {
-      full_name='autowriteall', abbreviation='awa',
-      short_desc=N_("as 'autowrite', but works with more commands"),
-      type='bool', scope={'global'},
-      varname='p_awa',
-      defaults={if_true=false}
-    },
-    {
-      full_name='background', abbreviation='bg',
-      short_desc=N_("\"dark\" or \"light\", used for highlight colors"),
-      type='string', scope={'global'},
-      varname='p_bg',
-      defaults={if_true="dark"}
-    },
-    {
-      full_name='backspace', abbreviation='bs',
-      short_desc=N_("how backspace works at start of line"),
-      type='string', list='onecomma', scope={'global'},
-      deny_duplicates=true,
-      varname='p_bs',
-      defaults={if_true="indent,eol,start"}
-    },
-    {
-      full_name='backup', abbreviation='bk',
-      short_desc=N_("keep backup file after overwriting a file"),
-      type='bool', scope={'global'},
-      varname='p_bk',
-      defaults={if_true=false}
-    },
-    {
-      full_name='backupcopy', abbreviation='bkc',
-      short_desc=N_("make backup as a copy, don't rename the file"),
-      type='string', list='onecomma', scope={'global', 'buffer'},
-      deny_duplicates=true,
-      varname='p_bkc',
-      defaults={
-        condition='UNIX',
-        if_true="auto",
-        if_false="auto"
+        Resetting this option will:
+        - Reset the 'rightleft' option.
+        - Disable the use of 'keymap' (without changing its value).
+        Note that 'arabicshape' and 'delcombine' are not reset (it is a global
+        option).
+        Also see |arabic.txt|.
+      ]=],
+      full_name = 'arabic',
+      redraw = { 'curswant' },
+      scope = { 'window' },
+      short_desc = N_('Arabic as a default second language'),
+      type = 'bool',
+    },
+    {
+      abbreviation = 'arshape',
+      defaults = { if_true = true },
+      desc = [=[
+        When on and 'termbidi' is off, the required visual character
+        corrections that need to take place for displaying the Arabic language
+        take effect.  Shaping, in essence, gets enabled; the term is a broad
+        one which encompasses:
+          a) the changing/morphing of characters based on their location
+             within a word (initial, medial, final and stand-alone).
+          b) the enabling of the ability to compose characters
+          c) the enabling of the required combining of some characters
+        When disabled the display shows each character's true stand-alone
+        form.
+        Arabic is a complex language which requires other settings, for
+        further details see |arabic.txt|.
+      ]=],
+      full_name = 'arabicshape',
+      redraw = { 'all_windows', 'ui_option' },
+      scope = { 'global' },
+      short_desc = N_('do shaping for Arabic characters'),
+      type = 'bool',
+      varname = 'p_arshape',
+    },
+    {
+      abbreviation = 'ari',
+      defaults = { if_true = false },
+      desc = [=[
+        Allow CTRL-_ in Insert and Command-line mode.  This is default off, to
+        avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get
+        into reverse Insert mode, and don't know how to get out.  See
+        'revins'.
+      ]=],
+      full_name = 'allowrevins',
+      scope = { 'global' },
+      short_desc = N_('allow CTRL-_ in Insert and Command-line mode'),
+      type = 'bool',
+      varname = 'p_ari',
+    },
+    {
+      abbreviation = 'ambw',
+      cb = 'did_set_ambiwidth',
+      defaults = { if_true = 'single' },
+      desc = [=[
+        Tells Vim what to do with characters with East Asian Width Class
+        Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek
+        letters, Cyrillic letters).
+
+        There are currently two possible values:
+        "single":	Use the same width as characters in US-ASCII.  This is
+        		expected by most users.
+        "double":	Use twice the width of ASCII characters.
+        						*E834* *E835*
+        The value "double" cannot be used if 'listchars' or 'fillchars'
+        contains a character that would be double width.  These errors may
+        also be given when calling setcellwidths().
+
+        The values are overruled for characters specified with
+        |setcellwidths()|.
+
+        There are a number of CJK fonts for which the width of glyphs for
+        those characters are solely based on how many octets they take in
+        legacy/traditional CJK encodings.  In those encodings, Euro,
+        Registered sign, Greek/Cyrillic letters are represented by two octets,
+        therefore those fonts have "wide" glyphs for them.  This is also
+        true of some line drawing characters used to make tables in text
+        file.  Therefore, when a CJK font is used for GUI Vim or
+        Vim is running inside a terminal (emulators) that uses a CJK font
+        (or Vim is run inside an xterm invoked with "-cjkwidth" option.),
+        this option should be set to "double" to match the width perceived
+        by Vim with the width of glyphs in the font.  Perhaps it also has
+        to be set to "double" under CJK MS-Windows when the system locale is
+        set to one of CJK locales.  See Unicode Standard Annex #11
+        (https://www.unicode.org/reports/tr11).
+      ]=],
+      expand_cb = 'expand_set_ambiwidth',
+      full_name = 'ambiwidth',
+      redraw = { 'all_windows', 'ui_option' },
+      scope = { 'global' },
+      short_desc = N_('what to do with Unicode chars of ambiguous width'),
+      type = 'string',
+      varname = 'p_ambw',
+    },
+    {
+      abbreviation = 'acd',
+      cb = 'did_set_autochdir',
+      defaults = { if_true = false },
+      desc = [=[
+        When on, Vim will change the current working directory whenever you
+        open a file, switch buffers, delete a buffer or open/close a window.
+        It will change to the directory containing the file which was opened
+        or selected.  When a buffer has no name it also has no directory, thus
+        the current directory won't change when navigating to it.
+        Note: When this option is on some plugins may not work.
+      ]=],
+      full_name = 'autochdir',
+      scope = { 'global' },
+      short_desc = N_('change directory to the file in the current window'),
+      type = 'bool',
+      varname = 'p_acd',
+    },
+    {
+      abbreviation = 'ai',
+      defaults = { if_true = true },
+      desc = [=[
+        Copy indent from current line when starting a new line (typing <CR>
+        in Insert mode or when using the "o" or "O" command).  If you do not
+        type anything on the new line except <BS> or CTRL-D and then type
+        <Esc>, CTRL-O or <CR>, the indent is deleted again.  Moving the cursor
+        to another line has the same effect, unless the 'I' flag is included
+        in 'cpoptions'.
+        When autoindent is on, formatting (with the "gq" command or when you
+        reach 'textwidth' in Insert mode) uses the indentation of the first
+        line.
+        When 'smartindent' or 'cindent' is on the indent is changed in
+        a different way.
+      ]=],
+      full_name = 'autoindent',
+      scope = { 'buffer' },
+      short_desc = N_('take indent for new line from previous line'),
+      type = 'bool',
+      varname = 'p_ai',
+    },
+    {
+      abbreviation = 'ar',
+      defaults = { if_true = true },
+      desc = [=[
+        When a file has been detected to have been changed outside of Vim and
+        it has not been changed inside of Vim, automatically read it again.
+        When the file has been deleted this is not done, so you have the text
+        from before it was deleted.  When it appears again then it is read.
+        |timestamp|
+        If this option has a local value, use this command to switch back to
+        using the global value: >
+        	:set autoread<
+        <
+      ]=],
+      full_name = 'autoread',
+      scope = { 'global', 'buffer' },
+      short_desc = N_('autom. read file when changed outside of Vim'),
+      type = 'bool',
+      varname = 'p_ar',
+    },
+    {
+      abbreviation = 'aw',
+      defaults = { if_true = false },
+      desc = [=[
+        Write the contents of the file, if it has been modified, on each
+        `:next`, `:rewind`, `:last`, `:first`, `:previous`, `:stop`,
+        `:suspend`, `:tag`, `:!`, `:make`, CTRL-] and CTRL-^ command; and when
+        a `:buffer`, CTRL-O, CTRL-I, '{A-Z0-9}, or `{A-Z0-9} command takes one
+        to another file.
+        A buffer is not written if it becomes hidden, e.g. when 'bufhidden' is
+        set to "hide" and `:next` is used.
+        Note that for some commands the 'autowrite' option is not used, see
+        'autowriteall' for that.
+        Some buffers will not be written, specifically when 'buftype' is
+        "nowrite", "nofile", "terminal" or "prompt".
+        USE WITH CARE: If you make temporary changes to a buffer that you
+        don't want to be saved this option may cause it to be saved anyway.
+        Renaming the buffer with ":file {name}" may help avoid this.
+      ]=],
+      full_name = 'autowrite',
+      scope = { 'global' },
+      short_desc = N_('automatically write file if changed'),
+      type = 'bool',
+      varname = 'p_aw',
+    },
+    {
+      abbreviation = 'awa',
+      defaults = { if_true = false },
+      desc = [=[
+        Like 'autowrite', but also used for commands ":edit", ":enew", ":quit",
+        ":qall", ":exit", ":xit", ":recover" and closing the Vim window.
+        Setting this option also implies that Vim behaves like 'autowrite' has
+        been set.
+      ]=],
+      full_name = 'autowriteall',
+      scope = { 'global' },
+      short_desc = N_("as 'autowrite', but works with more commands"),
+      type = 'bool',
+      varname = 'p_awa',
+    },
+    {
+      abbreviation = 'bg',
+      cb = 'did_set_background',
+      defaults = { if_true = 'dark' },
+      desc = [=[
+        When set to "dark" or "light", adjusts the default color groups for
+        that background type.  The |TUI| or other UI sets this on startup
+        (triggering |OptionSet|) if it can detect the background color.
+
+        This option does NOT change the background color, it tells Nvim what
+        the "inherited" (terminal/GUI) background looks like.
+        See |:hi-normal| if you want to set the background color explicitly.
+        					*g:colors_name*
+        When a color scheme is loaded (the "g:colors_name" variable is set)
+        setting 'background' will cause the color scheme to be reloaded.  If
+        the color scheme adjusts to the value of 'background' this will work.
+        However, if the color scheme sets 'background' itself the effect may
+        be undone.  First delete the "g:colors_name" variable when needed.
+
+        Normally this option would be set in the vimrc file.  Possibly
+        depending on the terminal name.  Example: >
+        	:if $TERM ==# "xterm"
+        	:  set background=dark
+        	:endif
+        <	When this option is set, the default settings for the highlight groups
+        will change.  To use other settings, place ":highlight" commands AFTER
+        the setting of the 'background' option.
+        This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file
+        to select the colors for syntax highlighting.  After changing this
+        option, you must load syntax.vim again to see the result.  This can be
+        done with ":syntax on".
+      ]=],
+      expand_cb = 'expand_set_background',
+      full_name = 'background',
+      scope = { 'global' },
+      short_desc = N_('"dark" or "light", used for highlight colors'),
+      type = 'string',
+      varname = 'p_bg',
+    },
+    {
+      abbreviation = 'bs',
+      cb = 'did_set_backspace',
+      defaults = { if_true = 'indent,eol,start' },
+      deny_duplicates = true,
+      desc = [=[
+        Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert
+        mode.  This is a list of items, separated by commas.  Each item allows
+        a way to backspace over something:
+        value	effect	~
+        indent	allow backspacing over autoindent
+        eol	allow backspacing over line breaks (join lines)
+        start	allow backspacing over the start of insert; CTRL-W and CTRL-U
+        	stop once at the start of insert.
+        nostop	like start, except CTRL-W and CTRL-U do not stop at the start of
+        	insert.
+
+        When the value is empty, Vi compatible backspacing is used, none of
+        the ways mentioned for the items above are possible.
+      ]=],
+      expand_cb = 'expand_set_backspace',
+      full_name = 'backspace',
+      list = 'onecomma',
+      scope = { 'global' },
+      short_desc = N_('how backspace works at start of line'),
+      type = 'string',
+      varname = 'p_bs',
+    },
+    {
+      abbreviation = 'bk',
+      defaults = { if_true = false },
+      desc = [=[
+        Make a backup before overwriting a file.  Leave it around after the
+        file has been successfully written.  If you do not want to keep the
+        backup file, but you do want a backup while the file is being
+        written, reset this option and set the 'writebackup' option (this is
+        the default).  If you do not want a backup file at all reset both
+        options (use this if your file system is almost full).  See the
+        |backup-table| for more explanations.
+        When the 'backupskip' pattern matches, a backup is not made anyway.
+        When 'patchmode' is set, the backup may be renamed to become the
+        oldest version of a file.
+      ]=],
+      full_name = 'backup',
+      scope = { 'global' },
+      short_desc = N_('keep backup file after overwriting a file'),
+      type = 'bool',
+      varname = 'p_bk',
+    },
+    {
+      abbreviation = 'bkc',
+      cb = 'did_set_backupcopy',
+      defaults = { condition = 'UNIX', if_false = 'auto', if_true = 'auto' },
+      deny_duplicates = true,
+      desc = [=[
+        When writing a file and a backup is made, this option tells how it's
+        done.  This is a comma-separated list of words.
+
+        The main values are:
+        "yes"	make a copy of the file and overwrite the original one
+        "no"	rename the file and write a new one
+        "auto"	one of the previous, what works best
+
+        Extra values that can be combined with the ones above are:
+        "breaksymlink"	always break symlinks when writing
+        "breakhardlink"	always break hardlinks when writing
+
+        Making a copy and overwriting the original file:
+        - Takes extra time to copy the file.
+        + When the file has special attributes, is a (hard/symbolic) link or
+          has a resource fork, all this is preserved.
+        - When the file is a link the backup will have the name of the link,
+          not of the real file.
+
+        Renaming the file and writing a new one:
+        + It's fast.
+        - Sometimes not all attributes of the file can be copied to the new
+          file.
+        - When the file is a link the new file will not be a link.
+
+        The "auto" value is the middle way: When Vim sees that renaming the
+        file is possible without side effects (the attributes can be passed on
+        and the file is not a link) that is used.  When problems are expected,
+        a copy will be made.
+
+        The "breaksymlink" and "breakhardlink" values can be used in
+        combination with any of "yes", "no" and "auto".  When included, they
+        force Vim to always break either symbolic or hard links by doing
+        exactly what the "no" option does, renaming the original file to
+        become the backup and writing a new file in its place.  This can be
+        useful for example in source trees where all the files are symbolic or
+        hard links and any changes should stay in the local source tree, not
+        be propagated back to the original source.
+        						*crontab*
+        One situation where "no" and "auto" will cause problems: A program
+        that opens a file, invokes Vim to edit that file, and then tests if
+        the open file was changed (through the file descriptor) will check the
+        backup file instead of the newly created file.  "crontab -e" is an
+        example.
+
+        When a copy is made, the original file is truncated and then filled
+        with the new text.  This means that protection bits, owner and
+        symbolic links of the original file are unmodified.  The backup file,
+        however, is a new file, owned by the user who edited the file.  The
+        group of the backup is set to the group of the original file.  If this
+        fails, the protection bits for the group are made the same as for
+        others.
+
+        When the file is renamed, this is the other way around: The backup has
+        the same attributes of the original file, and the newly written file
+        is owned by the current user.  When the file was a (hard/symbolic)
+        link, the new file will not!  That's why the "auto" value doesn't
+        rename when the file is a link.  The owner and group of the newly
+        written file will be set to the same ones as the original file, but
+        the system may refuse to do this.  In that case the "auto" value will
+        again not rename the file.
+      ]=],
+      expand_cb = 'expand_set_backupcopy',
+      full_name = 'backupcopy',
+      list = 'onecomma',
+      scope = { 'global', 'buffer' },
+      short_desc = N_("make backup as a copy, don't rename the file"),
+      type = 'string',
+      varname = 'p_bkc',
+    },
+    {
+      abbreviation = 'bdir',
+      defaults = { if_true = '' },
+      deny_duplicates = true,
+      desc = [=[
+        List of directories for the backup file, separated with commas.
+        - The backup file will be created in the first directory in the list
+          where this is possible.  If none of the directories exist Nvim will
+          attempt to create the last directory in the list.
+        - Empty means that no backup file will be created ('patchmode' is
+          impossible!).  Writing may fail because of this.
+        - A directory "." means to put the backup file in the same directory
+          as the edited file.
+        - A directory starting with "./" (or ".\" for MS-Windows) means to put
+          the backup file relative to where the edited file is.  The leading
+          "." is replaced with the path name of the edited file.
+          ("." inside a directory name has no special meaning).
+        - Spaces after the comma are ignored, other spaces are considered part
+          of the directory name.  To have a space at the start of a directory
+          name, precede it with a backslash.
+        - To include a comma in a directory name precede it with a backslash.
+        - A directory name may end in an '/'.
+        - For Unix and Win32, if a directory ends in two path separators "//",
+          the swap file name will be built from the complete path to the file
+          with all path separators changed to percent '%' signs. This will
+          ensure file name uniqueness in the backup directory.
+          On Win32, it is also possible to end with "\\".  However, When a
+          separating comma is following, you must use "//", since "\\" will
+          include the comma in the file name. Therefore it is recommended to
+          use '//', instead of '\\'.
+        - Environment variables are expanded |:set_env|.
+        - Careful with '\' characters, type one before a space, type two to
+          get one in the option (see |option-backslash|), for example: >
+            :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
+        <
+        See also 'backup' and 'writebackup' options.
+        If you want to hide your backup files on Unix, consider this value: >
+        	:set backupdir=./.backup,~/.backup,.,/tmp
+        <	You must create a ".backup" directory in each directory and in your
+        home directory for this to work properly.
+        The use of |:set+=| and |:set-=| is preferred when adding or removing
+        directories from the list.  This avoids problems when a future version
+        uses another default.
+        This option cannot be set from a |modeline| or in the |sandbox|, for
+        security reasons.
+      ]=],
+      expand = 'nodefault',
+      full_name = 'backupdir',
+      list = 'onecomma',
+      scope = { 'global' },
+      secure = true,
+      short_desc = N_('list of directories for the backup file'),
+      type = 'string',
+      varname = 'p_bdir',
+    },
+    {
+      abbreviation = 'bex',
+      cb = 'did_set_backupext_or_patchmode',
+      defaults = { if_true = '~' },
+      desc = [=[
+        String which is appended to a file name to make the name of the
+        backup file.  The default is quite unusual, because this avoids
+        accidentally overwriting existing files with a backup file.  You might
+        prefer using ".bak", but make sure that you don't have files with
+        ".bak" that you want to keep.
+        Only normal file name characters can be used; `/\*?[|<>` are illegal.
+
+        If you like to keep a lot of backups, you could use a BufWritePre
+        autocommand to change 'backupext' just before writing the file to
+        include a timestamp. >
+        	:au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~'
+        <	Use 'backupdir' to put the backup in a different directory.
+      ]=],
+      full_name = 'backupext',
+      normal_fname_chars = true,
+      scope = { 'global' },
+      short_desc = N_('extension used for the backup file'),
+      tags = { 'E589' },
+      type = 'string',
+      varname = 'p_bex',
+    },
+    {
+      abbreviation = 'bsk',
+      defaults = {
+        if_true = '',
+        doc = [["$TMPDIR/*,$TMP/*,$TEMP/*"
+        Unix: "/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*"
+        Mac: "/private/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*"]],
+        meta = '/tmp/*',
       },
-    },
-    {
-      full_name='backupdir', abbreviation='bdir',
-      short_desc=N_("list of directories for the backup file"),
-      type='string', list='onecomma', scope={'global'},
-      deny_duplicates=true,
-      secure=true,
-      expand='nodefault',
-      varname='p_bdir',
-      defaults={if_true=''}
-    },
-    {
-      full_name='backupext', abbreviation='bex',
-      short_desc=N_("extension used for the backup file"),
-      type='string', scope={'global'},
-      normal_fname_chars=true,
-      varname='p_bex',
-      defaults={if_true="~"}
-    },
-    {
-      full_name='backupskip', abbreviation='bsk',
-      short_desc=N_("no backup for files that match these patterns"),
-      type='string', list='onecomma', scope={'global'},
-      deny_duplicates=true,
-      varname='p_bsk',
-      defaults={if_true=""}
-    },
-    {
-      full_name='belloff', abbreviation='bo',
-      short_desc=N_("do not ring the bell for these reasons"),
-      type='string', list='comma', scope={'global'},
-      deny_duplicates=true,
-      varname='p_bo',
-      defaults={if_true="all"}
-    },
-    {
-      full_name='binary', abbreviation='bin',
-      short_desc=N_("read/write/edit file in binary mode"),
-      type='bool', scope={'buffer'},
-      redraw={'statuslines'},
-      varname='p_bin',
-      defaults={if_true=false}
-    },
-    {
-      full_name='bomb',
-      short_desc=N_("a Byte Order Mark to the file"),
-      type='bool', scope={'buffer'},
-      no_mkrc=true,
-      redraw={'statuslines'},
-      varname='p_bomb',
-      defaults={if_true=false}
-    },
-    {
-      full_name='breakat', abbreviation='brk',
-      short_desc=N_("characters that may cause a line break"),
-      type='string', list='flags', scope={'global'},
-      redraw={'all_windows'},
-      varname='p_breakat',
-      defaults={if_true=" \t!@*-+;:,./?"}
-    },
-    {
-      full_name='breakindent', abbreviation='bri',
-      short_desc=N_("wrapped line repeats indent"),
-      type='bool', scope={'window'},
-      redraw={'current_window'},
-      defaults={if_true=false}
-    },
-    {
-      full_name='breakindentopt', abbreviation='briopt',
-      short_desc=N_("settings for 'breakindent'"),
-      type='string', list='onecomma', scope={'window'},
-      deny_duplicates=true,
-      alloced=true,
-      redraw={'current_buffer'},
-      defaults={if_true=""},
-    },
-    {
-      full_name='browsedir', abbreviation='bsdir',
-      short_desc=N_("which directory to start browsing in"),
-      type='string', scope={'global'},
-      enable_if=false,
-    },
-    {
-      full_name='bufhidden', abbreviation='bh',
-      short_desc=N_("what to do when buffer is no longer in window"),
-      type='string', scope={'buffer'},
-      noglob=true,
-      alloced=true,
-      varname='p_bh',
-      defaults={if_true=""}
-    },
-    {
-      full_name='buflisted', abbreviation='bl',
-      short_desc=N_("whether the buffer shows up in the buffer list"),
-      type='bool', scope={'buffer'},
-      noglob=true,
-      varname='p_bl',
-      defaults={if_true=1}
-    },
-    {
-      full_name='buftype', abbreviation='bt',
-      short_desc=N_("special type of buffer"),
-      type='string', scope={'buffer'},
-      noglob=true,
-      alloced=true,
-      varname='p_bt',
-      defaults={if_true=""}
-    },
-    {
-      full_name='casemap', abbreviation='cmp',
-      short_desc=N_("specifies how case of letters is changed"),
-      type='string', list='onecomma', scope={'global'},
-      deny_duplicates=true,
-      varname='p_cmp',
-      defaults={if_true="internal,keepascii"}
-    },
-    {
-      full_name='cdhome', abbreviation='cdh',
-      short_desc=N_(":cd without argument goes to the home directory"),
-      type='bool', scope={'global'},
-      secure=true,
-      varname='p_cdh',
-      defaults={if_true=false}
-    },
-    {
-      full_name='cdpath', abbreviation='cd',
-      short_desc=N_("list of directories searched with \":cd\""),
-      type='string', list='comma', scope={'global'},
-      deny_duplicates=true,
-      expand=true,
-      secure=true,
-      varname='p_cdpath',
-      defaults={if_true=",,"}
-    },
-    {
-      full_name='cedit',
-      short_desc=N_("used to open the command-line window"),
-      type='string', scope={'global'},
-      varname='p_cedit',
-      defaults={if_true=macros('CTRL_F_STR')}
-    },
-    {
-      full_name='channel',
-      short_desc=N_("Channel connected to the buffer"),
-      type='number', scope={'buffer'},
-      no_mkrc=true,
-      nodefault=true,
-      varname='p_channel',
-      defaults={if_true=0}
-    },
-    {
-      full_name='charconvert', abbreviation='ccv',
-      short_desc=N_("expression for character encoding conversion"),
-      type='string', scope={'global'},
-      secure=true,
-      varname='p_ccv',
-      defaults={if_true=""}
-    },
-    {
-      full_name='cindent', abbreviation='cin',
-      short_desc=N_("do C program indenting"),
-      type='bool', scope={'buffer'},
-      varname='p_cin',
-      defaults={if_true=false}
-    },
-    {
-      full_name='cinkeys', abbreviation='cink',
-      short_desc=N_("keys that trigger indent when 'cindent' is set"),
-      type='string', list='onecomma', scope={'buffer'},
-      deny_duplicates=true,
-      alloced=true,
-      varname='p_cink',
-      defaults={if_true=indentkeys_default}
-    },
-    {
-      full_name='cinoptions', abbreviation='cino',
-      short_desc=N_("how to do indenting when 'cindent' is set"),
-      type='string', list='onecomma', scope={'buffer'},
-      deny_duplicates=true,
-      alloced=true,
-      varname='p_cino',
-      defaults={if_true=""}
-    },
-    {
-      full_name='cinwords', abbreviation='cinw',
-      short_desc=N_("words where 'si' and 'cin' add an indent"),
-      type='string', list='onecomma', scope={'buffer'},
-      deny_duplicates=true,
-      alloced=true,
-      varname='p_cinw',
-      defaults={if_true="if,else,while,do,for,switch"}
-    },
-    {
-      full_name='cinscopedecls', abbreviation='cinsd',
-      short_desc=N_("words that are recognized by 'cino-g'"),
-      type='string', list='onecomma', scope={'buffer'},
-      deny_duplicates=true,
-      alloced=true,
-      varname='p_cinsd',
-      defaults={if_true="public,protected,private"}
-    },
-    {
-      full_name='clipboard', abbreviation='cb',
-      short_desc=N_("use the clipboard as the unnamed register"),
-      type='string', list='onecomma', scope={'global'},
-      deny_duplicates=true,
-      varname='p_cb',
-      defaults={if_true=""}
-    },
-    {
-      full_name='cmdheight', abbreviation='ch',
-      short_desc=N_("number of lines to use for the command-line"),
-      type='number', scope={'global'},
-      redraw={'all_windows'},
-      varname='p_ch',
-      defaults={if_true=1}
-    },
-    {
-      full_name='cmdwinheight', abbreviation='cwh',
-      short_desc=N_("height of the command-line window"),
-      type='number', scope={'global'},
-      varname='p_cwh',
-      defaults={if_true=7}
-    },
-    {
-      full_name='colorcolumn', abbreviation='cc',
-      short_desc=N_("columns to highlight"),
-      type='string', list='onecomma', scope={'window'},
-      deny_duplicates=true,
-      redraw=