runtime(doc): clarify the effect of 'smarttab'
Commit:
https://github.com/vim/vim/commit/d6c9ac97a009f7099b7d3636548aa3a4fabb5f1a
Author: Damien Lejay <dam...@lejay.be>
Date: Wed Jun 4 21:19:18 2025 +0200
runtime(doc): clarify the effect of 'smarttab'
closes: https://github.com/vim/vim/issues/17426
Signed-off-by: Damien Lejay <dam...@lejay.be>
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 9ec46825e..155eb8f13 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 @@ 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 5c6fbfbef..4471b7c52 100644
--- 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 349c1af8d..de902ee2c 100644
--- 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
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1uMtoJ-00031Q-Sw%40256bit.org.
