Documentation for fundamental concepts

[m-kru]

After experimenting with kakoune for 2 days, the things in my head start getting blurred. I read the :doc, github Wiki plus some stuff in the Net. However, I still have not found any documentation with definitions for basic concepts such as: server, client, session, context, window, buffer. Now, imagine that you come across following sentence in the docs:

By default, their execution happens within the context of the current client, ...

It is really hard to understand the docs, when you do not know what basic concepts mean, and how they relate to each others. Does documentation with fundamental concepts exist and I just can't find it? If no, then it would be really nice if some experienced user could provide it. It would really make life of newcomers much easier.

[lenormf]

Several things could be explained better in the documentation, however the line has to be drawn somewhere with regard to the a priori knowledge that we expect users to have.

Users who are familiar with modal editors know what scopes (window, buffer, global) are.

Users with a certain level of tech-literacy know what client/server architecture or a context/session are. Note that this editor is branded as a code editing tool, which means the assumption is that you are some type of programmer, or at least familiar with software. It's not unfair to expect savvy users to understand these specific terms.

If we keep going down the layers of knowledge that a randomly selected user might not have, we'll find that some might not know what a “terminal” is. Or what “codepoint” refers to. What a “shell” is.

The documentation would turn into a big mess (which it already is) and a maintenance nightmare if we let the line be drawn too far out.

So could you make the exact list of terms you don't understand (i.e. no grouped statement like “fundamentals”), so we can then decide whether it's reasonable to expect users to know what they refer to?

[m-kru]

@lenormf I can't agree with all you have written.

Users who are familiar with modal editors know what scopes (window, buffer, global) are.

With the above I can agree. Scopes are actually described in :doc scopes.

Users with a certain level of tech-literacy know what client/server architecture or a context/session are. Note that this editor is branded as a code editing tool, which means the assumption is that you are some type of programmer, or at least familiar with software. It's not unfair to expect savvy users to understand these specific terms.

I feel like I have more than "certain level of tech-literacy" and I do not agree with the above. All terms client, server, context, session are always somehow specific to the domain/application.

If we keep going down the layers of knowledge that a randomly selected user might not have, we'll find that some might not know what a “terminal” is. Or what “codepoint” refers to. What a “shell” is.

I agree, you always have to draw the line somewhere.

The documentation would turn into a big mess (which it already is) and a maintenance nightmare if we let the line be drawn too far out.

I think the documentation is quite good. Personally, I find it better than vim's documentation.

So could you make the exact list of terms you don't understand (i.e. no grouped statement like “fundamentals”), so we can then decide whether it's reasonable to expect users to know what they refer to?

1. When are servers and client spawned?
2. What is server responsible for?
3. What is client responsible for?
4. How is session related to server? Is it 1:1?
5. What is bonded to context, only options?
6. What is bonded to session?
7. What does manage contexts, server/client?

8. What does manage sessions, server/client?

   Please forgive me if some of the above questions are answered somewhere in the docs. Probably I just have not come across them yet.

[Screwtapello]

I wouldn't describe these as "fundamental" concepts; they're concepts that Kakoune is built on, but as a user they don't matter much unless you're doing tricky things with scripting - I'd say Kakoune's fundamentals are things like "insert mode vs. normal mode" and buffers and registers.

When are servers and client spawned?

If you run kak -d -s foo you get a headless server for a session named "foo".

If you run kak -c foo you get a new client that connects to an existing session named "foo". The :new command inside Kakoune launches a new terminal and runs kak -c inside it.

If you just run kak, you get a server and a client, although as an implementation detail they happen to be in the same process.

If you run kak to create a client-and-server, connect a new client to it, then quit the client-and-server, it will spin the server off as a new background process so the external client still has something to talk to.

What is server responsible for?

Pretty much everything.

What is client responsible for?

It collects keyboard and mouse input, and sends it to the server. It receives text to display, and draws it to the terminal. The client/server protocol is not the same as the JSON-UI protocol, but it should give you an idea of the kind of data passed back and forth.

However, note that there's also "window scope". Window scope is a particular buffer displayed in a particular client, so although all the window-scope information is stored in the server process and manipulated in the server process, a reasonable person might associated it with a client.

How is session related to server? Is it 1:1?

I would say the server is the specific Unix process listening on the rendezvous socket, and the session is the server and all the clients connecting to it. So yes, 1:1.

What is bonded to context, only options?

I'm honestly not sure.

• The exec/eval docs for -draft say "Modifications to the selections or input state will not affect the client."
• The expansions docs have a bunch of expansions that are only available in special circumstances, like hook_param only being available in the body of a hook.
• The commands docs for :on-key mention that it waits for a key from the current client context, so if it's executed inside a draft context it won't ever receive a key unless you use :execute-keys

So at least selections, expansions, input-handling and display can be part of a context. On the other hand, the docs sometimes mention "buffer context" or "global context", which presumably don't have those things. If I had to come up with a concise definition, it might be "a scope, or a temporary copy of a scope".

I wonder what happens if you try to define a mapping in a draft context?

What is bonded to session?

• The set of defined options
• The set of declared commands
• The set of provided modules
• The set of connected clients
• The set of installed hooks
• The set of user modes

etc.

What does manage contexts, server/client?

As mentioned above, everything exists in the server, including contexts.

What does manage sessions, server/client?

Since sessions and servers are 1:1, neither the server nor the client manage sessions. You can list existing sessions with kak -l, you can start a new session with kak -d, you can terminate a session with echo kill | kak -p.

[lenormf]

Looking at the questions, I think a way to frame the problem of this issue is the following:

• You would like the documentation to be prescriptive, to explain every term, mechanism and the implications of their uses when combined.

• I would like the documentation to remain descriptive, to explain the terms whose definition can not be intuitively derived from the generally accepted ones (provided we assume the users understand them, c.f. the line drawing problem), and let users connect the dots about the rest.

I'm not against expanding more on terms and concepts experienced users take for granted. I suppose some words mentioned in the original issue could be explained somewhere.

But I also don't think the followup questions asked are not relevant to the documentation, they're more of implementation details. You can work out rough answers to all of them by simply experimenting with the editor - it's not clear why you would need those questions to be answered specifically in the first place any way.

It might make users feel more secure to have lots of prose to potentially read through when they're starting up with the editor. It allows them not to have to think, one only needs to look at the words. But they're not the ones bearing the burden of maintaining an encyclopedia, that's why expectations and demands need to be tempered.

[mawww]

I think it would make sense to document at least some of those concepts that are not easy to derive, or some, like window that are still confusing to most long term users (for example, window are not tied to a client, they can move between clients...).

session and server are basically the same thing, although server refers to the process and session to the state it holds.

[edrex]

@m-kru's reported experience as a new user encountering the terms client, server, session, window scope in the documentation matches my own, as although I'm steeped in network engineering culture, their use in Kakoune's case is domain specific and the finer points of their interaction are not immediately obvious. Also, I think their knowledge is valuable background for more than occasional users of the editor, since their effective use has clear benefits (avoiding clobbering due to duplicate buffers for instance)

@Screwtapello's answers above are concise and helpful, and with a little editing would serve as embedded documentation for these concepts. I would be willing to submit a doc patch. Standalone "client-server" doc? Or maybe "concepts" or "glossary". Awaiting guidance/go ahead from a more experienced contributor.