Select mode is not implemented

[pafcu]

Select mode is not implemented yet

[raindev]

You've meant visual mode, right? So, this problems is related to the issue?

$ python3 vimsplain.py 2V
Traceback (most recent call last):
  File "vimsplain.py", line 318, in <module>
    matched, explanation, instr, state = parse(instr, commands, state)
  File "vimsplain.py", line 173, in parse
    raise ValueError
ValueError

[pafcu]

I think this is an excellent example of why it's a good idea to be a bit verbose when describing bugs, even when you know the issue perfectly well yourself.

To be honest, it's been 4 years since I looked at the code: I don't know what I meant anymore :-)
Visual mode is implemented, so probably it's not that.

I suspect the issue is that the vim help index does not mention that you can have a number in front of the "v" command, so the parser gets confused when there is one there anyway. "vimsplain.py 2u" doesn't work either because the documentation does not mention that it's possible to do something like that.

[raindev]

I think this is an excellent example of why it's a good idea to be a bit verbose when describing bugs, even when you know the issue perfectly well yourself.

Yeah, great point ; )

I've also took into account that Vim help have no numerical prefix for this one command. Do you consider it useful to interpret such a uses of numbers in commands on your own, like adding "2x: " to the beginning of an explanation string, for example?

[pafcu]

If the words "N", "Nth" or "Nmove" appears in the explanation, vimsplain will understand that the command takes a number in front of it (because this is how it's usually indicated in the docs). So the solution would be to change the description of the v command to read e.g. "start characterwise Visual mode start select the same number of characters or lines as used for the last Visual operation, but at the current cursor position, multiplied by N."

After this change, vimsplain 2v should work. You'd have to do the same for the V command as well, of course.

I suggest filing a bug against the vim documentation to include this information. If that's not possible, feel free to change index.txt in this project, and submit a pull request. But really, the ideal would be to have it in the main vim docs.

[raindev]

Naturally, most Vim commands support multiple applications by using numeric prefix. Given this I'm not sure if it's right approach to mention it explicitly for every command in the index.

It seems, there're no single approach for repeating commands taken in index.txt. Besides problems with v and V, u is also out of luck. I've tweaked index a little bit for this three particular command in the PR, but hadn't searched the whole file for similar issues.

[pafcu]

Sure, the vim index is not that great. That's why I think it may be good to try to improve the situation in vim itself. Alternatively, I suppose it would be possible to parse the full documentation for each command, because there it is specified whether a command takes a count or not.

One possibility would be to accept counts in front of any command. This would lead to some incorrect sequences being accepted, but that might be better than crashing. It also wouldn't give you a full explanation of what's going on either for valid commands, since vimsplain wouldn't be able to say what effect the count has.

[raindev]

Yeah, the best way would be to improve Vim index itself. Maybe, I'll have time to do that.

Full documentation is more precise than index in regards command counts. The problem I see with an option to use it for Vimsplain explanation is its verbosity comparing to the index. Too broad command descriptions would make Vimsplain less convenient, especially with long chain of commands.

Simply accepting numeric prefixes isn't feel right, I agree. However, there should be a better way to react to situations when count not allowed or not mentioned in the documentation.

[pafcu]

You are 100% right about the verbosity. But what could be done is to make a tool for preprocessing index.txt.
It would work as follows:

1. Read in the current index.txt
2. For each command there, look it up in the full docs. Check if it takes a count (usualy indicated by the presence of the word "[count]". If it takes a count, add the string "(N times)" to the end of the original description found in index.html.
3. Print out the corrected index.txt and use it with vimsplain.

This kind of tool could also be used to simply list the commands that need to be documented better, which would help with the documentation effort.

[pafcu]

@raindev Did you ever get around to working on this? I'm considering making a web interface to vimsplain, and it would be nice to have it behave correctly before that.

[raindev]

I haven't looked into the issue since than. Neither have I contacted Vim mailing list about the documentation inconsistencies. I don't think I would have time to attain the problem in the near future. Thank you for pinging me though. The idea to make a web version of vimsplain sounds great. Reminded me of http://explainshell.com/