utils/actions: Add user-friendly docs to `Action` variants

[har7an]

that explain what every action does, what it serializes to in the config.yaml and whether it is meant for direct user-interaction in the first place.

Related to: #1562

[har7an]

Some actions still lack documentation because I didn't know what they do... They have a ??? in the code now, I'd be happy to change that if someone explains to me what they do.

[a-kenji]

What do you mean by direct user interaction?

[har7an]

What do you mean by direct user interaction?

Users mostly interact with zellij by means of mouse clicks or key bindings. All key bindings execute one or more Actions. I for example added a shortcut to Scrollmode (G) that scrolls to the bottom of the scrollback. Trying to figure out how to scroll to the top I thought maybe ScrollAtPoint (or what it was called) may help me, but it doesn't cause any reaction. Reading the code I found out that this Action related to mouse clicks, but I don't think it can be expected by anyone wanting to play with this to read the source code.

Edit: I mean: The default key bindings are really just "suggestions". Nothing keeps me from adding my own, removing the ones that exist, rebinding them, adding more actions to them or removing actions, etc...

[a-kenji]

Thanks for clarifying @har7an,

In that case I would say that Write and WriteChars are very handy for direct user interaction.

Also thanks for doing this, I think this can be valuable. I also think we shouldn't merge new actions, that don't have any documentation at all - in general.

I am not sure yet, if I like that we document the serialization here itself.

[har7an]

In that case I would say that Write and WriteChars are very handy for direct user interaction.

Okay, I couldn't think of a direct usecase. But I can of course remove the "hints".

I am not sure yet, if I like that we document the serialization here itself.

Hm, I understand that, it looks "odd". But I wouldn't know where else to put it to keep it at least somewhat in sync with the code.

I would also offer to open a separate PR against the zellij docs repo that adds some explanations and examples so users know what to do with it. If you want that, of course. :)

[a-kenji]

Okay, I couldn't think of a direct usecase. But I can of course remove the "hints".

It is for example used to send the prefix key in the default configuration. So if you are in a nested zellij session, you can use in the outer session ^b-^b to send ^b to the inner session.

Edit: Oops didn't mean to close it.

I would also offer to open a separate PR against the zellij docs repo that adds some explanations and examples so users know what to do with it.

I would like that, yes.

Hm, I understand that, it looks "odd". But I wouldn't know where else to put it to keep it at least somewhat in sync with the code.

I don't think it looks that odd, it just seems unnecessary. Just keep it that way for now, if it becomes a problem we can still remove it at some point.

[har7an]

So if you are in a nested zellij session, you can use in the outer session ^b-^b to send ^b to the inner session.

Aha, I see. That's a clever idea, I never thought about nesting zellij sessions.

@a-kenji Would you mind explaining to me what the following actions do and maybe how to use them?

• ScrollUpAt(Position)
• ScrollDownAt(Position)
• NewTab(Option<TabLayout>) - Here in particular I wonder whether the user can influence the TabLayout somehow? Or is this usable in keybindings only as NewTab(None)?
• ToggleTab,
• Copy

Then I can complete the code documentation and start working on the user documentation with examples etc.

[a-kenji]

* `ScrollUpAt(Position)`

* `ScrollDownAt(Position)`

They fall under your definition of not likely to be used by most direct user interaction. This allows to scroll while selecting with the mouse.

* `NewTab(Option<TabLayout>)` - Here in particular I wonder whether the user can influence the TabLayout somehow? Or is this usable in keybindings only as `NewTab(None)`?

This takes a tab layout as an argument, meaning anything you can specify in the tab section of a layout. For example you can open a new tab that runs htop, bound to ^b-8.

https://zellij.dev/documentation/actions.html#newtab-tablayout

* `ToggleTab`,

This toggles between the two most recently used tabs. https://zellij.dev/documentation/actions.html#toggletab

* `Copy`

This copies the selection.

[har7an]

@a-kenji Thanks for clarifying!

It seems that Run does execute a command but it doesn't open a new pane... Tried it with:

action: [Run: {cmd: "/usr/bin/ls", args: [], cwd: , direction: Right},]

I can confirm the command is executed (Used touch instead, that created a file) but I don't see any output.

[a-kenji]

@har7an It opens a new pane, but if your command exits, it means there is nothing that the pane can display and it will close again.

You can try it with a command that will remain:

action: [Run: {cmd: "htop", args: [], cwd: , direction: Right},]

And if you close the command, it will also close the pane.

But you can always choose to keep a command there. For example running fish you can use:

cmd: fish
args: ["-C", "ls"]

That way you tell fish to run ls, and also open a shell. Because the shell is open the pane is open. You can try it out yourself when you have two normal panes open in zellij: Type exit into the shell of your choosing, the chance is high, that this will close your shell, that will likely also close the pane in zellij itself.

[har7an]

@a-kenji Ah, that makes sense, thanks!

Should I also add some more detailed documentation to the types used by the Action variants? E.g. the documentation to RunCommandAction states only "Intermediate representation", but there aren't any examples or similar.

[imsnif]

Hey, what's the status of this?

[har7an]

@imsnif Thanks for bumping this. Still waiting for feedback from @a-kenji on https://github.com/zellij-org/zellij-org.github.io/pull/150 which is meant to complement the changes proposed here. Completing one without the other will likely confuse a lot of users.