diff --git a/doc/pages/execeval.asciidoc b/doc/pages/execeval.asciidoc index f7b8db1e..49a42df4 100644 --- a/doc/pages/execeval.asciidoc +++ b/doc/pages/execeval.asciidoc @@ -1,70 +1,66 @@ = Execute-keys and Evaluate-commands -== Description +*execute-keys* [] ...:: + Run keys as if they were pressed. -The *execute-keys* and *evaluate-commands* commands can be used to run -Kakoune commands: +*evaluate-commands* [] ...:: + Evaluate specified commands as if they were entered into the command + prompt. ----------------------------- -execute-keys [] ... -evaluate-commands [] ... ----------------------------- +By default, the execution of both commands happens within the context of +the current client, and stops when the last key/command is reached or an +error occurs. -*execute-keys* runs keys as if they were pressed, whereas *evaluate-commands* -evaluates its given parameters as if they were entered in the command prompt. -By default, their execution happens within the context of the current client, -and stops when the last key/command is reached, or an error is raised. - -*execute-keys* also save the following registers, who are then restored -when the commands have been executed: */*, *"*, *|*, *^*, *@*. -*evaluate-commands* does not save any registers by default. +Regarding registers, *execute-keys* saves the following registers, which +are then restored when the keys have been executed: */*, *"*, *|*, *^*, +*@*. *evaluate-commands* doesn't save any registers by default. (See <>) -== Optional switches +== Switches for both commands *-client* :: - execute in the context of the client named *name* + Execute in the context of the client *name*. *-try-client* :: - execute in the context of the client named *name* if such client - exists, or else in the current context + Execute in the context of the client *name* if such client exists, + or else in the current context. *-draft*:: - execute in a copy of the context of the selected client. Modifications - to the selections or input state will not affect the client. This - permits to make some modification to the buffer without modifying - the user’s selection + Execute in a copy of the context of the selected client. Modifications to + the selections or input state will not affect the client. This permits + making modifications to the buffer without modifying the user’s + selection. *-itersel*:: - execute once per selection, in a context with only the considered - selection. This permits avoiding cases where the selections may - get merged + Execute once per selection, each having its own context. This prevents + situations where selections get merged. *-buffer* :: - execute in the context of each buffers in the comma separated list - *names*. `*` as a name can be used to iterate on all non-debug buffers + Execute in the context of each buffer specified in the comma separated + list *names*. `*` can be used as a *name* to iterate over all non-debug + buffers. (See <>) *-save-regs* :: - regs is a string of registers to be restored after execution (overwrites - the list of registers saved by default, c.f. description) + *regs* is a string of registers to be restored after execution (overwrites + the list of registers saved by default). -== evaluate-commands specific switches +== Switches specific to *evaluate-commands* *-no-hooks*:: - disable hook execution while executing the keys/commands + Disable hook execution while executing the keys/commands. (See <>) *-verbatim*:: - do not reparse and split positional arguments. Forward them - exactly as given to the `evaluate-commands` command. + Don't reparse and split positional arguments. Forward them exactly + as specified. -== execute-keys specific switches +== Switches specific to *execute-keys* *-with-maps*:: - use user key mapping in instead of built in keys + Use a custom key mapping instead of the built-in one. (See <>) *-with-hooks*:: - the execution of keys will trigger existing hooks + Execute keys and trigger existing hooks. (See <>)