Contribute visual examples of VimTeX's motions and text-editing mappings #2362
Conversation
Changes - Link the series's "Getting started with the VimTeX plugin" article in the Quick Start. - Inconsequential rewording of introduction to DustyTopology's video, just to make things a little more concise (I think without losing information).
@lervag---based on email exchange, folding and formatting are disabled by default. I have updated the README accordingly.
Reasoning: It feels sensible to have a dedicated file for GIFs (and perhaps other media content pending future contributions) instead of flooding the main README with images and videos. This is currently a very bare-bones file, listing all the GIFs I have available in the order the corresponding VimTeX features appear in `:help vimtex-features`. Since the order in both files matches up, I'm currently imagining a new user might simultaneously scroll through this file while reading `:help vimtex-features` and thus get a better image than either file along could provide. Note: I see that `github.com/lervag/vimtex-media` already exists. I have temporarily created my own `github.com/ejmastnak/vimtex-media`, since I see the content of `github.com/lervag/vimtex-media` is MIT-licensed, and I had already released the GIFs I made under a CC-BY-NC-SA (sigh). I imagine we can work this out easily (I'm not one for splitting hairs over licenses), but I did want to wait for input before making a committal decision of my own. I do feel that a CC license would be more appropriate for media (MIT is for code, no?), but that might(?) require `@DustyTopology`'s consent, and I think his GitHub account is deleted. Eh, we'll figure something out.
Two changes - Updated section name from "Screenshots" to "Screenshots and GIFs" and updated TOC accordingly. - The aforementioned link to VISUALS.md from the "Screenshots and GIFs" sections of the README.
Had left a commented-out TODO, but on second thought it's clearly not the best idea to pollute the main README with commented-out notes-to-self.
|
I'm realizing I was a bit noisy with the large number of commits here and we will probably want to rebase this, but I leave that to the discretion of the higher authorities. |
| @@ -0,0 +1,183 @@ | |||
| # VimTeX Visualized | |||
There was a problem hiding this comment.
This is excellent! I like the title :)
One thing, though: I don't feel quite "up to the task" of maintaining this particular file. In case there are changes or new features that someone wants "visualized", then I would need community help to update. Perhaps that should be clarified here?
There was a problem hiding this comment.
Agreed. If you have an idea about phrasing this disclaimer/notice-to-the-community, please go ahead. I am also happy to take responsibility for helping maintain this file, just not sure how that would work in practice.
Thanks! I believe this is a very good improvement of the informal documentation! I've added a few comments to the files, nothing big. Apart from that, I hope you don't mind if I adjust the wording after merging. In particular, I want to update the quick start part to make it more "logically" structured. But I think it is better that I do it afterwards, then you could read it and comment (if desired).
Very good! I would also recommend that you publish the article (or series) elsewhere. Your content is good and deserves an audience!
Thanks for noticing and fixing that!
Ah, yes. Licensing. To be honest, I don't care so much about the licensing. That is, in the sense that I don't mind what anyone does with whatever I share. That's why I've used the MIT license. However, I respect other peoples concern for licensing, and I don't want to force the MIT license here. The point here is to conserve the rights of the third-party content creators. I would therefore not mind changing to the stricter CC-BY-NC-SA for
Yes, I can see this is tricky. And I agree that there are not really that much content available that is suitable for a link here. So I think it is perfectly fine that we now only add the link to your guide.
No worries. I don't really mind the number of commits. But you can of course feel free to clean up before merge if you want to. |
Please go ahead, I have no reservations about this.
Sounds good. I'll add a short introduction of my series to the README as you suggested in our email exchange, and then you can reword it or rearrange its position if needed, similar to how you will tweak the Quick Start section.
If you are willing to change vimtex-media to a CC license that would be great---I do feel a CC would be more appropriate for media. I decided to change ejmastnak/vimtex-media to the (slightly) more permissive BY-NC, which at least permits sub-licensing remixed works, and in fact wouldn't mind lowering this further to the very permissive CC-BY, which is roughly a CC equivalent of MIT (allowing essentially arbitrary use as long as copyright/attribution is given). I lean towards non-commercial since I support free sharing of content, but I recognize forcing this on a few GIFs may just be idealism. Let me know if you would prefer CC-BY. I don't mind too much one way or the other here, my only preference could be a CC license for non-software content.
@DustyTopology's GitHub account seems to be deleted, so I don't know if it is possible to contact him. I imagine switching from MIT to CC-BY should be fine. If we instead stick with BY-NC, which revokes MIT's commercial use clause, one possible solution is to use two directories, one with each license (although this is less clean and risks future clutter). |
[@lervag](https://github.com/lervag), please feel free to update this at your discretion. The main point I wanted to make is that I am happy to commit to maintaining this page and am the person to contact in the event of mistakes/changes.
Consider this the first draft of a section for third-party VimTeX guides on the larger Web. As we discussed earlier, [@lervag](https://github.com/lervag), I have (1) referenced and briefly described my series and (2) invited the VimTeX community to contribute other (good-quality) third-party content. As in commit 58e704a, feel free to edit this section as you see fit.
|
I have pushed a few more commits that should resolve the following: [On maintaining VISUALS.md]
Addressed in 58e704a [On third-party guides]
Addressed in 6429f84 In both cases, consider the commits a first draft, just to put ideas on the table, and feel free to edit as you see fit. |
Great!
Yes, agreed. Let's move to CC BY-NC. If anyone has commercial interests, they could always contact owners directly.
You're right, his account is deleted, and I do not have any of his contact details. The repository is mine, this discussion is public, so I believe there should be no problem in just changing the license. I propose that you make the change of license a part of your future PR to vimtex-media? Regarding your recent updates: It looks good. I'll merge when I have the time and then make some adjustments. These will most likely all be minor. One minor comment, though: I really don't like when a branch pulls in master in a merge. Instead, I much prefer to have branches rebased on top of master before I merge. That way, it is much easier to inspect the changes brought by any given branch. I can manually fix this myself when I merge, unless you want to fix it yourself. If so, you would have to do a |
Ah, beginner mistake, apologies. Thank you for pointing this out, this is actually my first contribution to an open source project, and I will know for next time.
Given my current lack of experience, I think it best that you fix this yourself this time. In the meantime, I will read up on rebasing. I imagine the Git Book would be the standard place to start, but if you know of good references for this workflow I will definitely read through them! |
|
Two updates:
|
|
Sorry for the late reply. Started a new job this week and have slightly too much on my mind. :p
No problem! Some people don't mind this at all, I may be somewhat strict in this regard. I don't know. But I guess it's one of the benefits of being the main developer of something :)
Sounds good! Here are some good Git references that may be useful/of help. Note that there may possibly be better guides available today that I'm not aware of. However, I believe they should still be relevant and good.
Great, thanks!
Sounds good! We'll merge vimtex-media first. |
|
So, to summarize my actions here:
Please let me know if it seems I missed something! |
No problem at all, good luck with the transition!
Thank you! I appreciate the effort you made to put together a thorough list of references. |
I took another look through vimtex-media and my fork of vimtex, and everything looks good. Please go ahead! |
|
Ok, I've done the merge. I did these steps, in case you're curious: # Check out the PR (use Github CLI)
gh pr checkout 2362
# Check out the PR branch and make a temporary branch while rebasing, in case
# I should do something wrong.
git checkout ejmastnak/master
git checkout -b fixup
# The problematic commits were 3a3ce56d and a977f6b4; we want to rebase the
# commits after a977 onto the commit before the merge, i.e. 58e704a7. We do it
# like this:
git rebase --onto 58e704a7 a977f6b4 fixup
# Now we have a clean branch that does not entangle with master. Before merge,
# we rebase onto master.
git rebase master
# Finalize merge
git checkout master
git merge --no-ff fixupThe final commit graph thus looks like this: |
Thanks! :)
No problem. Glad to help! And finally, thanks for the very useful contribution to the project! |
|
FYI: I made a few minor adjustments to the text. The most noticable was to move your new paragraph under quick start below the video. The reasoning was that I feel it makes more sense to promote the video since it is more "quick", whereas your article does take some more time for anyone to read and study. So, we now first show a short video intro, then encourage your excellent guide, then finally stresses that people should read the docs. Let me know if you think any of my changes are regressions! Edit: My changes are introduced in this commit: 882641b |
Thanks for sharing this! Doesn't look too difficult at all---I'll be ready to do it myself next time if need be.
Yes, the progression from the "quick" video to the somewhat longer guide to the official docs, which are the most comprehensive, makes perfect sense to me. So I fully agree with all changes in 882641b.
You're very welcome, I'm glad it could help. Thank you for the excellent plugin! |
This PR is motivated by #1946 and adds GIFs demonstrating most of VimTeX's motions and delete/change/toggle key mappings, i.e. most of mappings in
:help vimtex-mappings.Summary of changes:
VISUALS.mdfile (currently in the project root; could also be moved todoc/) holding the aforementioned GIFs and concise accompanying descriptions.README.mdto "Screenshots and GIFs" (TOC updated accordingly) and linked toVISUALS.mdfrom the new "Screenshots and GIFs" section of the README.README.mdto my third-partyarticle Getting started with the VimTeX plugin, as per our email exchange,
@lervag.README.mdchanging "All features are enabled by default" to "Most features are enabled by default" and noting the disabled folding and formatting features (see c8e441a).Notes:
The GIFs in
VISUALS.mdare currently stored in github.com/ejmastnak/vimtex-media---we will probably want to move these to github.com/lervag/vimtex-media, but please first see the comments at the end of 2c57a48.@lervag, we had discussed adding a section on third-party guides to the main README.I looked into content I could find online, but didn't find anything particularly captivating (mostly outdated summaries of setting up inverse search before the days of
VimtexInverseSearchor nice but not terribly comprehensive summaries of standard commands/mappings which I'm not sure add much beyond what the main docs already offer).Although you have endorsed it, personally adding only my own series to a third-party section feels too much like self-promotion, so I defer to you on this one.