Kakoune has a lot of good reference documentation — lists of commands, of options, of key-bindings, etc. but not a lot of explanation documentation that describes how all those things work together. I figure the first step toward making that possible would just be to list all the concepts involved, and I figured a brainstorming thread would be a good way to gather that information. Off the top of my head, Kakoune has:
I would love to be able to do: :doc toc. For a table of contents that would give a global view of the documentation and it’s subsections. I am unfamiliar with *.asciidoc and don’t know if it would be possible.
Thanks @Screwtapello you have given me something to think about. Talk later, bye .
If I am a user and would like to build add-highlighter
how would I know to do the following from the :doc completion menu
(Display → Highlighters) → (Regex → Faces)
Kind of. Options can be set to any value by scripts, and other scripts (and sometimes the C++ core) pay attention to them. Values are just information from the core, made available for scripts to use. If your script is only interested in examining the current state of Kakoune, then yeah, they’re effectively immutable options.
I can’t think of a good name. Those are part of the command-line that starts Kakoune, but Kakoune also has its own internal command-line (the : prompt). Vim documents these under “how to start Vim”, which makes sense, but I’m hesitant to duplicate information between the manpage and the online docs. That particular relationship could do with some polishing too.
Possibly. It’s weird, everybody talks about installing plugins and writing plugins, but plugins aren’t actually a thing in Kakoune’s core, they’re just a sort of convenient side-effect of the way a bunch of other features work together. Maybe there should be “plugins” documentation just to explain that fact and point to all the other things.
That kind of already exists - if you type :doc the completion menu will list all the available pages of documentation, and once you pick a page, the completion menu will list all the subsections of that page.
I think it would be interesting to talk about how to organise the doc.
Acording to this theory, they are 4 type of documentation tutorials , how-to guides , technical reference and explanation
I would add another one to the list : cheat sheet
Today kakoune has documentation hosted in different places:
:doc command
github wiki
forum manual++ , recipies etc…
independant blog article
Maybe we should establish some rule of what should go where
As a new user of Kakoune (I started using it this year), perhaps I can share some of my experience trying to get through the docs while my memory is still more or less fresh.
I think that the main problem of Kakoune documentation is that it is organised by concepts, more or less in the lines of the concept map sketched here. And this is a problem because, when you first enter the Kakoune world, you are initially not that interested in all the concepts, but in making the editor adapts to your workflow.
For instance, in my personal experience, when I started using Kakoune, I think I was trying to find answers for the following questions (and in the following chronological order):
where’s the configuration file?
how can I customise its appearance? Including:
changing the color scheme
showing line numbers
line wrapping
hiding the Assistant (yeah, yeah, I hide it, even though it’s cute)
making a tab displays as 4 spaces
how can I edit this buffer the Kakoune way instead of just do basic operations?
how am I supposed to make new selections? Isn’t there an equivalent of the <c-n> key of vim-visual-multi? If I can’t easily make new selections, why would I switch to this editor?
how can I install plugins?
how can I exchange d and <a-d>, and c and <a-c>? By the way, why replicate such an arcane and counter-intuitive behaviour from the old ages of vi?
how can I make new mappings?
specially, how can I make a mapping to call : buffer and make me select a buffer fast using Kakoune’s built-in fuzzy finder?
how can I make a file with a custom extension being recognised as a known file type?
how can I set custom options based on the file type?
how can I define a new command to automate this thing I do often?
how can I script Kakoune?
Note that organising the docs by concept (like commands, expansions, execeval, faces…) don’t help to answer most of the questions above fast. It certainly didn’t help me.
I remember I almost gave up migrating to Kakoune just because I thought it didn’t have line wrapping. I couldn’t find it in the docs regardless of how much I tried. How could I know it was in the highlighters section?! I saw this name – highlighters – and thought it was related to creating custom color schemes. It wasn’t until I decided to search the issues in the Github repository to see if there was any demand to implement it that I saw it was already implemented. Then, it took me some more time of searching in the issues until I finally found how to do it.
Perhaps we could try to figure out a way to organise the docs by action (how can I do what I want to do?) instead of concepts (what’s the definition of expansions?). I don’t know how exactly it could look like, but it could have at least these topics:
UI customisation with code snippets as examples;
editing text the Kakoune way (with lots of useful examples);
behaviour customization, like defining mappings and dealing with hooks (with many examples);
scripting Kakoune (with tons of good code snippets as examples).
And, please!, let’s think about writing good examples in the docs. They help a lot!
So much yes to all of that @gustavo-hms. I would add an introductory document that explains what the kakoune way of doing things is and gives an overview of it’s abilities by example. Honestly your recent musings on selections as functors and how to avoid shelling out by embracing the editor should be required reading… Something along it’s lines would go a long way towards enlightening new users to what is possible. It doesn’t need to explain absolutely everything, just show enough to help the user break out of their mental models coming from vim, emacs, sublime, vscode or whatever and embrace the power of the kakoune way.
I can totally relate to what @gustavo-hms sayd. It also took my look time to find the line wrapping feature!
Yes . But please don’t put it in the :doc command. I don’t like reading long article inside my text editor. Editor are made for code. If I’m reading documentation, I want a clear page with a nice typo and a breathing layout. Maybe with images and videos to help me understand.
I think ‘:doc’ should act like a quick cheat sheet to recall a command without leaving the editor. A bit like the tldr or cheat.sh command in the terminal.
.