Vimtex: Document a getting started guide

[tdi]

This is an enhancement request.

I think that a getting started paragraph, or a typical use case, in the README.md would be in order. Also, subparagraphs documenting some basic but crucial use cases, animated gifs?

I think that at least there should be an explanation how to build the document. Now, in order to build I just execute :VimtexCompile upon vim startup and latexmk continuous build start. I do not feel though it is an intended way to use the plugin.

[nasenatmer]

Maybe a Quick Start section would do. Sth like

1. Open a given .tex document
2. Press \ll to start compilation. A viewer window will appear
3. Press \ll to stop compilation.
4. If you want to checkout any errors, press \le
5. If you want to clean auxiliary files, press \lc

Like this?

[tdi]

Exactly, now I could not find any of this anywhere. I can prepare an animated gif if it is in place.

[lervag]

Thanks for the suggestion. I think you might be right, that this is in order. Perhaps it would be better to add this to the wiki? I could add a link to the wiki from the README file?

[tdi]

I would add a quickstart as @nasenatmer suggested to the main README.md, maybe just after the Installation section.

[lervag]

Ok. I'll do it later when I have the time. (As you probably understand from the increasing number of issues, I unfortunately don't have that much time right now, but I hope to get back on top of the issues in not too long.)

[tdi]

@nasenatmer can you provide PR or should I ? @lervag can then just merge.

[nasenatmer]

@tdi I'm not exactly good at making PR requests, so if you have a suggestion, please do so!

[lervag]

I've added a simple quick start text based on your suggestions. I could probably also add a simple gif that showcases the steps. But to do that, I need to know how to make such gifs/screencasts. Any suggestions on that?

[lervag]

Ok, I've created my first recording of a terminal session. It is not perfect, e.g. for some reason it makes it look like starting/stopping compilation creates a huge glitch. But I think it is getting close to something useful.

I would be happy to get some feedback, tips/ideas for improvements, and/or suggestions for tools that may give better recording results. I now used tty2gif.

[tdi]

@lervag If you use OSX then you can try LICEcap tool to record gifs. There is also https://asciinema.org/, a neat tool to record on linux and osx.

[lervag]

I'm on Linux. I've tried asciinema, but I don't really like the results. Both asciinema, tty2gif, and ttyrec seem to enhance the minor glitches when vim runs system commands.

I guess the current version is OK?

[tdi]

It is ok but the problem is that we do not see keys pressed. So really without the guide as suggested by @nasenatmer it gives nothing to a user.

[lervag]

Yes, I don't know how to make the keypresses show up. If someone could point me to a good tool that could record both the keypresses and the (relevant part of) the screen, then that would probably help.

[tdi]

@lervag https://github.com/KeyboardFire/mkcast maybe this will be ok

[lervag]

Thanks for the tip. I couldn't get it to work, though. Nor the other one, xscast.

I've tried to use recordMyDesktop combined with screenkey now, which seems to make OK videos. However, I can't find a good method to convert the video to gif. The gif file becomes huge. :

[ferdinandyb]

I found this issue when trying to find a vimtex screencast for my blog. I ended up making my own, but thought I'd share the process. I used kazam and screenkey to make an mp4 and then this script I found some time ago to convert the mp4 to a gif. Here's what the output looks like. The mp4 was around 15.5 Mb and the gif is roughly half. Not super small but manageable, although I could've downscaled the width, so could've been smaller ... The context was not for latex experts, so the screencast is not very, khm, comprehensive :)

[lervag]

I found this issue when trying to find a vimtex screencast for my blog. I ended up making my own, but thought I'd share the process. I used kazam and screenkey to make an mp4 and then this script I found some time ago to convert the mp4 to a gif. Here's what the output looks like. The mp4 was around 15.5 Mb and the gif is roughly half. Not super small but manageable, although I could've downscaled the width, so could've been smaller ... The context was not for latex experts, so the screencast is not very, khm, comprehensive :)

Thanks for the tips! I think you're blog post looks quite good and well thought out. I was not aware of screenkey, which will be useful! Kazam also looks nice. I've tested asciinema and menyoki and have not really decided what I like best so far.

To avoid further kidnapping this thread, I'll lock the issue. Feel free to continue the discussion on e.g. Gitter.