[Help wanted] Better visual examples in README file

[lervag]

The current README file has a simple "Quick Start" section with a very simple screencast/visual example. In the discussion in #1903 it was suggested that this can be improved, and I very much agree. However, I have realized that this is not something I am very capable of doing. That is, I've looked into it, but I never feel satisfied with the results of my more advanced screencasts.

I would find it very useful if someone in the community could help me. Possible actions:

• create a better quick start section altogether (suggest inline or with PR)
• create screencasts that might replace the current one (or we can have more than one)
• anything similar/related

Suggestions and comments are of course also welcome!

[LambdaP]

Hi. I don’t know anything about screencasts and consider myself too clumsy to do such a thing properly.

However, I’m a decent writer, and I’d love to help with the documentation, the README, and related files. Let’s chat.

[lervag]

However, I’m a decent writer, and I’d love to help with the documentation, the README, and related files. Let’s chat.

Great! I'm unfortunately quite sporadically available at these times. I think that, in general, the README and docs are quite good. However, There is definitely room for improvement. Especially, I think, with regard to introducing the features and guiding newcomers. That is, Vimtex has become quite large with very many features, and so the documentation is also very large. This makes it impossible for most people to actually read all of it. So I think the docs should be considered a reference, but I want people to at least read the introduction. But the introduction is still not quite "good enough", in the sense that it does not provide a good introduction to the main features.

I try to avoid too much redundancy between the README and the main docs. I think the README should be a minimal introduction that explains what Vimtex is, then refer to the docs for more info. The docs should be improved with a better "getting started" section or "quick start" that introduces the main features in a simple and accessible manner. To summarize, I think this last part is now what is mainly missing. And I would be very happy to get help on this part.

[LambdaP]

Thanks for the explainer, I can work with that. I also think that the documentation in vimtex.txt is quite good.

Regarding the large number of features that Vimtex has nowadays, have you considered moving some away into separate plugins? You seem to have done that already with wiki.vim and the syntax plugin. Might it help to fight the complexity? :-)

[lervag]

Regarding the large number of features that Vimtex has nowadays, have you considered moving some away into separate plugins? You seem to have done that already with wiki.vim and the syntax plugin. Might it help to fight the complexity? :-)

Yes and no. This is a complicated question. I've implemented some quite general features (e.g. UI, path handling, position handling, etc) that probably would be very suitable for a more utility like "library" plugin. I also know there are some advocates for this (see e.g. lh-vim-lib), and I can easily see benefits of modularising the code into more atomic libraries and smaller plugins. However, I think most people don't like the idea of a dependency based plugin ecosystem; myself included. If people in general used a plugin manager that handled dependencies (I think this does exist, but I don't quite remember and I don't use one myself), then it would be easier.

My conclusion is to avoid dependencies. So, then it remains to ask if there are specific features in VimTeX that are really more general and could be its own plugin. And perhaps there are, but I am not quite aware of it now. If you are thinking of something specific, please feel free to raise discussions about that (preferably in a new thread so we can keep this one back on topic).

Here's my attempt at a screencast. The first shows the default keybindings regarding compiling and errors and so on:

Screencast.1.mov

The second shows some the table of contents window and example motions, text objects, mappings:

Screencast.2.mov

The ToC window is a seriously cool feature, so I feel I had to include it.

[lervag]

Here's my attempt at a screencast.

Great, thanks! I hope you don't mind a couple of comments/suggestions.

The first shows the default keybindings regarding compiling and errors and so on:
Screencast.1.mov

This clearly replaces the current screencast, and I think it is already better than my own versions! Well done!

• Would the cast look better if you hide the preamble at the start? I understand why it is necessary to define the commands, but I believe the "story" would be less cluttered if the initial "page" only displays from \section{Compiling}.
• To also show off some more of the colorscheme, perhaps you could put some of the content inside an itemize or enumerate environment? Or, perhaps a better alternative: add a new section to the second video to display some of the syntax highlighting (I could help with some examples, if you want).
• I'm curious, which colorscheme are you using? It looks OK to me, except for the quickfix window: the white on blue colors do not feel optimal, IMHO. Not a big deal, so if you disagree, then I won't make a big issue of it.

The second shows some the table of contents window and example motions, text objects, mappings:
Screencast.2.mov
The ToC window is a seriously cool feature, so I feel I had to include it.

• Perhaps you could also show tsd; I find I use it quite a lot, so perhaps it would make it more well known?
• In the final sentence: It should be :h, not h:. :)

[lervag]

One question: Are you able to convert these to a format that works well on a github readme file? The .mov might be suitable already? It looks crisp, better than the current gif file. But I worry about the file size.

@clason Feel free to add your comments here, if you have any.

[clason]

I use tse more often :)

(My color scheme is dark, but has a lot of vimtex-specific highlights: https://gist.github.com/clason/f62c9849c2e634f314c546f2e8b0585b)

Imaps are pretty cool, too?

And one thing that would be more difficult to show off but is a game-changer for me is fuzzy matching in omnicomplete (for example, \cite{<part of author name> will complete even if the author name is not part of the bib key -- same for the title).

[clason]

And, yes, huge animation in the plugin repo that I have to download would be... less than ideal ;)

Great, thanks! I hope you don't mind a couple of comments/suggestions.

Any time!

Would the cast look better if you hide the preamble at the start? I understand why it is necessary to define the commands, but I believe the "story" would be less cluttered if the initial "page" only displays from
\section{Compiling}.

I agree, it would look better if I hid the preamble. The reason I left it in was to show \begin{document}. I could, like you suggested, start the screencast at \section{Compiling} or I could fold away the preamble (not including \begin{document}) and perhaps completely hide the fold by changing the syntax highlighting.

To also show off some more of the colorscheme, perhaps you could put some of the content inside an itemize or enumerate environment? Or, perhaps a better alternative: add a new section to the second video to display some of the syntax highlighting (I could help with some examples, if you want).

I think adding a section showing some of the syntax highlighting would be a good idea. This would also be a good place to mention that VimTeX overrides the builtin tex highlight groups with more flexible ones. Alternatively, we could just put a screenshot in the README showing the syntax highlighting instead of a gif.

I'm curious, which colorscheme are you using? It looks OK to me, except for the quickfix window: the white on blue colors do not feel optimal, IMHO. Not a big deal, so if you disagree, then I won't make a big issue of it.

The colour scheme is essentially https://github.com/arzg/vim-colors-xcode but I've been tweaking it over time. The blue doesn't really bother me, but I don't mind changing it. I think it would be a good idea to have more than one error in the QuickFix menu. How's this:

Perhaps you could also show tsd; I find I use it quite a lot, so perhaps it would make it more well known?

Sure. I've tried to keep the videos short, but I think there is still room for more features.

In the final sentence: It should be :h, not h:. :)

Heh, oops :^)

One question: Are you able to convert these to a format that works well on a github readme file? The .mov might be suitable already? It looks crisp, better than the current gif file. But I worry about the file size.

I made these with the intent that if they were to be included in the README, then it would as gifs. This is why I have kept them short; gifs don't come with video controls, so if someone misses something then they have to wait for the whole thing to start over from the beginning.