Create something akin to `vimtutor` for Helix

[Omnikar]

This would introduce the user to modal editing, and to Helix's commands and its multiple selections. I think it could be opened via something like hx --tutor, or opened from within the editor with :tutor.

This is currently WIP. Current progress can be found in runtime/tutor.txt.

PRs:

• #537
• #737
• #898

Todos:

• [x] hx --tutor and :tutor to load tutorial into a buffer (#898)
• [x] Multiple cursors (#737)
• [ ] Extend mode
• [ ] Minor modes
  • [ ] Goto
  • [ ] View
  • [ ] Match
  • [ ] Window
  • [ ] Space

[python128]

VIm tutor is basically a text file which contains explanations of keys, and some examples to work on, right?

I had a look at this site for thus info, because I never used vim: here

If so, can I have a go at this?

[Omnikar]

Yes, vimtutor is just a text file separated into lessons which interactively introduce the keys and concepts, and each of which is sized to fit on an 80x24 terminal screen.

[aeosynth]

Kakoune has something similar: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE

[Omnikar]

Kakoune has something similar: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE

I know this doesn't have to do with the tutorial itself, but what if we were to copy that title page idea?

 _   _                 __    __
| | | |         _      \ \  / /
| |_| |   ___  | | (_)  \ \/ /
|  _  |  / _ \ | |  _    )  (
| | | | |  __/ | | | |  / /\ \
|_| |_|  \___| |_| |_| /_/  \_\

[python128]

Kakoune has something similar: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE

I know this doesn't have to do with the tutorial itself, but what if we were to copy that title page idea?

 _   _                 __    __
| | | |         _      \ \  / /
| |_| |   ___  | | (_)  \ \/ /
|  _  |  / _ \ | |  _    )  (
| | | | |  __/ | | | |  / /\ \
|_| |_|  \___| |_| |_| /_/  \_\

Actually a good idea, but I would suggest using some other format, rather than the exact one used by Kakoune...

[Omnikar]

Kakoune has something similar: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE

I don't think I like the format of this in comparison to Vimtutor. The latter emphasizes that the user should learn by doing, rather than trying to memorize everything, and provides tasks for the user to complete using what is taught in each lesson. Whereas Kakoune's seems to just list the keys and describe what they do.

[python128]

How about I do it like vimtutor, but some ideas used by Kakoune's list. Eg: I can make it interactive like vimtutor, but make the keys like kakoune. i.e. :

       .---,
       | ↑ |        Movement in a buffer (the representation of the contents
   .---'---'---,    of a file opened by Kakoune) can be achieved using the arrow
   | ← | ↓ | → |    keys, which will move the cursor up one column/row into
   `---'---'---`    a given direction.
Try moving around the file!

[Omnikar]

As long as it maintains Vimtutor's premise of learning by doing by giving the user small tasks to perform using the skills they learn. Also, you might want to open a draft PR so that you can receive feedback as you work on this.

[olanod]

As someone who finds the project quite neat but a bit clueless about its full potential and advance usage I'll just stick around to watch how tutorials and documentation get better 👀

[Omnikar]

Ok, a partial tutorial has been added by #537. I'll leave this open until the tutorial is completed.

[A-Walrus]

Should there be some kind of explanation on using LSP and TS features within tutor?

TS features should be fairly straightforward, show some example code in whatever language, and ask them to navigate with go to next function and things like that.

For the language server it's a bit tricky since we can't really rely on the user having any specific language server installed can we? I would want an explanation of capabilities such as go to definition/implementation/etc..., show documentation, code actions.

[the-mikedavis]

Both are difficult to add to the current tutor because they need the document to be a language with tree-sitter and language-server support and currently it's text, plus it would need you to install the language server for that language. That may be better left off as a separate git project similar to https://github.com/rust-lang/rustlings

[CobaltCause]

It'd be cool if the tutor file was somehow templated from the configured keybinds so it would always display the correct instructions even if the user had rebound the key. I imagine this would be pretty difficult to implement though.

[correabuscar]

in 3.5 SELECT / EXTEND MODE, if I mouse click on B of FOO BAR then press b to get to F, because FOO is now selected, then when I do the suggested v2w it selects only BAR. Maybe mentioning the solution for to how to "fix" this possibility would be great to see there.

I might be the only one, but this kind of thing stops me in my tracks and I stop following the tutor and do something else, unrelated, instead. ie. it's easy to give up on helix when tiny things like this happen, and just fall back to nvim.

[DanInSpace104]

I don't know if it is problem with tutor, or with default colorscheme, but when i do 10.1 CYCLING AND REMOVING SELECTIONS after 4-th step i can't see any difference between selections at all No matter how many times i press ( or ) or Alt-) or Alt-( it looks the same:

[the-mikedavis]

That's https://github.com/helix-editor/helix/issues/3842.

[divarvel]

We might want to remove the match mode from the todo-list, since it depends on a tree-sitter grammar for most operations.

As such,

• mm does not work
• mam / mim work with brackets, braces, parens, but not double quotes
• ms works
• md / mr don't work

I was a bit surprised that mam/mim work for some pairs, but not quotes, and that mm does not work at all, even for pairs supported by mam / mim.

That makes writing a chapter on the match minor mode a bit tricky. I also tried this in a markdown file with a rust block, hoping that the language injection feature would allow using matching mode movements inside it, but it seems it's only used for highlighting (edit: with https://github.com/helix-editor/helix/pull/5176, making the tutor a markdown file would let us use other languages to demonstrate tree-sitter features)

[goyalyashpal]

if the tutor file was somehow templated from the configured keybinds - @ CobaltCause at https://github.com/helix-editor/helix/issues/506#issuecomment-1233782124

i was thinking exact same thing :)

[jokeyrhyme]

Perhaps the TS and LSP lessons could be implemented in multiple languages, and :tutor could either prompt the user to pick, or could auto-select one based on the best available combination of lesson + grammar + server?

There's probably only a handful of languages needed to significantly cover the user base

[jokeyrhyme]

We could also wait for the plugin system, and either ship the TS and LSP for the plugin system's language, or privilege that language by having :tutor show you how to install any missing pieces?