runtime(doc): update documentation on tabstop settings
Commit:
https://github.com/vim/vim/commit/bfa16364f104f336fc7407ee4533ae9045f040c4
Author: Damien Lejay <dam...@lejay.be>
Date: Tue Jun 10 21:12:31 2025 +0200
runtime(doc): update documentation on tabstop settings
Unify the treatment of tabstop, correct errors and deprecate smarttab
usage.
closes: #17444
Signed-off-by: Damien Lejay <dam...@lejay.be>
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 70fe4ca60..b50468863 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 07
+*options.txt* For Vim version 9.1. Last change: 2025 Jun 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -7803,11 +7803,13 @@ A jump table for the options with a short description
can be found at |Q_op|.
global
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'.
+ In leading whitespace, this has the same effect as setting
+ 'softtabstop' 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
+ NOTE: in most cases, using 'softtabstop' is a better option. 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'*
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index de902ee2c..6af25683f 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 Jun 04
+*quickref.txt* For Vim version 9.1. Last change: 2025 Jun 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -942,7 +942,7 @@ Short explanation of each option: *option-list*
'tabclose' 'tcl' which tab page to focus when closing a tab
'tabline' 'tal' custom format for the console tab pages line
'tabpagemax' 'tpm' maximum number of tab pages for |-p| and "tab all"
-'tabstop' 'ts' number of spaces that <Tab> in file uses
+'tabstop' 'ts' number of columns between two tab stops
'tagbsearch' 'tbs' use binary searching in tags files
'tagcase' 'tc' how to handle case when searching in tags files
'tagfunc' 'tfu' function to get list of tag matches
diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt
index 54fd6bc51..ed92c9535 100644
--- a/runtime/doc/usr_25.txt
+++ b/runtime/doc/usr_25.txt
@@ -1,4 +1,4 @@
-*usr_25.txt* For Vim version 9.1. Last change: 2025 Feb 01
+*usr_25.txt* For Vim version 9.1. Last change: 2025 Jun 10
VIM USER MANUAL - by Bram Moolenaar
@@ -215,27 +215,28 @@ An alternative is to filter the text through an external
program. Example: >
*25.3* Indents and tabs
Indents can be used to make text stand out from the rest. The example texts
-in this manual, for example, are indented by eight spaces or a tab. You would
-normally enter this by typing a tab at the start of each line. Take this
+in this manual, for example, are indented by eight columns. You would
+normally enter this by typing <Tab> at the start of each line. Take this
text:
the first line ~
the second line ~
-This is entered by typing a tab, some text, <Enter>, tab and more text.
+This is entered by typing <Tab>, some text, <Enter>, <Tab> and more text.
The 'autoindent' option inserts indents automatically: >
:set autoindent
When a new line is started it gets the same indent as the previous line. In
-the above example, the tab after the <Enter> is not needed anymore.
+the above example, pressing the <Tab> key after <Enter> is not needed anymore.
INCREASING INDENT
-To increase the amount of indent in a line, use the ">" operator. Often this
-is used as ">>", which adds indent to the current line.
+To increase the amount of indent in a line, use the ">" operator, in Normal
+mode. Often this is used as ">>", which adds indent to the current line.
+In Insert mode, use <C-t>.
The amount of indent added is specified with the 'shiftwidth' option. The
-default value is 8. To make ">>" insert four spaces worth of indent, for
+default value is 8. To make ">>" insert four columns worth of indent, for
example, type this: >
:set shiftwidth=4
@@ -248,46 +249,27 @@ When used on the second line of the example text, this is
what you get:
"4>>" will increase the indent of four lines.
-TABSTOP
+SOFT TAB STOPS
If you want to make indents a multiple of 4, you set 'shiftwidth' to 4. But
-when pressing a <Tab> you still get 8 spaces worth of indent. To change this,
-set the 'softtabstop' option: >
+when pressing a <Tab> you still get 8 columns worth of indent. To change
+this, set the 'softtabstop' option: >
:set softtabstop=4
-This will make the <Tab> key insert 4 spaces worth of indent. If there are
-already four spaces, a <Tab> character is used (saving seven characters in the
-file). (If you always want spaces and no tab characters, set the 'expandtab'
-option.)
+Vim now creates invisible tab stops for your cursor every 4 columns; hitting
+<Tab> jumps to the next stop and inserts the exact mix of spaces or tabs
+needed.
Note:
You could set the 'tabstop' option to 4. However, if you edit the
file another time, with 'tabstop' set to the default value of 8, it
will look wrong. In other programs and when printing the indent will
also be wrong. Therefore it is recommended to keep 'tabstop' at eight
- all the time. That's the standard value everywhere.
+ all the time. That's the standard value everywhere on UNIX-like
+ systems.
-CHANGING TABS
-
-You edit a file which was written with a tabstop of 3. In Vim it looks ugly,
-because it uses the normal tabstop value of 8. You can fix this by setting
-'tabstop' to 3. But you have to do this every time you edit this file.
- Vim can change the use of tabstops in your file. First, set 'tabstop' to
-make the indents look good, then use the ":retab" command: >
-
- :set tabstop=3
- :retab 8
-
-The ":retab" command will change 'tabstop' to 8, while changing the text such
-that it looks the same. It changes spans of white space into tabs and spaces
-for this. You can now write the file. Next time you edit it the indents will
-be right without setting an option.
- Warning: When using ":retab" on a program, it may change white space inside
-a string constant. Therefore it's a good habit to use " " instead of a
-real tab.
-
==============================================================================
*25.4* Dealing with long lines
@@ -576,6 +558,32 @@ The "gR" command uses Virtual Replace mode. This
preserves the layout:
inp 0.786 0.534 0.693 ~
+
+REFORMATTING TABS IN TABLES
+
+You edit a file that contains tabular data and the original author of the file
+decided to align the tabular data using tab characters (instead of spaces).
+Alas, they were using tab stops separated by 4 columns and Vim's default
+is 8 columns; the table looks wrong! What can be done?
+ To fix the appearance without modifying the file, adjust the setting
+temporarily: >
+
+ :set tabstop=4
+
+This updates the visual layout, but the file itself remains unchanged.
+ Another possibility is to permanently reformat the file. For this Vim
+provides the |:retab| command. First, set 'tabstop' to match original layout
+(as above), then run: >
+
+ :retab 8
+
+The ":retab" command will change 'tabstop' to 8, while changing the text such
+that it looks the same. It changes spans of white space into tabs and spaces
+for this. You can now write the file.
+ Warning: When using ":retab" on a program, it may change white space inside
+a string constant. Therefore it's a good habit to use " " instead of a
+real tab.
+
==============================================================================
Next chapter: |usr_26.txt| Repeating
diff --git a/runtime/doc/usr_30.txt b/runtime/doc/usr_30.txt
index 86fe649bd..59ef37a99 100644
--- a/runtime/doc/usr_30.txt
+++ b/runtime/doc/usr_30.txt
@@ -1,4 +1,4 @@
-*usr_30.txt* For Vim version 9.1. Last change: 2025 May 30
+*usr_30.txt* For Vim version 9.1. Last change: 2025 Jun 10
VIM USER MANUAL - by Bram Moolenaar
@@ -547,8 +547,8 @@ tab stops.
If you prefer to have different values for 'shiftwidth' and 'softtabstop',
you can still do so and use <C-t> to indent with 'shiftwidth'. Or you can
-use the 'smarttab' option introduced in Vim 5.6, allowing for a unified
-<Tab> key that knows what to do in the different situations.
+use the 'smarttab' option, allowing for a unified <Tab> key that knows what to
+do in the different situations.
VARIABLE TAB STOPS
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index f6c0ae9ae..d6fb6418f 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -1,4 +1,4 @@
-*various.txt* For Vim version 9.1. Last change: 2025 Jun 07
+*various.txt* For Vim version 9.1. Last change: 2025 Jun 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -514,7 +514,7 @@ T *+title* Setting the window 'title' and 'icon';
Always enabled
N *+toolbar* |gui-toolbar|
T *+user_commands* User-defined commands. |user-commands|
Always enabled since 8.1.1210.
-H *+vartabs* Variable-width tabstops. |'vartabstop'|
+H *+vartabs* Variable-width tab stops. |'vartabstop'|
T *+vertsplit* Vertically split windows |:vsplit|; Always
enabled
since 8.0.1118.
T *+vim9script* |Vim9| script
diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt
index b35fe77c7..f694df838 100644
--- a/runtime/doc/vi_diff.txt
+++ b/runtime/doc/vi_diff.txt
@@ -1,4 +1,4 @@
-*vi_diff.txt* For Vim version 9.1. Last change: 2025 Jun 02
+*vi_diff.txt* For Vim version 9.1. Last change: 2025 Jun 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -1102,7 +1102,7 @@ The following options are supported by Vi: ~
'shiftwidth' 'sw' number of spaces to use for (auto)indent step
'showmatch' 'sm' briefly jump to matching bracket if insert one
'showmode' 'smd' message on status line to show current mode
-'tabstop' 'ts' number of spaces that <Tab> in file uses
+'tabstop' 'ts' number of columns between two tab stops
'taglength' 'tl' number of significant characters for a tag
'tags' 'tag' list of file names used by the tag command
{Vi: default is "tags /usr/lib/tags"}
--
--
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/E1uP4R8-00BsXR-Cz%40256bit.org.
