Improve description. Document a bit more.
useredsa opened this issue · comments
The README 's description says:
Leverage the client-server architecture of Kakoune to connect programs to clients.
I think it's a rather short description.
With the new addittions to the plugin, I recognize I'm a bit lost and I don't know what's the purpose of some of the tools. I understand the objective of the plugin has always been to "connect" external apps to kakoune easily. For example, opening a file browser and having it open the files in the kakoune client. Unfortunately, I couldn't find the answers I wanted in the readme.
-
What is the use of
:connect-detach?
The docstring says: «Write an attachable program to connect.sh and detach the client».
Although everybody understands that detaching a client is closing it (right?), what is an attachable program and what isconnect.sh?connect.shis a file created by the commandconnect-detachthat can be used to execute the program given toconnect-detach(or the shell in general) in the context of the kakoune server.kak-shelluses this, for example. Isn't this kakoune command supposed to be hidden? When would we use it? Doesn't the name make it feel as if it had something to do with:attach? The description makes it feel as though as if the file would be automatically executed when the client closes. -
What is the use of
kak-shell?
It seems to me that it can be used to connect a non-connected terminal to a session, but the name suggests it is meant to be used as a shell. Indeed, it serves to execute a program connected to a kakoune session (by default, your shell). This is likeconnect-detachbut from outside kakoune, only that it lets you select a session. Am I right? And when would we use this?
In addition, would it be more useful if the shell changed directory to kakoune's server directory? -
How to customize the prompt?
Ok, I realized how I could do this. I added the following code to my.bashrc, but I didn't know what to do with that line at first.
# Prompt: Kakoune's connect plugin prompt + usual bash prompt
PS1='[\u@\h \W]\$ '
if [ -e ~/.local/share/kak/connect/prompt ]; then
PS1="\$(~/.local/share/kak/connect/prompt)$PS1"
fi
- The commands are not in the readme.
It is necessary to read the source code. I don't know if this is intentional, but it's at least a bit uncomfortable to have to navigate over github to read about them (if you don't have the plugin installed).
@alexherbo2 What's your opinion? Can we include more thorough explanations in the README or in a wiki page?
I could help to write some of the explanations.
I've started modifying the README.md.
@alexherbo2 , Could you answer these questions?:
- What is the use of
:connect-detach? - Isn't this kakoune command supposed to be hidden? When would we use it?
- Don't you think it's better to rename either
connect-detachor:attach?
I would also like to add FAQ.md and RECIPES.md pages inside the wiki.
The command really detaches, leaving a gem. It can be used to reattach later.
The command really detaches, leaving a gem. It can be used to reattach later.
Hmm... I don't use it much, honestly. Can we change the docstring then? Without seeing the source I wouldn't have said it did create an external file which you needed to source. Maybe we could also add an example in the README.
Yep
My current work is here.
I can include the FAQ.md and RECIPES.md files as wiki pages or as project files. What do you prefer?
Wow it looks awesome!
Something graphical could be a nice addition with the recent updates.
I have 2020-08-14 17:28:38 where I use Dolphin as a project drawer, like in Sublime Text, but I want to redo the video properly.
I can include the
FAQ.mdandRECIPES.mdfiles as wiki pages or as project files. What do you prefer?
I’m not sure yet. I’d like something like the documentation of Krabby.
Wow it looks awesome!
Something graphical could be a nice addition with the recent updates.
I have 2020-08-14 17:28:38 where I use Dolphin as a project drawer, like in Sublime Text, but I want to redo the video properly.
I can include the
FAQ.mdandRECIPES.mdfiles as wiki pages or as project files. What do you prefer?I’m not sure yet. I’d like something like the documentation of Krabby.
I don't really want to get into recording videos right now.
You can do the same with broot instead of dolphin.
I have these screenshots:
Regarding documentation organization, let's set up a docs folder then. I can add there these two files. In the future we can add other files with topics such as desktop integration using the desktop entry. Does it sound right?
Yep
@useredsa Does Broot support the mouse?
@useredsa Does Broot support the mouse?
Yup.
By the way, the alias : conflicts with the internal Null command (help :) from a posix shell.
We can remove it.
We can remove it.
Or replace it by :s. Choose whatever you prefer.
@useredsa I just added a :fifo command.
You can use like this:
rails routes | :fifoOr directly:
:fifo rails routesIt creates a *fifo* buffer in the client that reads the command output.
You can directly do fifo from Kakoune if you required the module.
@useredsa I just added a
:fifocommand.You can use like this:
rails routes | :fifoOr directly:
:fifo rails routesIt creates a
*fifo*buffer in the client that reads the command output.You can directly do
fifofrom Kakoune if you required the module.
I'll wait and add more additions together.
I added this video as a demo, but it is just temporary.