commit 038fb30ece791f403c298632ca40b83f79687bf8
parent 5e4700152b79e090d880d2734e0eaec726f4b8a7
Author: zeertzjq <zeertzjq@outlook.com>
Date: Thu, 5 Jun 2025 06:28:16 +0800
vim-patch:d6c9ac9: runtime(doc): clarify the effect of 'smarttab'
closes: vim/vim#17426
https://github.com/vim/vim/commit/d6c9ac97a009f7099b7d3636548aa3a4fabb5f1a
Co-authored-by: Damien Lejay <damien@lejay.be>
Diffstat:
5 files changed, 24 insertions(+), 39 deletions(-)
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
@@ -510,7 +510,7 @@ paragraph, no matter where the cursor currently is. Or you can use Visual
mode: hit "v", move to the end of the block, and type "gq". See also |gq|.
==============================================================================
-4. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab*
+4. 'expandtab', 'softtabstop' and 'smarttab' options *ins-expandtab*
If the 'expandtab' option is on, spaces will be used to fill the amount of
whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first
@@ -521,13 +521,6 @@ number of characters in the line increases. Backspacing will delete one
space at a time. The original character will be put back for only one space
that you backspace over (the last one).
- *ins-smarttab*
-When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
-the beginning of a line and 'tabstop' positions in other places. This means
-that often spaces instead of a <Tab> character are inserted. When 'smarttab'
-is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
-used for ">>" and the like.
-
*ins-softtabstop*
When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
positions, and a <BS> used to delete white space, will delete 'softtabstop'
@@ -542,6 +535,13 @@ the cursor. Otherwise you cannot always delete a single character before the
cursor. You will have to delete 'softtabstop' characters first, and then type
extra spaces to get where you want to be.
+ *ins-smarttab*
+When the 'smarttab' option is on, the <Tab> key indents by 'shiftwidth' if the
+cursor is in leading whitespace. The <BS> key has the opposite effect. This
+behaves as if 'softtabstop' were set to the value of 'shiftwidth'. This option
+allows the user to set 'softtabstop' to a value other than 'shiftwidth' and
+still use the <Tab> key for indentation.
+
==============================================================================
5. Replace mode *Replace* *Replace-mode* *mode-replace*
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
@@ -5791,16 +5791,11 @@ A jump table for the options with a short description can be found at |Q_op|.
*'smarttab'* *'sta'* *'nosmarttab'* *'nosta'*
'smarttab' 'sta' boolean (default on)
global
- When on, a <Tab> in front of a line inserts blanks according to
- 'shiftwidth'. 'tabstop' or 'softtabstop' is used in other places. A
- <BS> will delete a 'shiftwidth' worth of space at the start of the
- line.
- When off, a <Tab> always inserts blanks according to 'tabstop' or
- 'softtabstop'. 'shiftwidth' is only used for shifting text left or
- right |shift-left-right|.
- What gets inserted (a <Tab> or spaces) depends on the 'expandtab'
- option. Also see |ins-expandtab|. When 'expandtab' is not set, the
- number of spaces is minimized by using <Tab>s.
+ When enabled, the <Tab> key will indent by 'shiftwidth' if the cursor
+ is in leading whitespace. The <BS> key has the opposite effect.
+ This behaves as if 'softtabstop' is set to the value of 'shiftwidth'.
+ Have a look at section |30.5| of the user guide for detailed
+ explanations on how Vim works with tabs and spaces.
*'smoothscroll'* *'sms'* *'nosmoothscroll'* *'nosms'*
'smoothscroll' 'sms' boolean (default off)
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
@@ -869,7 +869,7 @@ Short explanation of each option: *option-list*
'signcolumn' 'scl' when and how to display the sign column
'smartcase' 'scs' no ignore case when pattern has uppercase
'smartindent' 'si' smart autoindenting for C programs
-'smarttab' 'sta' use 'shiftwidth' when inserting <Tab>
+'smarttab' 'sta' <Tab> in leading whitespace indents by 'shiftwidth'
'smoothscroll' 'sms' scroll by screen lines when 'wrap' is set
'softtabstop' 'sts' number of spaces that <Tab> uses while editing
'spell' enable spell checking
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
@@ -6168,16 +6168,11 @@ vim.o.si = vim.o.smartindent
vim.bo.smartindent = vim.o.smartindent
vim.bo.si = vim.bo.smartindent
---- When on, a <Tab> in front of a line inserts blanks according to
---- 'shiftwidth'. 'tabstop' or 'softtabstop' is used in other places. A
---- <BS> will delete a 'shiftwidth' worth of space at the start of the
---- line.
---- When off, a <Tab> always inserts blanks according to 'tabstop' or
---- 'softtabstop'. 'shiftwidth' is only used for shifting text left or
---- right `shift-left-right`.
---- What gets inserted (a <Tab> or spaces) depends on the 'expandtab'
---- option. Also see `ins-expandtab`. When 'expandtab' is not set, the
---- number of spaces is minimized by using <Tab>s.
+--- When enabled, the <Tab> key will indent by 'shiftwidth' if the cursor
+--- is in leading whitespace. The <BS> key has the opposite effect.
+--- This behaves as if 'softtabstop' is set to the value of 'shiftwidth'.
+--- Have a look at section `30.5` of the user guide for detailed
+--- explanations on how Vim works with tabs and spaces.
---
--- @type boolean
vim.o.smarttab = true
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
@@ -8182,16 +8182,11 @@ local options = {
abbreviation = 'sta',
defaults = true,
desc = [=[
- When on, a <Tab> in front of a line inserts blanks according to
- 'shiftwidth'. 'tabstop' or 'softtabstop' is used in other places. A
- <BS> will delete a 'shiftwidth' worth of space at the start of the
- line.
- When off, a <Tab> always inserts blanks according to 'tabstop' or
- 'softtabstop'. 'shiftwidth' is only used for shifting text left or
- right |shift-left-right|.
- What gets inserted (a <Tab> or spaces) depends on the 'expandtab'
- option. Also see |ins-expandtab|. When 'expandtab' is not set, the
- number of spaces is minimized by using <Tab>s.
+ When enabled, the <Tab> key will indent by 'shiftwidth' if the cursor
+ is in leading whitespace. The <BS> key has the opposite effect.
+ This behaves as if 'softtabstop' is set to the value of 'shiftwidth'.
+ Have a look at section |30.5| of the user guide for detailed
+ explanations on how Vim works with tabs and spaces.
]=],
full_name = 'smarttab',
scope = { 'global' },
