[vim/vim] Misleading documentation for 'switchbuf' (#8215)

[Danilo Rezende]

This is the current documentation section for the 'switchbuf' option:

						*'switchbuf'* *'swb'*
'switchbuf' 'swb'	string	(default "")
			global
	This option controls the behavior when switching between buffers.
	Possible values (comma separated list):
	   useopen	If included, jump to the first open window that
			contains the specified buffer (if there is one).
			Otherwise: Do not examine other windows.
			This setting is checked with |quickfix| commands, when
			jumping to errors (":cc", ":cn", "cp", etc.).  It is
			also used in all buffer related split commands, for
			example ":sbuffer", ":sbnext", or ":sbrewind".
	   usetab	Like "useopen", but also consider windows in other tab
			pages.
	   split	If included, split the current window before loading
			a buffer for a |quickfix| command that display errors.
			Otherwise: do not split, use current window (when used
			in the quickfix window: the previously used window or
			split if there is no other window).
	   vsplit	Just like "split" but split vertically.
	   newtab	Like "split", but open a new tab page.  Overrules
			"split" when both are present.
	   uselast	If included, jump to the previously used window when
			jumping to errors with |quickfix| commands.

The problems

1. It is not clear what commands honor the switchbuf option: Is it only quickfix and buffer-related split commands? Or will :buffer-like commands respect it too? In my experience, :buffer does not. (relevant vi stack exchange answer)

2. The explanation of what commands will or will not respect the switchbuf option should not be hiding under the description of the possible values of the switchbuf option: The user that won't read it may be mislead into thinking that some commands would respect the option, while they don't.

3. It is not clear what "switching buffers" means: For example, one could think :b foo could switch a buffer, but :b doesn't(in my experience) respect the switchbuf option.

4. Typo: I think buffer related should be buffer-related instead.

Have a nice day, you guys! :)

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or unsubscribe.

[Bram Moolenaar]

It is mentioned what commands use which values. You do need to read through the text to see that. I can add a remark near the top about that.
Since not all values apply to the same commands, those commands must be mentioned at the value.
The ":buffer" command is not mentioned, thus 'switchbuf' is not used for that.
You need to read it carefully, the information is all there.

[Bram Moolenaar]

Closed #8215.