vim-patch:a4a3f71: runtime(doc): clarify tabstop settings and guidance

closes: vim/vim#17381

https://github.com/vim/vim/commit/a4a3f712e250299bb788a1de9c7557ba0de92f06

Co-authored-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>

1 files changed, 6 insertions, 39 deletions

diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index d0e5992bef..f9c6ec1171 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -9055,45 +9055,12 @@ local options = {
       cb = 'did_set_shiftwidth_tabstop',
       defaults = 8,
       desc = [=[
-        Number of spaces that a <Tab> in the file counts for.  Also see
-        the |:retab| command, and the 'softtabstop' option.
-
-        Note: Setting 'tabstop' to any other value than 8 can make your file
-        appear wrong in many places.
-        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.
-
-        The value of 'tabstop' will be ignored if |'vartabstop'| is set to
-        anything other than an empty string.
+        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 |'vartabstop'| is set, this option is ignored.
+        Leave it at 8 unless you have a strong reason (see usr |30.5|).
       ]=],
       full_name = 'tabstop',
       redraw = { 'current_buffer' },