Document interaction between evaluate-commands and expansions

[Supreeeme]

This tripped me up a bit, so I thought it would be worth properly documenting the behavior.

[Screwtapello]

This is not really specific to evaluate-commands, the same thing applies to every command that takes a string to evaluate later, including define-command, hook, provide-module, etc. And you don't have to single-quote expansions to prevent them from being expanded - any kind of quoting or escaping will do, including balanced strings (%{ %val{client} }) or backslash-escaping (\%val{client}) (see :doc command-parsing for details).

The one thing that makes evaluate-commands unusual is that, as a convenience, it accepts multiple arguments and joins them with spaces, then evaluates them. Other commands that take a block of commands to evaluate only ever take a single argument, which makes it more difficult to wind up in this situation.

For example, you can say:

eval echo hello

...but you can't say:

define-command greet echo hello

(you get a "wrong argument count" error)

Instead you need to group the commands you want to execute into a single argument:

define-command greet %{ echo hello }

If you started with echo %val{client} and got the "wrong argument count" error, you might wrap the command in %{} and be shielded from the "early expansion" bug without even knowing there was a potential problem.

I do think it's worth having a reminder in execeval that even if you say -client foo or -buffer bar, that doesn't exempt eval (or exec) from the usual :doc command-parsing rules where unquoted expansions are expanded before the command is executed.