Kakoune: Be more clear on how to use "kak -p"

[sucrecacao]

Feature

man kak give the following:

 -p session_id
              send  the  commands  written  on the standard input to
              session session_id

With this information, I try the following
echo 'ihello' | kak -p myses
and also
echo "execute-keys 'ihello' " | kak -p myses

Because the doc doesn't talk about the -client $client_id than I'm suppose to add in the command.

I had to dig the forum to find a nice example on how properly use kak -p ( here

We could use something like:

  -p session_id
              send  the  commands  written  on the standard input to
              session session_id. You need to add the `-client` with the client Id option the given command, see example

Plus a clear example

echo "execute-keys -client $kakoune_client_id 'x'" | kak -p $kakoune_session_id
```

[Screwtapello]

You don't need to give the client ID on the command-line unless you're trying to affect a particular client. You can do things like:

echo "set-option global tabstop 5" | kak -p $kak_session
echo "edit /path/to/file" | kak -p $kak_session
echo "source /path/to/plugin.kak" | kak -p $kak_session

...or basically anything that you could put in your kakrc file.

A command like execute-keys ihello will only work in a client, since it involves client-specific functionality such as "insert mode", and because it's possible for two clients to be viewing the same file but in different modes. If you want to put a particular client into insert mode, you need to use -client. If you want to affect a buffer without affecting a particular client, you need to use -buffer. That's all specific to execute-keys (and evaluate-commands), not really anything to do with kak -p though.

It would probably be helpful for the kak -p docs to mention that the given commands are executed at global scope, though. That's the wording used in things like :doc expansions and :doc hooks to describe what information is available to executing code, and hopefully is enough of a clue that things like execute-keys won't do anything useful on their own.

[sucrecacao]

That's all make much sense, but how a new user is suppose to know that ?

It would probably be helpful for the kak -p docs to mention that the given commands are executed at global scope, though.

definitely, a link to more detailed doc on how to use the -buffer and -client option would be helpful .

Or maybe an error message when doing echo execute-keys 'x' | kak -p $session ? Like Cannot run 'execute-keys' from stdin without '-buffer' or '-client' option, see ':doc ...' for more information

hopefully is enough of a clue that things like execute-keys won't do anything useful on their own.

I don't believe so. Maybe it would for people that have experience with kakoune but I don't think it would help new user. Generally speaking, I feel like kakoune doc is a cheat sheet for experience user, as a new user it is hard to find the info I'm looking for.

@Screwtapello do you mind if I put some of you comment in the wiki ?

[sucrecacao]

https://github.com/mawww/kakoune/wiki/kak-%E2%80%90p

[Screwtapello]

a link to more detailed doc on how to use the -buffer and -client option would be helpful .

:doc execeval is the best we have currently. Possibly that information should be moved somewhere more prominent, or at least linked to, but I'm not sure what the best place would be.

Or maybe an error message...

That's https://github.com/mawww/kakoune/issues/2292

I feel like kakoune doc is a cheat sheet for experience user...

That's fair. In the grand unified theory of documentation Kakoune has a lot of Reference documentation, but not much in the way of Explanation. At some point somebody needs to sit down and write a list of all the concepts involved in Kakoune (modes, scopes, highlighters, sessions, clients, etc.), make a diagram of how they are related, and figure out how to put that into words. That's a lot of work, though.

do you mind if I put some of you comment in the wiki

Go right ahead!