runtime(doc): clarify tabstop settings and guidance
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>
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 86392dd..0f8d063 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -8493,46 +8493,14 @@
*'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)