|
| 1 | +# Documentation |
| 2 | + |
| 3 | +Welcome to the high-level documentation of VimTeX. |
| 4 | + |
| 5 | +This file should help you to understand the structure of this plugin and how |
| 6 | +it works. |
| 7 | + |
| 8 | +So first of all, we're taking a look into the first layer of the plugin, after |
| 9 | +that, we're going to through each necessary directory, if it needs some more |
| 10 | +description. We won't go through _every_ file, because it would take a little |
| 11 | +bit too long the most should be probably self explained. |
| 12 | + |
| 13 | +This file works as follows: |
| 14 | +The table of contents has the same structure as the file structure of |
| 15 | +VimTeX. If you want to know something about the |
| 16 | +`vimtex/autoload/vimtex/compiler` directory, than you can lookup the path in the |
| 17 | +table of contents and click on it. (Hopefully) It'll give you some nice |
| 18 | +information. |
| 19 | + |
| 20 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 21 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 22 | + |
| 23 | + |
| 24 | +- [ftplugin](#ftplugin) |
| 25 | +- [syntax](#syntax) |
| 26 | +- [indent](#indent) |
| 27 | +- [after/ftplugin](#afterftplugin) |
| 28 | +- [autoload](#autoload) |
| 29 | + - [health](#health) |
| 30 | + - [unite/sources](#unitesources) |
| 31 | + - [vimtex](#vimtex) |
| 32 | + - [vimtex.vim](#vimtexvim) |
| 33 | + - [delim.vim](#delimvim) |
| 34 | + - [cache.vim](#cachevim) |
| 35 | + - [compiler](#compiler) |
| 36 | + - [compiler.vim](#compilervim) |
| 37 | + - [debug.vim](#debugvim) |
| 38 | + - [complete.vim](#completevim) |
| 39 | + - [tools](#tools) |
| 40 | + - [context.vim](#contextvim) |
| 41 | + - [fold.vim](#foldvim) |
| 42 | + - [parser.vim](#parservim) |
| 43 | + - [qf.vim](#qfvim) |
| 44 | + - [syntax](#syntax-1) |
| 45 | + - [text\_obj.vim](#text%5C_objvim) |
| 46 | + - [view.vim](#viewvim) |
| 47 | +- [rplugin/python3/denite/source/vimtex.py](#rpluginpython3denitesourcevimtexpy) |
| 48 | +- [test](#test) |
| 49 | + |
| 50 | +<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 51 | + |
| 52 | +# ftplugin |
| 53 | +Well nothing really big to say here: If you open a `bib` or `tex` tiletype |
| 54 | +it'll look, if you have VimTeX has been loaded. |
| 55 | + |
| 56 | +# syntax |
| 57 | +The main file which loads the syntax highlighting settings according to its |
| 58 | +needs because all syntax rules might wouldn't be worth it. |
| 59 | + |
| 60 | +# indent |
| 61 | +The main function is `VimtexIndent` which returns the indent of the next line |
| 62 | +you're writing. If you want to know how it's doing that, take a look into this |
| 63 | +function! |
| 64 | + |
| 65 | +# after/ftplugin |
| 66 | + |
| 67 | +Currently there's only one file in it which makes sure that VimTeX loaded |
| 68 | +successfully and that there're no conflicts with other plugins like LaTeX-Box. |
| 69 | + |
| 70 | +# autoload |
| 71 | + |
| 72 | +If you want to know more about the *special functionality* of the `autoload` |
| 73 | +directory, you can read the `:h autoload` section or take a little look into |
| 74 | +[this chapter](https://learnvimscriptthehardway.stevelosh.com/chapters/42.html) |
| 75 | +of [Learn Vimscript the Hard |
| 76 | +Way](https://learnvimscriptthehardway.stevelosh.com/chapters/42.html) by Steve |
| 77 | +Losh. |
| 78 | + |
| 79 | +## health |
| 80 | + |
| 81 | +This directory has the following health-checks functions: |
| 82 | + |
| 83 | +- If the user has a valid vim version |
| 84 | +- If the user selected a valid compiler |
| 85 | +- If their might be any plugin-clashes. |
| 86 | +- If the user has the needed dependencies for their PDF-Viewer |
| 87 | + |
| 88 | +**HINT:**** This file uses some functions provided by the `health.vim` framework |
| 89 | +which is only available for `neovim`! |
| 90 | + |
| 91 | +## unite/sources |
| 92 | + |
| 93 | +This directory is used to combine VimTeX with |
| 94 | +[denite](https://github.com/Shougo/denite.nvim) or |
| 95 | +[unite](https://github.com/Shougo/unite.vim). These extra-plugins are mainly |
| 96 | +used to list the TOC of your current document. Take a look into `:h vimtex-unite`, to get more information. |
| 97 | + |
| 98 | +## vimtex |
| 99 | + |
| 100 | +This directory has the main files. Each file should be self-explaining but here |
| 101 | +are some files which might be good to know! |
| 102 | + |
| 103 | +## vimtex.vim |
| 104 | + |
| 105 | +This file includes the main function: `vimtex#init()` which loads all the |
| 106 | +functionalities from all other files and modules. |
| 107 | + |
| 108 | +### delim.vim |
| 109 | + |
| 110 | +This file includes some functions to detect the surrounding delimiters like |
| 111 | +this: |
| 112 | + |
| 113 | +```tex |
| 114 | +\begin{Environment} |
| 115 | + Some awesome text | |
| 116 | +\end{Environment} |
| 117 | +``` |
| 118 | + |
| 119 | +The vertical line (`|`) should represent your cursor. Now you could use the |
| 120 | +`vimtex#delim#get_surrounding('env_tex')` function in order to get the current |
| 121 | +environment where the user is. Here's an example code: |
| 122 | + |
| 123 | +```vim |
| 124 | +" Return values are dictionaries |
| 125 | +let [l:open, l:close] = vimtex#delim#get_surrounding('env_tex') |
| 126 | +
|
| 127 | +" Empty dicts mean we did not find a surrounding environment |
| 128 | +if empty(l:open) | return | endif |
| 129 | +
|
| 130 | +" The dicts have several attributes, the most important are probably these: |
| 131 | +echo l:open.name |
| 132 | +echo l:open.lnum |
| 133 | +echo l:open.cnum |
| 134 | +``` |
| 135 | + |
| 136 | +For more information, take a look into [this |
| 137 | +issue](https://github.com/lervag/vimtex/issues/1981#issuecomment-792263781). |
| 138 | + |
| 139 | +### cache.vim |
| 140 | +This file includes some functions to create and access your own caches. |
| 141 | +Here's an example: |
| 142 | + |
| 143 | +```vim |
| 144 | +function VimTeXCacheExample() |
| 145 | + " create a new cache (if the name doesn't exist yet) |
| 146 | + " with an attribute 'number'. So the cache would be like that: |
| 147 | + " |
| 148 | + " let l:test = { |
| 149 | + " 'number' = 10, |
| 150 | + " } |
| 151 | + let l:my_cache = vimtex#cache#open('cache_name', {'number' : 10}) |
| 152 | +
|
| 153 | + " change the value in you cache |
| 154 | + let l:my_cache['number'] = 9001 |
| 155 | +
|
| 156 | + " will print '9001' |
| 157 | + echo l:my_cache['number'] |
| 158 | +
|
| 159 | + " save your changes |
| 160 | + " In general it'll be saved in your `$XDG_CACHE_HOME/vimtex/` directory |
| 161 | + " (normally '~/.cache/vimtex') in the appropriate tex-file where you accessed |
| 162 | + " cache file. |
| 163 | + call vimtex#cache#close('cache_name') |
| 164 | +endfunction |
| 165 | +``` |
| 166 | + |
| 167 | +### compiler |
| 168 | +As the directory names says: This directory includes the vim files to interact |
| 169 | +with the given LaTeX compiler. Each file have similar function names like |
| 170 | +`s:compiler.start`. You can take a look into these function to get a better |
| 171 | +understanding how they work. |
| 172 | + |
| 173 | +### compiler.vim |
| 174 | +This file includes the main functions to interact with the given compiler in the |
| 175 | +`vimtex/autoload/vimtex/compiler` directory, it also provides the commands like |
| 176 | +`:VimtexCompile`. For example, the `vimtex#compiler#start()` function just calls |
| 177 | +(if we selected the latexmk compiler) the `s:compiler_nvim.start_single()` |
| 178 | +function of the `vimtex/autolaod/vimtex/compiler/latexmk.vim` file. |
| 179 | + |
| 180 | +### debug.vim |
| 181 | +This file is used for interal debugging and is not related to LaTeX at all. It |
| 182 | +parses the stacktrace from the `v:throwpoint` variable (see `:h v:throwpoint` |
| 183 | +for more information). If this does not exist, then we forcibly create |
| 184 | +it and remove the top element. |
| 185 | +You can try this code as an example: |
| 186 | + |
| 187 | +```vim |
| 188 | +function! Test() abort |
| 189 | + try |
| 190 | + throw "Error message is here :D" |
| 191 | + catch |
| 192 | + call vimtex#debug#stacktrace(1) |
| 193 | + endtry |
| 194 | +endfunction |
| 195 | +``` |
| 196 | +Now enter `:call Test()` and the quickfix window should pop up with the `"Error |
| 197 | +message is here :D"` message. |
| 198 | + |
| 199 | +### complete.vim |
| 200 | +It includes a bunch of functions to filter out the information for the omnifunc |
| 201 | +function of vim like getting the names of the custom-environments and loading |
| 202 | +the given keywords of a package. Each section includes a function which takes |
| 203 | +care for a given part of the omnicompletion. |
| 204 | + |
| 205 | +The `complete` directory includes all keywords which are loaded for the given |
| 206 | +package you're using in your `tex` file. |
| 207 | + |
| 208 | +#### tools |
| 209 | +This directory includes all glyphs like α and β. |
| 210 | + |
| 211 | +### context.vim |
| 212 | +The single file (`cite.vim`) is used for the `vimtex-context-citation` part. |
| 213 | +[Here's](https://github.com/lervag/vimtex/pull/1961#issuecomment-795476750) a more detailed description of what it does and what's it's used for. |
| 214 | + |
| 215 | +### fold.vim |
| 216 | +This file includes the functions to create the foldings. The main function is |
| 217 | +the `vimtex#fold#init_state(state)` function which is calling the needed fold |
| 218 | +functions for the current section: |
| 219 | + |
| 220 | +```vim |
| 221 | + " this is in line 43 |
| 222 | + let a:state.fold_types_dict[l:key] = vimtex#fold#{l:key}#new(l:config) |
| 223 | +``` |
| 224 | + |
| 225 | +The `vimtex/autoload/vimtex/fold` directory takes care of folding your `tex` |
| 226 | +document like this thanks to the functions of each file: |
| 227 | + |
| 228 | + |
| 229 | +The filenames in this directory represent what it folds. |
| 230 | + |
| 231 | +### parser.vim |
| 232 | +As the name of the file says: It's parsing the file we're currently editing. For |
| 233 | +example it looks where the preamble stops or how the table of contents is |
| 234 | +structured. Thanks to these information we're able to see a little TOC to |
| 235 | +navigate in our file (`:h :VimtexTocToggle` for more information): |
| 236 | + |
| 237 | + |
| 238 | + |
| 239 | +The `vimcomplete.bst` file is used by `parser/bib.vim` in the |
| 240 | +`s:parse_with_bibtex()` function, which will actually run the bibtex problem |
| 241 | +with the supplied `.bst` file in order to convert a `.bib` file to a `.bbl` file |
| 242 | +that is much easier to parse. |
| 243 | + |
| 244 | +### qf.vim |
| 245 | +Here we're creating the entries for the quickfix window do display them. It |
| 246 | +depends on which filetype we're currently editing. For example if we're editing |
| 247 | +a `bib` file, than it's using the function in the |
| 248 | +`vimtex/autoload/vimtex/qf/bibtex.vim` in order to create the appropriate |
| 249 | +error/warning logs. |
| 250 | + |
| 251 | +Here's an example which is generated through the `latexlog.vim` |
| 252 | +file: |
| 253 | + |
| 254 | + |
| 255 | +### syntax |
| 256 | +This directory includes the syntax highlighting rules for each keyword in a |
| 257 | +LaTeX file. But the *main* syntax-highlighting functionalities are in the |
| 258 | +`syntax/core.vim` file which also includes the concealling characters starting |
| 259 | +from line 745. |
| 260 | + |
| 261 | +The `p` directory just includes more syntax highlighting rules which are *only* |
| 262 | +loaded if they are needed. |
| 263 | + |
| 264 | +### text\_obj.vim |
| 265 | +This file includes some functions which can be used to get some information |
| 266 | +about the current user position. `envtargets.vim` includes for instance some |
| 267 | +functions like `vimtex#text_obj#envtargets#current` to get the current |
| 268 | +environment where the user is. |
| 269 | + |
| 270 | +### view.vim |
| 271 | +In this file we're interacting with the given PDF-Viewer set by the |
| 272 | +`g:vimtex_view_method` variable (like zathura). VimTeX is calling the |
| 273 | +appropriate functions of the selected pdf-viewer. |
| 274 | +In order to achieve that, it just use the `g:vimtex\_view\_method` variable to |
| 275 | +get the (file)name in the `vimtex/autoload/vimtex/view` directory where all |
| 276 | +files have the same function names. Just a different name according to the |
| 277 | +compiler. So it looks like that (line is from the `vimtex#view#init_buffer()` |
| 278 | +function): |
| 279 | + |
| 280 | +```vim |
| 281 | + let a:state.viewer = vimtex#view#{g:vimtex\_view\_method}#new() |
| 282 | +``` |
| 283 | + |
| 284 | +If `g:vimtex\_view\_method` would be `zathura`, we'd call the |
| 285 | +`vimtex#view#zathura#new()` function which call zathura to open the PDF-file for |
| 286 | +us. |
| 287 | + |
| 288 | +# rplugin/python3/denite/source/vimtex.py |
| 289 | +This file is used to interact with the |
| 290 | +[denite.vim](https://github.com/Shougo/denite.nvim) plugin. For example to jump |
| 291 | +to a section/subsection or chapter. |
| 292 | + |
| 293 | +# test |
| 294 | +This directory includes *all* test cases which have to pass in order to have a |
| 295 | +stable and functional awesome VimTeX plugin :) Each directory and filename |
| 296 | +should be self explaining for which cases they are used for. |
0 commit comments