In Editor Tutor Like :vimtutor or nvim's :Tutor

Fairly self-explanatory.

I think it should be somewhat similar to Vim/Neovim’s, however going over some of the Kakoune specific stuff.

Also probably some things you can do in GUI editors/IDEs that you can already do in Kakoune out-of-the-box. I think it should also go over more advanced key combinations.

Inner and outer text objects, custom text objects, regex based selection, and probably a brief overview of things like def, define-command etc.

1 Like

It’d be great, and it’s the kind of thing people ask about often, but nobody yet has had the time to sit down and write a complete tutorial from scratch.

vimtutor specifically has a lot of polish, with a command built-into Vim and an external script and support for translations, but at its heart it’s just a plain text-file that anyone could write. Once somebody’s written the text-file, adding all the extra polish is comparatively easy.

And as a tutorial, each step builds on the previous one, so it doesn’t have to be written all at once. You could start by writing an outline, and then write lessons one-by-one, and at each point along the way you’d have a useful (if limited) tutorial. If one author didn’t make it all the way through the outline, another one could take over.

The problem is just finding somebody with enough time and interest to begin.

I’ve found vimtutor useless, as it shows some basics and then throws you into the open world of Vim with literally no knowledge besides how to move around and yank/paste stuff. The problem is, that if you have tutorial that covers literally everything, then it is very long read. If tutorial covers essentials, it doesn’t really help besides that. So I think that documentation is a much preferred read. A tutorial that points to documentation, and teaches how to interact with it I think is a good compromise.

2 Likes

Isn’t Kakoune trampoline (link below) already something similar to Vim tutor? It does contain the basics and it does mention <a-i> and <a-a> text objects. Sure, it is not as polished as Vim tutor but I found it an excellent introduction. And it has the advantage of being short. For more complex things such as scripting, so far there is no alternative to the documentation, as Andrey said.

But some day there will be a book, Learn Kakoune the hard way!
:grinning:

I suppose you’re right but you have to admit that vimtutor gives some more exposure to Vim, and so does VimGolf.

I personally just have beef with Kakoune’s documentation. One big set of sparse .asciidoc files on Github doesn’t feel very helpful. Though I’ve never written online docs for software, so good alternatives aren’t immediately apparent to me other than possibly having a non-Github wiki in the form of a website.

What little more I know of Kakoune than your average Joe Shmoe who looked at the Github page is from digging around and looking at some of y’alls configurations and asking y’all here. Not looking at docs, which is not a good sign. Part of what Vim wizards know is from fudging around with keys and digging around the docs, but I feel it’s better to be as upfront with things like advanced key combinations and configurations as reasonably possibly, rather than someone copypasta’ing something from someone else’s config or a Github wiki page.

That’s sort of why I think a tutor would be a bit better. And if Kakoune is all about improving upon Vim, than I don’t see why it wouldn’t be possible to find ways to improve upon what is given in vimtutor.

For me, I learned from:

  • Kind of the Kakoune introduction mentioned and using it a little bit with the verbose mode.
  • The doc command
  • The Github Wiki
  • The plugin list to see what I could do
  • People’s kakrc in the forum

I think the Wiki and the doc command is great. The fact the clippy makes easy to find everything is great also. That’s why I didn’t need a tutorial, unlike with vim.

I was quite happy learning the basics from the TRAMPOLINE walkthrough (by the way, why is it called that?) If you want a “kaktutor”, just run kak < TRAMPOLINE :stuck_out_tongue:. That said, I knew Vim already so I mostly knew my way around anyway.

The asciidoc files accessible through the :doc command are great as a reference but it’s not clear where to start for beginners. Maybe a proper manual or user guide with a linear progression and learning curve would be more approachable to new users.

I wasn’t familiar with vimtutor and just read over some of it.

Would it be considered poor taste to just copy/modify the existing vimtutor for kakoune (Granyed with a ton of reorganization)? I’m a huge fan of the Feynman technique, and I was thinking about trying this to getter better acquainted with kakoune, but I don’t really want to write the stuff pertaining to navigation which is mostly the same.

Also how long is too long for a tutorial? Given this helps me cement stuff into long term memory, I’d like to keep it going into way more advanced stuff(such as writing plugins and custom modes) but totally understand if that is beyond the scope of a built in tutorial.

I can’t find any explicit copyright licence on the vimtutor text. There’s contact details for the author, but the fact that it mentions “bitnet” suggests the details are very, very old. A web search for “Bob Ware Colorado School of Mines” brings up a likely-looking obituary from 2013, so contacting the author for permission may prove difficult.

It might be worth posting in the Vim subreddit or mailing list or something, just to see if anybody objects, but as a practical concern it’s probably fine to just copy the most relevant parts and acknowledge the source in the beginning “what is this document” section.

The best discussion of tutorial-writing I’ve read suggests that the point of a tutorial is to get the user to that first rush of “I can do this!”. It doesn’t need to be something interesting or useful, it just need to be something complex enough that they can’t do it by accident, and simple enough that they can get there by mechanically following instructions. Documentation about writing plugins and custom modes is definitely needed too, but might be better suited as how-to guides or even explanations rather than tutorials.

While I don’t really have the time or focus to write comprehensive Kakoune documentation at the moment, I occasionally blog about things as I learn them, and it would be great if there were more blog-posts about Kakoune in the world, for people to find via search-engines and the like.