:help :filter can be improved

[lacygoill]

From :help :filter:

|:set|        - filter by variable name

:set does not accept the name of a variable, but the name of an option, so :filter cannot filter by variable name, but by option name. Patch fixing the issue:

diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 3f750cd87..09f8534ef 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -598,7 +598,7 @@ N  *+X11*		Unix only: can restore window title |X11|
 			   |:oldfiles|   - filter by file name
 			   |:registers|  - filter by register contents
 					   (does not work multi-line)
-			   |:set|        - filter by variable name
+			   |:set|        - filter by option name
 
 			Only normal messages are filtered, error messages are
 			not.

---

And what about :set! termcap? Is :filter supposed to filter its output? I guess it should, because it can already filter :set! all:

:filter /func/ set! all

--- Options ---
  completefunc=
  imactivatefunc=
  imstatusfunc=
  maxfuncdepth=100
  omnifunc=
  operatorfunc=
  quickfixtextfunc=
  tagfunc=
  thesaurusfunc=

But :set! termcap is filtered in a weird way:

:set term=xterm
:filter /t_AB/ set! termcap

--- Terminal codes ---
  t_AB=^[[4%p1%dm
--- Terminal keys ---
t_#2 <S-Home>    ^[[1;2H
t_#4 <S-Left>    ^[[1;2D
t_%1 <Help>      ^[[28;*~
...

Notice that the first section ("Terminal codes") has been correctly filtered to only keep the line matching the 't_AB' option. But the second section ("Terminal keys") has not been filtered. This seems inconsistent.

Also, :filter cannot filter the keys by their Vim keysym names, which the user might be tempted to run to read how pseudo-keys like <FocusGained> or <FocusLost> are set:

:filter /Focus/ set! termcap

Notice that all the lines in the first "Terminal codes" are correctly filtered out, but no line is removed from the second "Terminal keys" section.

If this is working as intended, maybe it should be documented. As a suggestion, here is a patch:

diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 3f750cd87..db4f51494 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -599,6 +599,8 @@ N  *+X11*		Unix only: can restore window title |X11|
 			   |:registers|  - filter by register contents
 					   (does not work multi-line)
 			   |:set|        - filter by variable name
+					   (for `:set! termcap`, only the codes
+					   are filtered; not the keys)
 
 			Only normal messages are filtered, error messages are
 			not.

[lacygoill]

Notice that all the lines in the first "Terminal codes" are correctly filtered out, but no line is removed from the second "Terminal keys" section.

It would help if it worked and :filter could filter the lines.

Suppose that a user has an issue with their arrow keys not working. It's simpler to tell them to run this:

:filter /\cup\|down\|right\|left/ set! termcap

Than to just run :set! termcap and look for various keys inside the long output.