From 90b682891dd554f06805b9536ad7228b0319f23b Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 13 Jun 2025 08:53:48 +0800 Subject: [PATCH] vim-patch:91af4c4: runtime(doc): improve the wording of 'sts', 'varts' and 'varsts' values (#34480) closes: vim/vim#17522 https://github.com/vim/vim/commit/91af4c41809c4089d15857c1be13315b1969ea3b Co-authored-by: Damien Lejay Co-authored-by: Christian Brabandt --- runtime/doc/options.txt | 68 +++++++++++++++++------------- runtime/doc/quickref.txt | 6 +-- runtime/lua/vim/_meta/options.lua | 69 +++++++++++++++++-------------- src/nvim/options.lua | 68 +++++++++++++++++------------- 4 files changed, 120 insertions(+), 91 deletions(-) diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index e76e23e8a8..005931c9d6 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -5816,18 +5816,24 @@ A jump table for the options with a short description can be found at |Q_op|. *'softtabstop'* *'sts'* 'softtabstop' 'sts' number (default 0) local to buffer - Number of spaces that a counts for while performing editing - operations, like inserting a or using . It "feels" like - s are being inserted, while in fact a mix of spaces and s is - used. This is useful to keep the 'ts' setting at its standard value - of 8, while being able to edit like it is set to 'sts'. However, - commands like "x" still work on the actual characters. - When 'sts' is zero, this feature is off. - When 'sts' is negative, the value of 'shiftwidth' is used. - See also |ins-expandtab|. When 'expandtab' is not set, the number of - spaces is minimized by using s. - The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is - set. + Create soft tab stops, separated by 'softtabstop' number of columns. + In Insert mode, pressing the key will move the cursor to the + next soft tab stop, instead of inserting a literal tab. behaves + similarly in reverse. Vim inserts a minimal mix of tab and space + characters to produce the visual effect. + + This setting does not affect the display of existing tab characters. + + A value of 0 disables this behaviour. A negative value makes Vim use + 'shiftwidth'. If you plan to use 'sts' and 'shiftwidth' with + different values, you might consider setting 'smarttab'. + + 'softtabstop' is temporarily set to 0 when 'paste' is on and reset + when it is turned off. It is also reset when 'compatible' is set. + + The 'L' flag in 'cpoptions' alters tab behavior when 'list' is + enabled. See also |ins-expandtab| ans user manual section |30.5| for + in-depth explanations. The value of 'softtabstop' will be ignored if |'varsofttabstop'| is set to anything other than an empty string. @@ -6888,34 +6894,38 @@ A jump table for the options with a short description can be found at |Q_op|. *'varsofttabstop'* *'vsts'* 'varsofttabstop' 'vsts' string (default "") local to buffer - A list of the number of spaces that a counts for while editing, - such as inserting a or using . It "feels" like variable- - width s are being inserted, while in fact a mixture of spaces - and s is used. Tab widths are separated with commas, with the - final value applying to all subsequent tabs. + Defines variable-width soft tab stops. The value is a comma-separated + list of widths in columns. Each width defines the number of columns + before the next soft tab stop. The last value repeats indefinitely. For example, when editing assembly language files where statements start in the 9th column and comments in the 41st, it may be useful to use the following: >vim set varsofttabstop=8,32,8 -< This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more - for every column thereafter. +< This sets soft tab stops at column 8, then at column 40 (8 + 32), and + every 8 columns thereafter. - Note that the value of |'softtabstop'| will be ignored while - 'varsofttabstop' is set. + Note: this setting overrides 'softtabstop'. + See section |30.5| of the user manual for detailed explanations on how + Vim works with tabs and spaces. *'vartabstop'* *'vts'* 'vartabstop' 'vts' string (default "") local to buffer - A list of the number of spaces that a in the file counts for, - separated by commas. Each value corresponds to one tab, with the - final value applying to all subsequent tabs. For example: >vim - set vartabstop=4,20,10,8 -< This will make the first tab 4 spaces wide, the second 20 spaces, - the third 10 spaces, and all following tabs 8 spaces. + Defines variable-width tab stops. The value is a comma-separated list + of widths in columns. Each width defines the number of columns + before the next tab stop; the last value repeats indefinitely. - Note that the value of |'tabstop'| will be ignored while 'vartabstop' - is set. + For example: > + :set vartabstop=4,8 +< This places the first tab stop 4 columns from the start of the line + and each subsequent tab stop 8 columns apart. + + Note: this setting overrides 'tabstop'. + On UNIX, it is recommended to keep the default tabstop value of 8. + Consider setting 'varsofttabstop' instead. + See section |30.5| of the user manual for detailed explanations on how + Vim works with tabs and spaces. *'verbose'* *'vbs'* 'verbose' 'vbs' number (default 0) diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 8f93f845eb..ad7f7f74b8 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -871,7 +871,7 @@ Short explanation of each option: *option-list* 'smartindent' 'si' smart autoindenting for C programs 'smarttab' 'sta' in leading whitespace indents by 'shiftwidth' 'smoothscroll' 'sms' scroll by screen lines when 'wrap' is set -'softtabstop' 'sts' number of spaces that uses while editing +'softtabstop' 'sts' number of columns between two soft tab stops 'spell' enable spell checking 'spellcapcheck' 'spc' pattern to locate end of a sentence 'spellfile' 'spf' files where |zg| and |zw| store words @@ -923,8 +923,8 @@ Short explanation of each option: *option-list* 'undoreload' 'ur' max nr of lines to save for undo on a buffer reload 'updatecount' 'uc' after this many characters flush swap file 'updatetime' 'ut' after this many milliseconds flush swap file -'varsofttabstop' 'vsts' a list of number of spaces when typing -'vartabstop' 'vts' a list of number of spaces for s +'varsofttabstop' 'vsts' a list of number of columns between soft tab stops +'vartabstop' 'vts' a list of number of columns between tab stops 'verbose' 'vbs' give informative messages 'verbosefile' 'vfile' file to write messages in 'viewdir' 'vdir' directory where to store files with :mkview diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 62ecba8353..33489f44d2 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6199,18 +6199,24 @@ vim.o.sms = vim.o.smoothscroll vim.wo.smoothscroll = vim.o.smoothscroll vim.wo.sms = vim.wo.smoothscroll ---- Number of spaces that a counts for while performing editing ---- operations, like inserting a or using . It "feels" like ---- s are being inserted, while in fact a mix of spaces and s is ---- used. This is useful to keep the 'ts' setting at its standard value ---- of 8, while being able to edit like it is set to 'sts'. However, ---- commands like "x" still work on the actual characters. ---- When 'sts' is zero, this feature is off. ---- When 'sts' is negative, the value of 'shiftwidth' is used. ---- See also `ins-expandtab`. When 'expandtab' is not set, the number of ---- spaces is minimized by using s. ---- The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is ---- set. +--- Create soft tab stops, separated by 'softtabstop' number of columns. +--- In Insert mode, pressing the key will move the cursor to the +--- next soft tab stop, instead of inserting a literal tab. behaves +--- similarly in reverse. Vim inserts a minimal mix of tab and space +--- characters to produce the visual effect. +--- +--- This setting does not affect the display of existing tab characters. +--- +--- A value of 0 disables this behaviour. A negative value makes Vim use +--- 'shiftwidth'. If you plan to use 'sts' and 'shiftwidth' with +--- different values, you might consider setting 'smarttab'. +--- +--- 'softtabstop' is temporarily set to 0 when 'paste' is on and reset +--- when it is turned off. It is also reset when 'compatible' is set. +--- +--- The 'L' flag in 'cpoptions' alters tab behavior when 'list' is +--- enabled. See also `ins-expandtab` ans user manual section `30.5` for +--- in-depth explanations. --- --- The value of 'softtabstop' will be ignored if `'varsofttabstop'` is set --- to anything other than an empty string. @@ -7491,11 +7497,9 @@ vim.o.ut = vim.o.updatetime vim.go.updatetime = vim.o.updatetime vim.go.ut = vim.go.updatetime ---- A list of the number of spaces that a counts for while editing, ---- such as inserting a or using . It "feels" like variable- ---- width s are being inserted, while in fact a mixture of spaces ---- and s is used. Tab widths are separated with commas, with the ---- final value applying to all subsequent tabs. +--- Defines variable-width soft tab stops. The value is a comma-separated +--- list of widths in columns. Each width defines the number of columns +--- before the next soft tab stop. The last value repeats indefinitely. --- --- For example, when editing assembly language files where statements --- start in the 9th column and comments in the 41st, it may be useful @@ -7504,11 +7508,12 @@ vim.go.ut = vim.go.updatetime --- ```vim --- set varsofttabstop=8,32,8 --- ``` ---- This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more ---- for every column thereafter. +--- This sets soft tab stops at column 8, then at column 40 (8 + 32), and +--- every 8 columns thereafter. --- ---- Note that the value of `'softtabstop'` will be ignored while ---- 'varsofttabstop' is set. +--- Note: this setting overrides 'softtabstop'. +--- See section `30.5` of the user manual for detailed explanations on how +--- Vim works with tabs and spaces. --- --- @type string vim.o.varsofttabstop = "" @@ -7516,18 +7521,22 @@ vim.o.vsts = vim.o.varsofttabstop vim.bo.varsofttabstop = vim.o.varsofttabstop vim.bo.vsts = vim.bo.varsofttabstop ---- A list of the number of spaces that a in the file counts for, ---- separated by commas. Each value corresponds to one tab, with the ---- final value applying to all subsequent tabs. For example: +--- Defines variable-width tab stops. The value is a comma-separated list +--- of widths in columns. Each width defines the number of columns +--- before the next tab stop; the last value repeats indefinitely. --- ---- ```vim ---- set vartabstop=4,20,10,8 +--- For example: --- ``` ---- This will make the first tab 4 spaces wide, the second 20 spaces, ---- the third 10 spaces, and all following tabs 8 spaces. +--- :set vartabstop=4,8 +--- ``` +--- This places the first tab stop 4 columns from the start of the line +--- and each subsequent tab stop 8 columns apart. --- ---- Note that the value of `'tabstop'` will be ignored while 'vartabstop' ---- is set. +--- Note: this setting overrides 'tabstop'. +--- On UNIX, it is recommended to keep the default tabstop value of 8. +--- Consider setting 'varsofttabstop' instead. +--- See section `30.5` of the user manual for detailed explanations on how +--- Vim works with tabs and spaces. --- --- @type string vim.o.vartabstop = "" diff --git a/src/nvim/options.lua b/src/nvim/options.lua index f5a3eb493b..105b82c6c9 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -8222,18 +8222,24 @@ local options = { abbreviation = 'sts', defaults = 0, desc = [=[ - Number of spaces that a counts for while performing editing - operations, like inserting a or using . It "feels" like - s are being inserted, while in fact a mix of spaces and s is - used. This is useful to keep the 'ts' setting at its standard value - of 8, while being able to edit like it is set to 'sts'. However, - commands like "x" still work on the actual characters. - When 'sts' is zero, this feature is off. - When 'sts' is negative, the value of 'shiftwidth' is used. - See also |ins-expandtab|. When 'expandtab' is not set, the number of - spaces is minimized by using s. - The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is - set. + Create soft tab stops, separated by 'softtabstop' number of columns. + In Insert mode, pressing the key will move the cursor to the + next soft tab stop, instead of inserting a literal tab. behaves + similarly in reverse. Vim inserts a minimal mix of tab and space + characters to produce the visual effect. + + This setting does not affect the display of existing tab characters. + + A value of 0 disables this behaviour. A negative value makes Vim use + 'shiftwidth'. If you plan to use 'sts' and 'shiftwidth' with + different values, you might consider setting 'smarttab'. + + 'softtabstop' is temporarily set to 0 when 'paste' is on and reset + when it is turned off. It is also reset when 'compatible' is set. + + The 'L' flag in 'cpoptions' alters tab behavior when 'list' is + enabled. See also |ins-expandtab| ans user manual section |30.5| for + in-depth explanations. The value of 'softtabstop' will be ignored if |'varsofttabstop'| is set to anything other than an empty string. @@ -9787,21 +9793,20 @@ local options = { cb = 'did_set_varsofttabstop', defaults = '', desc = [=[ - A list of the number of spaces that a counts for while editing, - such as inserting a or using . It "feels" like variable- - width s are being inserted, while in fact a mixture of spaces - and s is used. Tab widths are separated with commas, with the - final value applying to all subsequent tabs. + Defines variable-width soft tab stops. The value is a comma-separated + list of widths in columns. Each width defines the number of columns + before the next soft tab stop. The last value repeats indefinitely. For example, when editing assembly language files where statements start in the 9th column and comments in the 41st, it may be useful to use the following: >vim set varsofttabstop=8,32,8 - < This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more - for every column thereafter. + < This sets soft tab stops at column 8, then at column 40 (8 + 32), and + every 8 columns thereafter. - Note that the value of |'softtabstop'| will be ignored while - 'varsofttabstop' is set. + Note: this setting overrides 'softtabstop'. + See section |30.5| of the user manual for detailed explanations on how + Vim works with tabs and spaces. ]=], full_name = 'varsofttabstop', list = 'comma', @@ -9815,15 +9820,20 @@ local options = { cb = 'did_set_vartabstop', defaults = '', desc = [=[ - A list of the number of spaces that a in the file counts for, - separated by commas. Each value corresponds to one tab, with the - final value applying to all subsequent tabs. For example: >vim - set vartabstop=4,20,10,8 - < This will make the first tab 4 spaces wide, the second 20 spaces, - the third 10 spaces, and all following tabs 8 spaces. + Defines variable-width tab stops. The value is a comma-separated list + of widths in columns. Each width defines the number of columns + before the next tab stop; the last value repeats indefinitely. - Note that the value of |'tabstop'| will be ignored while 'vartabstop' - is set. + For example: > + :set vartabstop=4,8 + < This places the first tab stop 4 columns from the start of the line + and each subsequent tab stop 8 columns apart. + + Note: this setting overrides 'tabstop'. + On UNIX, it is recommended to keep the default tabstop value of 8. + Consider setting 'varsofttabstop' instead. + See section |30.5| of the user manual for detailed explanations on how + Vim works with tabs and spaces. ]=], full_name = 'vartabstop', list = 'comma',