[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).

[ghost]

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 ;)

[ghost]

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.

[lervag]

Imaps are pretty cool, too?

Definitely, although I rarely use them myself. Heh.

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).

I agree, citation completion is a very nice core feature! What you refer to requires the "barebones" omnicompletion, though, and does not tend to work so well with autocomplete plugins. I.e., type \cite{SOMETHING<c-x><c-o> will by default complete anything where a citation string that includes the author or title matches. See :help vimtex-complete-cites for more info (I guess you know this, but other readers may not be aware of it).

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.

I think it is best if you can have the \section{Compiling} be the very top line, similar to the other "sections" in the videos.

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.

Yes, good point. A screenshot is probably better for showing the syntax highlighting. Probably we should use two screenshots to also show the conceals, as that seems to be popular.

... 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: ...

Very good; thanks! I also think it can be good to state in the README which colorscheme is used (possibly with links and specifications of modifications).

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.

Great. The final question is then how small can we make such gifs while still keeping the frames at decent quality. The current quick_start.gif is about 380 kb. I would prefer to not increase by much.

[ghost]

Great. The final question is then how small can we make such gifs while still keeping the frames at decent quality. The current quick_start.gif is about 380 kb. I would prefer to not increase by much.

On second thought, gif is not a good format for videos when it comes to file size. I converted one of the mov files with ffmpeg to h265 lowering the resolution and compressing a bit, ultimately reducing the size from ~7mb to 418kb with I hope not too much a loss in quality. See below.

s2v2.mp4

[lervag]

I think you're right about gifs and file formats, but it seems the mp4 file can not be displayed on github. I don't mind using other formats, as long as they work as expected in a README file.

Note: I just realized it may be possible to "cheat". I.e., perhaps we don't have to add the gifs/movie files to the repo, but instead add links from the README file to files uploaded in an issue post? That way, people will not need to download large files.

[clason]

Another "cheat" I've sometimes seen is to have the images and movies live in a separate media repo and link them from there; this also allows changing them more often without adding churn to the main repo.

[ghost]

I think you're right about gifs and file formats, but it seems the mp4 file can not be displayed on github. I don't mind using other formats, as long as they work as expected in a README file.

Note: I just realized it may be possible to "cheat". I.e., perhaps we don't have to add the gifs/movie files to the repo, but instead add links from the README file to files uploaded in an issue post? That way, people will not need to download large files.

I just gave it a try and it seems that it can. See here: https://github.com/DustyTopology/mp4. What I've just discovered is that it does not actually upload the video to the repo, the video is hosted elsewhere like and only a link is added to the READme. So, this means file size should not be an issue!

[lervag]

Storing media files in a separate repo actually sounds like a good idea. But using the user-images.githubusercontent.com also seems like a possibility.

In any case, we're partly off topic. @DustyTopology Let me know when you have updated videos, then we can figure out how to add them to the README after we've agreed on a version.

Btw, I still can't see the video you're linking. It looks like this on my end:

[ghost]

Ok getting back on track. Here is screencast version 2:

Screencast.mp4

Edit: New video. Had statusline plugin on in previous video.

And example syntax screenshot:

Colour scheme used is https://github.com/arzg/vim-colors-xcode with the following modifications:

" VimTeX highlight groups
hi texCmd guifg=#ad3da4 guibg=NONE gui=NONE ctermfg=127 ctermbg=NONE cterm=NONE
hi! link texMathEnvArgName texEnvArgName
hi! link texMathZone LocalIdent
hi! link texMathZoneEnv texMathZone
hi! link texMathZoneEnvStarred texMathZone
hi! link texMathZoneX texMathZone
hi! link texMathZoneXX texMathZone
hi! link texMathZoneEnsured texMathZone

" Small tweaks
hi! link QuickFixLine Normal
hi! link qfLineNr Normal
hi! link EndOfBuffer LineNr
hi! link Conceal LocalIdent

[lervag]

Thank you, I think this is very good, and I would be very happy to add this to the README file and remove the old gif. My gut feeling is that the best approach is to make a new repo "vimtex-media" where the images, gifs and/or videos are added, then link to them from the README file. I can do this, but I'll first leave a couple more days to allow more comments.

One more thing: I think the tex file you use in the video may also be very useful as a better quick introduction in itself. Perhaps it should be added to the repo with a link to allow people to read it and test on their own? I.e., we could add a link to the file in the quick start section and encourage people to download that tex file to read and interactively test VimTeX?

[ghost]

Thank you, I think this is very good, and I would be very happy to add this to the README file and remove the old gif.

Thank you!

My gut feeling is that the best approach is to make a new repo "vimtex-media" where the images, gifs and/or videos are added, then link to them from the README file. I can do this, but I'll first leave a couple more days to allow more comments.

I think this is the best solution in the long term.

One more thing: I think the tex file you use in the video may also be very useful as a better quick introduction in itself. Perhaps it should be added to the repo with a link to allow people to read it and test on their own? I.e., we could add a link to the file in the quick start section and encourage people to download that tex file to read and interactively test VimTeX?

That sounds like a great idea. How should I send it to you?

I noticed a typo in the previous video, so here's (hopefully) the final take:

Screencast.mp4

[lervag]

My gut feeling is that the best approach is to make a new repo "vimtex-media" where the images, gifs and/or videos are added, ...

I think this is the best solution in the long term.

https://github.com/lervag/vimtex-media/

One more thing: I think the tex file you use in the video may also be very useful as a better quick introduction in itself. ...

That sounds like a great idea. How should I send it to you?

Feel free to send it by email. My email addres is splattered across the repo. Or, you could also send it by PR (this would also rightly attribute the contribution to you). In such a PR you could also help add the improved media files. I've started, but changing the main gif/video will also require some minor update to the text.

This example file is probably so small that I think the best place to add it is to the test/ folder, e.g. replace the test/example-quick-start/main.tex.

I noticed a typo in the previous video, so here's (hopefully) the final take:
Screencast.mp4

Great, thanks! The final question now is how to add these things. That is, either you send things to me (e.g. email) and I'll make the changes, or you can submit these contributions by PR. As described above. The media files can be contributed on the vimtex-media repo and should be added there first. Then, when these are available, then we'll update the README file.

[ghost]

Great, thanks! The final question now is how to add these things. That is, either you send things to me (e.g. email) and I'll make the changes, or you can submit these contributions by PR. As described above. The media files can be contributed on the vimtex-media repo and should be added there first. Then, when these are available, then we'll update the README file.

I'll send a pull request to the media repository to start.

[lervag]

Great, thanks!

[lervag]

I believe, with the improved quick start video and the tex example with the guide text, that this issue can be considered resolved. Agreed?

[ghost]

Yes, agreed.

[lervag]

Hmm. It seems like it is not possible to add the mp4 to the README. I tested both the ![](url) syntax and the more straightforward URL syntax. It may be that the mp4 feature only works with githubusercontent type links?

[lervag]

Ok, so: It works when I use the link to mp4 file from your issue post. The https://user-images.githubusercontent.com link. But with raw.githubusercontent.com/lervag/vimtex-media and github.com/lervag/vimtex-media links it does not work. I'm not sure exactly how to conclude this. Perhaps just accept the link to the issue posted file (and add a reference to the issue)?

[ghost]

Hmm. It seems like it is not possible to add the mp4 to the README. I tested both the syntax and the more straightforward URL syntax. It may be that the mp4 feature only works with githubusercontent type links?

What worked for me was to open the README on Github and drag and drop (or paste) the video in there.

Ok, so: It works when I use the link to mp4 file from your issue post. The https://user-images.githubusercontent.com link. But with raw.githubusercontent.com/lervag/vimtex-media and github.com/lervag/vimtex-media links it does not work. I'm not sure exactly how to conclude this. Perhaps just accept the link to the issue posted file (and add a reference to the issue)?

Go right ahead; that is fine with me.

[clason]

It should work with raw.githubusercontent.com -- you can look at https://raw.githubusercontent.com/tjdevries/colorbuddy.nvim/master/README.md for an example.

[lervag]

What worked for me was to open the README on Github and drag and drop (or paste) the video in there.

That will upload the video to Githubs user content store again, which is unnecessary since it is already uploaded. I believe (perhaps theres a duplicate content check to avoid redundancy).

It should work with raw.githubusercontent.com -- you can look at https://raw.githubusercontent.com/tjdevries/colorbuddy.nvim/master/README.md for an example.

Well, I tested it. I tried adding the following link:

https://raw.githubusercontent.com/lervag/vimtex-media/main/video/quick-start.mp4

It did not work (and I expect it will not work in this issue either). But the link is correct. Still, I'll be glad to be proven wrong.

So, it remains to add the quick-start example tex file with a link from the README.

[clason]

Ah, probably movies are different from (animated) images, then. Sorry!

[clason]

(But notice that the link is different there -- it points to a specific blob, not the web link.)

(So just to make sure: you tried https://github.com/lervag/vimtex-media/blob/main/video/quick-start.mp4?raw=true?)

[ghost]

Alternatively, we could go back to the original idea and post them as gifs. The file size will like increase quite a bit, but that may not be a concern if we put it in the media repository. Or make the increase moderate but at the cost of a decrease in quality.

[lervag]

Alternatively, we could go back to the original idea and post them as gifs. The file size will like increase quite a bit, but that may not be a concern if we put it in the media repository. Or make the increase moderate but at the cost of a decrease in quality.

I think the movie format is actually quite nice, because it makes it easy to play/pause/rewind. So let's keep it like this. Unless, of course, you all disagree..?

So just to make sure: you tried https://github.com/lervag/vimtex-media/blob/main/video/quick-start.mp4?raw=true?

Yes. I've tried each of these, and as you can see in the following, only the final link works.

https://github.com/lervag/vimtex-media/blob/main/video/quick-start.mp4

https://github.com/lervag/vimtex-media/blob/main/video/quick-start.mp4?raw=true

https://raw.githubusercontent.com/lervag/vimtex-media/main/video/quick-start.mp4

https://raw.githubusercontent.com/lervag/vimtex-media/a3731e12ea564f1d2560b5d29ef8e6b73faf4e5b/video/quick-start.mp4

https://user-images.githubusercontent.com/lervag/vimtex-media/main/video/quick-start.mp4

https://user-images.githubusercontent.com/66584581/119213849-1b7d4080-ba77-11eb-8a31-7ff7b9a4a020.mp4 - correctly displays as:

Screencast.mp4

Let me know if there are other ways to write a link that may work. If possible, I would prefer to use a link to a fully controlled destination. But in the end, I won't really mind linking to the user-images uploaded files. So I'll not spend much more energy on this.

[lervag]

By the way: interesting to note that the previously linked blog post was on hacker news today.

[lervag]

Ah, sorry - that link was referenced in the PR thread in vimtex-media.

[lervag]

I've now added the new quick start file as well. Please look at the current README and let me know what you think.

I'm closing now, but please feel free to continue the discussion.

[ghost]

I think it looks great!