runtime(doc): clarify the effect of 'smarttab'

closes: #17426

Signed-off-by: Damien Lejay <damien@lejay.be>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 9ec46825e4c1fa46bc0c1f7f08dd5a5f6f1a8807..155eb8f13a1d59428f5561455083b4d825469b5a 100644 (file)
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1,4 +1,4 @@
-*insert.txt*    For Vim version 9.1.  Last change: 2025 Jun 02
+*insert.txt*    For Vim version 9.1.  Last change: 2025 Jun 04
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -529,7 +529,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
@@ -540,13 +540,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'
@@ -561,6 +554,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
index 5c6fbfbef1a0f5cc2ac9efb2d411f8f044207679..4471b7c5251de52de14884c06b196297be784c60 100644 (file)
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1,4 +1,4 @@
-*options.txt*  For Vim version 9.1.  Last change: 2025 Jun 02
+*options.txt*  For Vim version 9.1.  Last change: 2025 Jun 04
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -7803,19 +7803,14 @@ A jump table for the options with a short description can be found at |Q_op|.
                                 *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'*
 'smarttab' 'sta'       boolean (default off)
                        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.
-       This option is reset when 'paste' is set and restored when 'paste' is
-       reset.
-       NOTE: This option is reset when 'compatible' is set.
+       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'.
+       This option is reset when 'compatible' is set; it is temporarily
+       disabled when 'paste' is enabled, and restored when 'paste' is turned
+       off.
+       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
index 349c1af8d06bdd8b9b57f94dcc776685d112cc33..de902ee2cb10fefacd0daccc66e9db6d061d194e 100644 (file)
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -1,4 +1,4 @@
-*quickref.txt*  For Vim version 9.1.  Last change: 2025 Apr 06
+*quickref.txt*  For Vim version 9.1.  Last change: 2025 Jun 04
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -918,7 +918,7 @@ Short explanation of each option:           *option-list*
 'signcolumn'     'scl'     when 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