Remove the interactive tutor

[dlejay]

This PR removes the interactive tutor from Vim.

Rationale

The vimtutor is one of the most beautiful features of Vim. It teaches “Vim by doing” and does it by having the beginner use just Vim and a file.
The innocent beginner simply types vimtutor in a terminal and at the end of the self-contained tutor, they already know how to use basic Vim commands because they have been using Vim by themselves.

The vimtutor can and should be improved. The Neovim project replaced the traditional vimtutor with their own version. :Tutor launches their interactive tutor.

Things that the vimtutor can take from the Tutor

I see some nice additions that should likely be transferred to the vimtutor, such as :

• a dedicated syntax file, to highlight keys like <ENTER> in a different colour
• using a few emojis to help navigate the text for example.

Things the vimtutor should not take from the Tutor

The interactive tutor uses hyperlinks that, in my view, introduce serious problems :

• while the cursor arrives at the end of the hyperlink, pressing l does not make the cursor move to the right. It feels like the cursor is “stuck” on the hyperlink (until you press l enough times). I think this behaviour is unacceptable for the vimtutor ;

• the beauty of the vimtutor is that it teaches Vim by using Vim, not by using a Tutor infrastructure. In Vim, you cannot expect hyperlinks to be accessed via <Enter>.
  As an analogy, if you put the so-called “training wheels” on a bicycle, children learn the training wheels, not how to ride a bike.

The first chapter is less progressive than the original vimtutor and puts many possible distractions with the links and all the possibilities to actually exit the focus of the Tutor.

The Tutor introduces exercise validation, which is again a distraction for the user. The vimtutor let them fully interact with Vim + a raw file.

Vim should not have several tutors

Just having to type vimtutor in a terminal is very beginner friendly. They hardly need to know anything.
With Neovim, they need to type first nvim then inside Neovim type :Tutor.
Currently to access the Tutor in Vim, they need to do the same thing, how are they even supposed to know about this ?

Having both tutors makes no sense, is confusing for the beginner (if they ever happen to know there are two), is confusing for the maintainers and requires double the amount of translation effort.

Conclusion

I think having the Neovim Tutor alongside the vimtutor is a net negative and it should be removed.
The good ideas from the Tutor should be incorporated into the vimtutor one at a time.

Disclaimer

I am always happy to be shown a different perspective and to change my opinion. Please feel free to share any disagreement.

[brianhuster]

Just having to type vimtutor in a terminal is very beginner friendly. They hardly need to know anything.

Is the vimtutor available for users who only have Vim installed via appimage?

With Neovim, they need to type first nvim then inside Neovim type :Tutor.
Currently to access the Tutor in Vim, they need to do the same thing, how are they even supposed to know about this ?

Then how would users know about the vimtutor command?

That being said, even though I contributed a few patches to the new Tutor plugin recently, I don't like it either, but not because of your reasons but because it is badly designed (IMO). Making change to a tutor file could be very error-prone if contributors and maintainers don't notice the corresponding .json file. Unfortunately it doesn't seem possible to fix without rewriting the whole plugin, so I don't think I have problems with removing it.

But anyway, I think the tutor should still be available to Vim users via an Ex command

[dlejay]

Is the vimtutor available for users who only have Vim installed via appimage?

I have no idea. Is a beginner (that would not know how to fix the problem) likely to be in this situation ?

Then how would users know about the vimtutor command?

:-) Correct. At least a complete beginner is not asked to enter the command mode with :.
Maybe, the vimtutor could be advertized on the welcome page of Vim ?

Having the vimtutor be launched via an Ex command makes sense to me.

[brianhuster]

At least a complete beginner is not asked to enter the command mode with :.

But a beginner is already asked to exit Vim with :quit<Enter>

[RestorerZ]

Just having to type vimtutor in a terminal is very beginner friendly. They hardly need to know anything.

As far as I know, :Tutor can also be run from the vimtutor command file.

Actually, as I remember, the history of including an interactive tutor is a long time ago. And it started back when Bram was still around, but he didn't do it (there's a discussion here somewhere). But now this tutor is in the package and it's unlikely to be abandoned for nothing. Considering the man-hours spent on its support, translation into other languages and your not very convincing arguments.

To be honest, I'm not crazy about the interactive tutor either, also because of the complexity of preparing the translation and maintaining it. One good thing is that it doesn't change that often.

---

Here's found this discussion: #6414

[dlejay]

@RestorerZ

Thanks for the link to the discussion. I can see that Bram and @lilydjwg raised similar concerns.

Regarding the man-hours, this shouldnʼt be an issue as this Tutor will likely stay the unique tutor of the Neovim project. And I guess anyone could add it as a plugin ?

Would you agree that Vim should have only one tutor ?

---

What should we tell beginners ? To me it is : “you have never used Vim before ? Open up a terminal and type vimtutor” end of story. Once someone has been through vimtutor, going through :Tutor is not useful.

So to me there can only be two possibilities :

1. :Tutor is the “better” version of the vimtutor and once all chapters have been translated, the “old” vimtutor is dropped. This is the Neovim path.
2. vimtutor is the default tutorial to learn Vim and there is no use in having :Tutor.

But maybe I am missing a scenario / use case where having both in the repo is beneficial.

[brianhuster]

I think vimtutor should be removed, it doesn't exist in appimage build anyway. On the other hand, if possible, I would hope :Tutor can be simplified, I think it is also OK to make :Tutor behave exactly like vimtutor.

But anyway, I think it's also worth noting that the new tutor plugin is also a framework for plugins to create their own interactive tutorial. An example is vim-visual-multi

[chrisbra]

Sorry, but I think both can have their place. I don't think that the interactive tutor has much of a maintenance burden as I think the tutor doesn't change much. So I don't see the problem in maintaining both versions here.

[dlejay]

@chrisbra What is the rationale behind having both ? What is the intention behind each of them in that scenario ?

@brianhuster If I understand correctly, you are in favour of

1. dropping the current interactive tutor
2. having an Ex command :Tutor that launches the current version of the vimtutor
3. dropping the vimtutor executable.

I think that is a solid option.

[lilydjwg]

What should we tell beginners ? To me it is : “you have never used Vim before ? Open up a terminal and type vimtutor” end of story.

I think I got to know vimtutor by tab-completion in the shell despite I learned Vim first via a book. vimtutor was a good practice exercise for me.

I think it's also worth noting that the new tutor plugin is also a framework for plugins to create their own interactive tutorial.

As I've said before, what it creates is a test, not a playground that people are encouraged to try and learn things. When I learn things, I don't always do the exercises from the tutor, and try whatever ideas that come out of my mind at the time; I learn something either they work or not; I don't want to complete certain tasks when I'm learning.

It shouldn't be called interactive tutorial. It has nothing like what other interactive tutorials I've come into. It should be called testing or task tutorial.

[chrisbra]

the original vimtutor works well, but may look scary to a new-user unfamiliar with a terminal. That's why I like the new style tutor. I think calling it interactive is fine, but I don't really mind, we can also call it tutor-plugin if you want.

So the point is:

• the original tutor is fine for old-style people, that are not afraid staring at a black screen or are familiar with working with a terminal
• users, unfamiliar with terminals may however appreciate a bit more interactive tutor style, which gives better feedback
• the original tutor itself didn't change much, as such I don't anticipate a lot of maintenance burden (or even updates) and I am not that much afraid of different deviating content

In any case, I don't have a strong feeling about it, if everybody would prefer deleting it, so be it.

So community, please speak up.

[brianhuster]

the original vimtutor works well, but may look scary to a new-user unfamiliar with a terminal.

Which is why the author of this PR suggested including a syntax file for vimtutor

[dkearns]

I think I missed it when this was added so I'm looking at it for the first time.

I don't really think it makes sense to have two beginner tutorials covering the same material. They, confusingly, feel like they might be from different versions of Vim.

I've just started running through it and opened the help section as suggested at the start of Lesson 0 and I'm dead in the water, with the cursor in the help window. I'm already a bit discouraged.

I also noticed that moving the cursor through the concealed text was a problem, as @dlejay mentioned. Putting my "day one with Vim" hat on, it felt like the cursor was stuck.

It looks like this came from Neovim so I assume it's had a fair run over there but it seems like it could do with some polish as it stands.

I also set everything in $VIMRUNTIME as nomodifiable so, I couldn't edit the text. :)

My first impression, for what it's worth, has me agreeing with everything in the OP.

[RestorerZ]

As I've said before, I'm not crazy about the interactive tutor.
It is imperfect, and sometimes it just doesn't work as it should. For example,
if you delete a text in a task in one of the lessons, the subsequent tasks do
not work as expected. And other flaws that have already been mentioned here.

However, I haven't seen a single convincing argument from the author why it is
necessary to remove an existing separate plugin. Some of his arguments could
still be considered if a decision was made to include the plugin in the
distribution. But not now that the module is already there.

The author insists that there is a vimtutor command, but it is not a command,
but a command file. If in this command file instead of the command
$VIM -f -u NONE -c "set nocp showcmd" "$TUTORCOPY"
you put the command
$VIM -f -c ":Tutor"
you will open not the good old tutor, but the interactive tutor.
So the beginner also only knows about the vimtutor command to enter in the
terminal.

So it can be considered that this argument of the author is untenable.

The author goes on to say that there should be only one tutor. But he doesn't
say why. Why can't there be several different ones? Everyone has their own
tastes and preferences.
If a beginner starts learning Vim not with a tutor, but with the documentation
and reads that there is also an interactive tutor and wants to work with it.
What's wrong with that?

So this argument doesn't hold up either.

As for the shortcomings of the interactive tutor, I think they can be fixed and
the interactive tutor can be improved one way or another. It is possible that
someone will do it and we will get a marvellous learning platform. But it
definitely won't happen if there is nothing to fix and improve.

My point is that there is no point in removing a separate plug-in that already
exists. Especially since its support does not require large community
expenditures. And by removing this plugin, it is possible that we will lose
more than we gain.

[RestorerZ]

And if the author is so dissatisfied with the existing interactive tutor, he
can improve the good old tutor so that there is no point in an interactive
tutor at all. For example, make a syntax highlighting file for the tutor. Or
something else. And then there will be no sense in the interactive analogue.

In general, it should be competition and user's choice rather than thoughtless
deletion and prohibition of something.

[brianhuster]

Why can't there be several different ones?

Maintainance cost and inconsistency. Because the Tutor file has some outdated thing, I once sent a PR to update the new tutor file. But I didn't realize that the vimtutor tutor file is still maintained separatedly, so vimtutor tutor file is still outdated and inconsistent with the tutor file from :Tutor

[brianhuster]

As for the shortcomings of the interactive tutor, I think they can be fixed and
the interactive tutor can be improved one way or another.

No, it can't be fixed without breaking change that will make it a totally different plugin. For this reason, I would also like Neovim to remove the "interactive" part of :Tutor plugin as well.

[chrisbra]

Maintainance cost

Ahm, check how many changes there were for the old tutor and it took us only about 20 years or more to include chapter 2

[RestorerZ]

No, it can't be fixed without breaking change that will make it a totally different plugin.

But doesn't that mean "in one way or another"?

And isn't it more prudent to have at least a not worse alternative before removing something?

[brianhuster]

And isn't it more prudent to have at least a not worse alternative before removing something?

I already told that alternative: make :Tutor command just behave like vimtutor, and add syntax highlighting to vimtutor

[dkearns]

Some of his arguments could still be considered if a decision was made to include the plugin in the distribution. But not now that the module is already there.

It hasn't made a release, no one's work flow depends on it, what is the cost of removing it?

[brianhuster]

Ahm, check how many changes there were for the old tutor and it took us only about 20 years or more to include chapter 2

That's why it has been outdated for so long time. Based on this StackOverflow thread, 'wildmenu' feature was added at least 13 years ago yet "Completion" section of the tutor was not updated until I sent a patch this year. And that patch only applied to the new Tutor plugin, which means vimtutor is still outdated.

[RestorerZ]

I already told that alternative: make :Tutor command just behave like vimtutor, and add syntax highlighting to vimtutor

All right. Let's do a decent highlighting of the old tutor's syntax first. And then we'll think about deleting it.

It hasn't made a release, no one's work flow depends on it, what is the cost of removing it?

The main development doesn't depend on him, I agree. And the cost of its removal consists of the resources already spent on implementing an interactive tutor, fixing bugs, translations into other languages.

[gdupras]

It hasn't made a release, no one's work flow depends on it, what is the cost of removing it?

Ubuntu 25.04 has Vim 9.1.0967 in its repositories. The new tutor was added in 9.1.0836.

[brianhuster]

And the cost of its removal consists of the resources already spent on implementing an interactive tutor, fixing bugs, translations into other languages.

Then we can just remove the "interactive" part of new Tutor plugin, and make vimtutor call :Tutor command. Whatever, I think the main point of this PR is just to deduplicate tutor feature and remove the "interactive" part which the PR author thinks to be useless and I think to be badly designed and error-prone.

[chrisbra]

Ubuntu 25.04 has Vim 9.1.0967 in its repositories. The new tutor was added in 9.1.0836.

We were talking about a new (stable) Vim release, so probably Vim 9.2

[gdupras]

We were talking about a new (stable) Vim release, so probably Vim 9.2

Yes, I understand that. My point is that since this new Tutor is included in a major Linux distro, the assumption that "no one's work flow depends on it" may not be correct.

[chrisbra]

most of the initial porting work was done by @yegappan so I'd also like to hear from him.

[brianhuster]

the assumption that "no one's work flow depends on it" may not be correct.

How could someone's workflow depend on a beginner tutorial?

[xmready]

If you are interested in the input of a random user, I think improving vimtutor and having :Tutor behave the same makes the most sense to me.

[habamax]

New :Tutor is fancy and may please newcomers. However, looks like all/most (citation needed :)) newcomers go to neovim anyway so I would go for our oldschool vimtutor being a vim thing.

It might benefit to add syntax highlighting there as was suggested, but I find plain non-colored text in vimtutor beautiful and non-distracting.

PS, on windows with the recent gvim after running :Tutor:

[vim-ml]

On Wed, Jun 25, 2025 at 12:28 PM Christian Brabandt < ***@***.***> wrote: *chrisbra* left a comment (vim/vim#17600) <#17600 (comment)> most of the initial porting work was done by @yegappan <https://github.com/yegappan> so I'd also like to hear from him.

The tutor plugin is specifically designed for first-time Vim users, providing an interactive introduction to Vim. Compared to the older version, this plugin offers a more hands-on learning experience, which significantly lowers the barrier for new users learning Vim commands. As previously mentioned, the maintenance cost is minimal. Given its usefulness and low overhead, I believe the tutor plugin should remain bundled with Vim. If any issues arise, we can address them. Regards, Yegappan

[brianhuster]

newcomers go to neovim anyway so I would go for our oldschool vimtutor being the a vim thing.

Not makes sense to me, given that vimtutor is also for newcomers. If all newcomers go to Neovim, then the existence of vimtutor would also be worthless.

While Neovim shines for people who want a development environment in the terminal, Vim still has its place. There are people who just needs a TUI editor to edit config files anyway, in which case they don't need Neovim but just a preinstalled Vim in their system.

[brianhuster]

If any issues arise, we can address them.

@yegappan I list some issues with that plugin and my preferred solution in a Neovim issue, hope you can give some opinions about it. If you are OK with it, I could send a PR to Vim first

[dlejay]

This PR does not propose to combine the best qualities of the old tutor and the new tutor so that there is one good learning platform, but simply to remove the interactive tutor already implemented in the Vim infrastructure.

I am happy to work on a syntax file for the vimtutor, but first I need to know if the original tutor is here to stay (or if the future is the interactive tutor). Otherwise it makes no sense. The current syntax/tutor.vim is for the :Tutor.

While Neovim shines for people who want a development environment in the terminal, Vim still has its place. There are people who just needs a TUI editor to edit config files anyway, in which case they don't need Neovim but just a preinstalled Vim in their system.

Is that the common “vision” for the future of Vim ?

[brianhuster]

Is that the common “vision” for the future of Vim ?

No, it's just my personal opinion about its current situations. The future of Vim will depends on its future Pull Requests.

[dkearns]

Syntax highlighting is going to introduce some fragility as well. It may be better to use text properties if going down that path.

[brianhuster]

Btw, given that the :Tutor plugin cannot be shipped with vim-tiny, Vim will have to keep vimtutor anyway. So if there must be a tutor system removed, I think it must be the :Tutor plugin

[chrisbra]

which is what this PR is suggestions, right? Also I think syntax highlighting for the traditional tutor wouldn't also work in tiny Vim.

[dlejay]

Well, a beginner learning Vim through the vimtutor on vim-tiny is highly unlikely.

[lilydjwg]

Well, a beginner learning Vim through the vimtutor on vim-tiny is highly unlikely.

Not very unlikely, considering some Linux distributions ship a vim-tiny by default. Surely the user is highly unlikely to want to learn with vim-tiny but a beginner may not realize that they have a tiny version of Vim. Perhaps a warning or error could be given instead.

[brianhuster]

Perhaps a warning or error could be given instead.

Why? Is there any feature taught in vimtutor not included in vim-tiny?

[lilydjwg]

Perhaps a warning or error could be given instead.

Why? Is there any feature taught in vimtutor not included in vim-tiny?

A beginner might find they have vim-tiny installed on the system and not realize that Vim has a lot of different build options (unlike most modern software). They might be confused that their Vim doesn't work as expected, only after some time they know the existence of the vim-nox or vim-gtk package. The tutor is a good place to clarify this.

[brianhuster]

A beginner might find they have vim-tiny installed on the system and not realize that Vim has a lot of different build options (unlike most modern software). They might be confused that their Vim doesn't work as expected, only after some time they know the existence of the vim-nox or vim-gtk package. The tutor is a good place to clarify this.

Then your comment is not related to this PR

[dlejay]

Not very unlikely, considering some Linux distributions ship a vim-tiny by default. Surely the user is highly unlikely to want to learn with vim-tiny but a beginner may not realize that they have a tiny version of Vim.

Are there any Linux distro that are both beginner-oriented and ship with vim-tiny by default ?

[dlejay]

It’s been 3 weeks without new comments. How do we move on ?

In my opinion, the only bad outcome would be : “let’s keep both just because we can”.

[brianhuster]

Note that the new tutor plugin is so fragile (hence really confusing to beginners) that I sent some patches to Neovim to rewrite it using extended marks (similar to Vim's text properties). So if Vim really wants to keep it, someone will need to rewrite it with text properties. Otherwise, removing it and make vimtutor more friendly with syntax highlighting, etc, is still a good idea.

[benknoble]

It’s been 3 weeks without new comments. How do we move on ?

In my opinion, the only bad outcome would be : “let’s keep both just because we can”.

I think the answer to this question is in the PR and discussion. My personal summary from a quick skim:

• there's good reason to keep both, at least for now;
• the old tutor could benefit from syntax highlighting, possibly via text properties to avoid fragility, and this will need to be optional (for vim-tiny);
• the old tutor could use updates with current Vim material (but may need to call out where such current material depends on newer (stable?) Vim versions or larger-than-tiny builds?);
• the new tutor could benefit from some fixes to highlighting (text properties) and other issues highlighted in this thread.

Except for the first bullet, any of these would make a fine small project and PR the community can have productive conversation about, I would think.

[dlejay]

there's good reason to keep both, at least for now;

I have troubles understanding what are the good reasons, could you help me ?

[chrisbra]

I am sorry, I don't plan to remove the interactive tutor right now. So I'll close this as not planned (at least for now).

[dlejay]

Thanks for taking the time to consider this proposal.
I understand why you’re closing this PR.

Best.