diff --git a/README.md b/README.md index 8a50649d3f..cbb6ab05bf 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,14 @@ filetype and syntax plugin for LaTeX files. - [Installation](#installation) - [Configuration](#configuration) - [Quick Start](#quick-start) -- [Screenshots](#screenshots) +- [Screenshots and GIFs](#screenshots-and-gifs) - [Features](#features) - [Other relevant plugins](#other-relevant-plugins) - [Linting and syntax checking](#linting-and-syntax-checking) - [Snippets and templates](#snippets-and-templates) - [Tag navigation](#tag-navigation) - [Alternatives](#alternatives) +- [VimTeX on the Web](#vimtex-on-the-web) @@ -111,11 +112,15 @@ let maplocalleader = "," ## Quick Start -The following is a video guide for how to use VimTeX (credits: +An article covering VimTeX's core features, containing plenty of examples and +high-resolution animations intended to help new users ease into working with the +plugin, is available at the third-party link [Getting started with the VimTeX +plugin](https://ejmastnak.github.io/tutorials/vim-latex/vimtex.html). + +Additionally, the following video shows how to use VimTeX's main features (credits: [@DustyTopology](https://github.com/DustyTopology) from [#1946](https://github.com/lervag/vimtex/issues/1946#issuecomment-846345095)). -It displays some of the main features. The example LaTeX file used in the video -is available under +The example LaTeX file used in the video is available under [`test/example-quick-start/main.tex`](test/example-quick-start/main.tex) and it may be instructive to copy the file and play with it to learn some of these basic functions. @@ -132,7 +137,7 @@ supplementary documents: * [CONTRIBUTING.md](CONTRIBUTING.md) * [DOCUMENTATION.md](DOCUMENTATION.md) -## Screenshots +## Screenshots and GIFs Here is an example of the syntax highlighting provided by VimTeX. The example is made by @DustyTopology with the @@ -142,12 +147,17 @@ here](https://github.com/lervag/vimtex/issues/1946#issuecomment-843674951). ![Syntax example](https://github.com/lervag/vimtex-media/blob/main/img/syntax.png) +Additionally, you can find animated demonstrations of VimTeX's core motions, +text-editing commands, and text objects in the file [VISUALS.md](VISUALS.md). + ## Features Below is a list of features offered by VimTeX. The features are accessible as both commands and mappings. The mappings generally start with `l`, -but if desired one can disable default mappings to define custom mappings. All -features are enabled by default, but each feature may be disabled if desired. +but if desired one can disable default mappings to define custom mappings. +Nearly all features are enabled by default, but each feature may be disabled if +desired. The two exceptions are code folding and formating, which are disabled +by default and must be manually enabled. - Document compilation with [latexmk](http://users.phys.psu.edu/~collins/software/latexmk-jcc/), @@ -174,7 +184,7 @@ features are enabled by default, but each feature may be disabled if desired. - glossary entries - package and documentclass names based on available `.sty` and `.cls` files - Document navigation through - - table of content + - table of contents - table of labels - proper settings for `'include'`, `'includexpr'`, `'suffixesadd'` and `'define'`, which among other things @@ -221,6 +231,10 @@ features are enabled by default, but each feature may be disabled if desired. - [import](http://ctan.uib.no/macros/latex/contrib/import/import.pdf) - [subfiles](http://ctan.uib.no/macros/latex/contrib/subfiles/subfiles.pdf) +For orientation, you can watch concise demonstrations of many of the motions, +text objects, and text-editing features provided by VimTeX in the file +[VISUALS.md](VISUALS.md). + See the documentation for a thorough introduction to VimTeX (e.g. `:h vimtex`). ## Other relevant plugins @@ -297,3 +311,16 @@ plugins for Vim, see: * [What are the differences between LaTeX plugins](http://vi.stackexchange.com/questions/2047/what-are-the-differences-between-latex-plugins) * [List of LaTeX editors (not only Vim)](https://tex.stackexchange.com/questions/339/latex-editors-ides) +## VimTeX on the Web + +VimTeX users may be interested in reading +[@ejmastnak](https://github.com/ejmastnak)'s series on [Efficient LaTeX Using +(Neo)Vim](https://ejmastnak.github.io/tutorials/vim-latex/intro.html), which +covers all the fundamentals of setting up a VimTeX-based LaTeX workflow, +including usage of the VimTeX plugin, compilation, setting up forward and +inverse search with a PDF reader, and Vimscript tools for user-specific +customization. + +If you know of (or create) other up-to-date, high-quality guides to VimTeX's +features on third-party websites, feel free to submit a pull request updating +this section. diff --git a/VISUALS.md b/VISUALS.md new file mode 100644 index 0000000000..221f8adb29 --- /dev/null +++ b/VISUALS.md @@ -0,0 +1,196 @@ +# VimTeX Visualized + +This page contains animated GIFs demonstrating many of the core VimTeX editing +features listed in `:help vimtex-features` and documented in more detail at +`:help vimtex-mappings`. The GIFs and accompanying descriptions are used with +permission from [@ejmastnak](https://github.com/ejmastnak)'s guide to [Getting +started with the VimTeX +plugin](https://ejmastnak.github.io/tutorials/vim-latex/vimtex.html). + +Hopefully the animations can give you a clearer mental image of what these +mappings do and how you might use them. You may want to scroll through this page +while simultaneously looking through `:help vimtex-features`—the animations +should nicely complement the plain-text documentation. + +#### This page is community-maintained + +* This page is made possible only with help from the community. + [@ejmastnak](https://github.com/ejmastnak), not + [@lervag](https://github.com/lervag), takes primary responsibility for + maintaining it, but contributions from all VimTeX users are welcome. + +* If you notice mistakes or outdated content (following a VimTeX update, say) + feel free to open a PR to fix it yourself, or alternatively contact + [@ejmastnak](https://github.com/ejmastnak) at + [ejmastnak@gmail.com](mailto:ejmastnak@gmail.com), who will be happy to + help fix it. + +## Table of contents + + +* [Motion commands](#motion-commands) + * [Navigating sections](#navigating-sections) + * [Navigating environments](#navigating-environments) + * [Navigating math zones](#navigating-math-zones) + * [Navigating frames](#navigating-frames) + * [Navigating matching delimiters](#navigating-matching-delimiters) +* [Text objects](#text-objects) + * [The delimiter and environment objects](#the-delimiter-and-environment-objects) +* [Deleting surrounding LaTeX content](#deleting-surrounding-latex-content) + * [Delete surrounding commands](#delete-surrounding-commands) + * [Delete surrounding environments](#delete-surrounding-environments) + * [Delete surrounding math zones](#delete-surrounding-math-zones) + * [Delete surrounding delimiters](#delete-surrounding-delimiters) +* [Changing surrounding LaTeX content](#changing-surrounding-latex-content) + * [Change surrounding commands](#change-surrounding-commands) + * [Change surrounding environments](#change-surrounding-environments) + * [Change surrounding math zones](#change-surrounding-math-zones) + * [Change surrounding delimiters](#change-surrounding-delimiters) +* [Toggling commands](#toggling-commands) + * [Toggling starred commands and environments](#toggling-starred-commands-and-environments) + * [Toggling delimiter modifiers](#toggling-delimiter-modifiers) + * [Toggling fractions](#toggling-fractions) + + + +## Motion commands + +### Navigating sections + +Use `]]` to jump to the beginning of the next `\section`, `\subsection` or +`\subsubsection`, whichever comes first. Use `[[` to jump backward through +sections, and see the similar shortcuts `][` and `[]` in the VimTeX +documentation at `:help (vimtex-][)` and `:help (vimtex-[])`. + +![Navigating sections](https://github.com/lervag/vimtex-media/blob/main/gif/move/move-section.gif) + +### Navigating environments + +Use `]m` and `[m` to jump to the next or previous environment `\begin{}` +command. See the VimTeX documentation for the similar shortcuts `]M` and `[M`, +described in `:help (vimtex-]M)` and `:help (vimtex-[M)`. + +![Navigating environments](https://github.com/lervag/vimtex-media/blob/main/gif/move/move-environment.gif) + +### Navigating math zones + +Use `]n` and `[n` to jump to the beginning of the next or previous math zone. +See the VimTeX documentation for the similar shortcuts `]N` and `[N`, +described in `:help (vimtex-]N)` and `:help (vimtex-[N)`. + +![Navigating math zones](https://github.com/lervag/vimtex-media/blob/main/gif/move/move-math.gif) + +### Navigating frames + +Use `]r` and `[r` to jump to the beginning of the next or previous Beamer +`frame` environment. See the VimTeX documentation for the similar shortcuts +`]R` and `[R`, described in `:help (vimtex-]R)` and `:help +(vimtex-[R)`. + +![Navigating frames](https://github.com/lervag/vimtex-media/blob/main/gif/move/move-frame.gif) + +### Navigating matching delimiters + +Use `%` to move between matching delimiters, inline-math `$` delimiters, and LaTeX environments. + +![Navigating matching delimiters](https://github.com/lervag/vimtex-media/blob/main/gif/move/move-matching.gif) + +## Text objects + +VimTeX provides text objects for commands, delimiters, environments, math zones, +sections, and items. Currently only delimiters and environments have a GIF. + +### The delimiter and environment objects + +The following GIF uses Vim's visual mode to show highlight the scope of the +`id`, `ad`, `ie`, and `ae` text objects. + +![Delimiter and environment objects](https://github.com/lervag/vimtex-media/blob/main/gif/text-objects/text-objects.gif) + +## Deleting surrounding LaTeX content + +### Delete surrounding commands + +Use `dsc` to delete a LaTeX command while preserving the command's argument(s); +the `dsc` mapping also recognizes and correctly deletes parameters inside square +brackets. + +![`dsc`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/dsc.gif) + +### Delete surrounding environments + +Use `dse` to delete the `\begin{}` and `\end{}` declaration surrounding a LaTeX +environment without changing the environment contents. + +![`dse`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/dse.gif) + +### Delete surrounding math zones + +Use `ds$` to delete surrounding math zones (display math, standard environments, +and inline math) without changing the math contents. + +![`ds$`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/dsm.gif) + +### Delete surrounding delimiters + +Use `dsd` to delete delimiters (e.g. `()`, `[]`, `{}`, *and* any of their `\left +\right`, `\big \big` variants) without changing the enclosed content. + +![`dsd`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/dsd.gif) + + +## Changing surrounding LaTeX content + +### Change surrounding commands + +Use `csc` to change a LaTeX command while preserving the command's argument(s). + +![`csc`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/csc.gif) + +### Change surrounding environments + +Use `cse` to change the type of a LaTeX environment without changing the +environment contents. + +![`cse`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/cse.gif) + +### Change surrounding math zones + +Use `cs$` to change the type of surrounding math zone without changing the math +contents. You can switch between display math, standard environments, and inline +math. + +![`cs$`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/csm.gif) + +### Change surrounding delimiters + +Use `csd` to change delimiters (e.g. `()`, `[]`, `{}`, and any of their `\left +\right`, `\big \big` variants) without changing the enclosed content; the `csd` +command is "smart" and correctly recognizes and preserves `\left \right`-style +modifiers. + +![`csd`](https://github.com/lervag/vimtex-media/blob/main/gif/change-delete/csd.gif) + +## Toggling commands + +### Toggling starred commands and environments + +Use `tsc` and `tse` to toggle between starred and un-starred versions of +commands and environments, respectively. + +![`tsc` and `tse`](https://github.com/lervag/vimtex-media/blob/main/gif/toggle/tsc-tse.gif) + +### Toggling delimiter modifiers + +Use `tsd` to change between plain and `\left`/`\right` versions of delimiters. +Use the `g:vimtex_delim_toggle_mod_list` variable to add more modifiers to the +delimiter toggle list. (e.g. `\big` as in the GIF below) + +![`tsd`](https://github.com/lervag/vimtex-media/blob/main/gif/toggle/tsd.gif) + +### Toggling fractions + +Use `tsf` to toggle between inline and `\frac{}{}` versions of fractions. + +![`tsf`](https://github.com/lervag/vimtex-media/blob/main/gif/toggle/tsf.gif) +