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.
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.
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!
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:
kakrc in the forumI 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 
. 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.
Not useless at all, at the end it tells you to read all the user manual by doing :h user-manual. Most people don’t do that, which is why they then say it
I agree on the length issue, but that is the only way to truly learn: bit by bit.
Coming here from Vim I was impressed with the built-in help system but absolutely at a loss about where to start first? Google didn’t help. People here mention TRAMPOLINE file, which didn’t come with my install via brew on OS X, and I’m having trouble copy and pasting it into the buffer from my browser (bracketed paste not supported?). Not a good first impression at all, although I’ll stomach it and persist because I enjoy the ideas and philosophy surrounding the editor.
Side note: how do I copy and paste the TRAMPOLINE file from Github raw file into Kakoune? Is there a :set paste (Vim) equivalent?
I guess the problem is the formatting? Easy option: first download the file and then open it. General option: \ disables hooks for the next command, then type i to insert and just paste into the terminal,
no formatting will be applied.
Yes, that was it, thank you!
Slowly reading through the help documents, and I found the answer at the very end of the :help FAQ document, which was exactly what you mentioned and what I used.
Besides already mentioned \, you also can set up xclip or xsel. I’ve mostly copied and pasted via these mappings which invoke xsel.
Thanks for the link, I’ll have to modify that to use pbcopy/pbpaste for OS X defaults.
I would like to share a snippet that I came up with for a command that downloads and pastes the TRAMPOLINE file to a scratch buffer.
define-command -docstring "open a tutorial" trampoline %sh {
tramp_file=$(mktemp "kakoune-trampoline.XXXXXXXX")
echo "edit -fifo $tramp_file *TRAMPOLINE*"
curl -s https://raw.githubusercontent.com/mawww/kakoune/master/contrib/TRAMPOLINE -o "$tramp_file"
}
It creates a temporary file, uses it as a fifo buffer, and uses curl to download the raw TRAMPOLINE file and write it to the temporary file.
Edit: Fixed minor error.
That’s awesome! Wish Kakoune had a startup screen like Vim that could run this for new user. It’s a rather large hump super early on in learning Kakoune that I think is easily fixed.
I realized that my original snipped has a number of issues that should be resolved with this:
define-command -docstring "open a tutorial" trampoline %{
evaluate-commands %sh{
tramp_file=$(mktemp -t "kakoune-trampoline.XXXXXXXX")
echo "edit -fifo $tramp_file *TRAMPOLINE*"
curl -s https://raw.githubusercontent.com/mawww/kakoune/master/contrib/TRAMPOLINE -o "$tramp_file"
}
}
The previous version creates the temporary file in the current directory rather than /tmp and also creates (but does not open) the file every time that Kakoune is run.
For pasting into terminals: Ctrl-Shift-V on pcs and Cmd-Shift-V on macs should work