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 9ec4682..155eb8f 100644
--- 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 @@
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 @@
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 @@
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*