adam/vim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

runtime(doc): clarify tabstop settings and guidance

Browse Source 
closes: #17381

Signed-off-by: Damien Lejay <damien@lejay.be>
Co-authored-by: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
Co-authored-by: Christian Brabandt <cb@256bit.org>
This commit is contained in:
Damien Lejay
2025-05-30 17:36:37 +02:00
committed by Christian Brabandt
parent 570e71a277
commit a4a3f712e2
2 changed files with 175 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
runtime/doc/options.txt
View File

@ -8493,46 +8493,14 @@ A jump table for the options with a short description can be found at |Q_op|.
*'tabstop'* *'ts'*
'tabstop' 'ts' number (default 8)
local to buffer
Number of spaces that a <Tab> in the file counts for. Also see
the |:retab| command, and the 'softtabstop' option.
Defines the column multiple used to display the Horizontal Tab
character (ASCII 9); a Horizontal Tab always advances to the next
tab stop.
The value must be at least 1 and at most 9999.
If Vim was compiled with |+vartabs| and |'vartabstop'| is set, this option
is ignored.
Leave it at 8 unless you have a strong reason (see usr |30.5|).
Note: Setting 'tabstop' to any other value than 8 can make your file
appear wrong in many places, e.g., when printing it.
The value must be more than 0 and less than 10000.
There are five main ways to use tabs in Vim:
1. Always keep 'tabstop' at 8, set 'softtabstop' and 'shiftwidth' to 4
(or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim
will use a mix of tabs and spaces, but typing <Tab> and <BS> will
behave like a tab appears every 4 (or 3) characters.
This is the recommended way, the file will look the same with other
tools and when listing it in a terminal.
2. Set 'softtabstop' and 'shiftwidth' to whatever you prefer and use
'expandtab'. This way you will always insert spaces. The
formatting will never be messed up when 'tabstop' is changed (leave
it at 8 just in case). The file will be a bit larger.
You do need to check if no Tabs exist in the file. You can get rid
of them by first setting 'expandtab' and using `%retab!`, making
sure the value of 'tabstop' is set correctly.
3. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use
'expandtab'. This way you will always insert spaces. The
formatting will never be messed up when 'tabstop' is changed.
You do need to check if no Tabs exist in the file, just like in the
item just above.
4. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use a
|modeline| to set these values when editing the file again. Only
works when using Vim to edit the file, other tools assume a tabstop
is worth 8 spaces.
5. Always set 'tabstop' and 'shiftwidth' to the same value, and
'noexpandtab'. This should then work (for initial indents only)
for any tabstop setting that people use. It might be nice to have
tabs after the first non-blank inserted as spaces if you do this
though. Otherwise aligned comments will be wrong when 'tabstop' is
changed.
If Vim is compiled with the |+vartabs| feature then the value of
'tabstop' will be ignored if |'vartabstop'| is set to anything other
than an empty string.
*'tagbsearch'* *'tbs'* *'notagbsearch'* *'notbs'*
'tagbsearch' 'tbs' boolean (default on)