<commit_before># Documentation

Welcome to the high-level documentation of VimTeX.

This file should help you to understand the structure of this plugin and how
it works.

So first of all, we're taking a look into the first layer of the plugin, after
that, we're going to through each necessary directory, if it needs some more
description. We won't go through _every_ file, because it would take a little
bit too long the most should be probably self explained.

This file works as follows:
The table of contents has the same structure as the file structure of
VimTeX. If you want to know something about the
`vimtex/autoload/vimtex/compiler` directory, than you can lookup the path in the
table of contents and click on it. (Hopefully) It'll give you some nice
information.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [ftplugin](#ftplugin)
- [syntax](#syntax)
- [indent](#indent)
- [after/ftplugin](#afterftplugin)
- [autoload](#autoload)
  - [health](#health)
  - [unite/sources](#unitesources)
  - [vimtex](#vimtex)
    - [delim.vim](#delimvim)
    - [cache.vim](#cachevim)
    - [compiler](#compiler)
    - [debug.vim](#debugvim)
    - [complete (dir)](#complete-dir)
      - [tools](#tools)
    - [context](#context)
    - [fold](#fold)
    - [parser](#parser)
    - [qf](#qf)
    - [syntax](#syntax-1)
    - [text_obj](#text_obj)
    - [view](#view)
- [rplugin/python3/denite/source/vimtex.py](#rpluginpython3denitesourcevimtexpy)
- [test](#test)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# ftplugin
Well nothing really big to say here: If you open a `bib` or `tex` tiletype
it'll look, if you have VimTeX has been loaded.

# syntax
The main file which loads the syntax highlighting settings according to its
needs because all syntax rules might wouldn't be worth it.

# indent
The main function is `VimtexIndent` which returns the indent of the next line
you're writing. If you want to know how it's doing that, take a look into this
function!

# after/ftplugin

Currently there's only one file in it which makes sure that VimTeX loaded
successfully and that there're no conflicts with other plugins like LaTeX-Box.

# autoload

If you want to know more about the *special functionality* of the `autoload`
directory, you can read the `:h autoload` section or take a little look into
[this chapter](https://learnvimscriptthehardway.stevelosh.com/chapters/42.html)
of [Learn Vimscript the Hard
Way](https://learnvimscriptthehardway.stevelosh.com/chapters/42.html) by <NAME>.

## health

This directory has the following health-checks functions:

- If the user has a valid vim version
- If the user selected a valid compiler
- If their might be any plugin-clashes.
- If the user has the needed dependencies for their PDF-Viewer

**HINT:**** This file uses some functions provided by the `health.vim` framework
which is only available for `neovim`!

## unite/sources

This directory is used to combine VimTeX with
[denite](https://github.com/Shougo/denite.nvim) or
[unite](https://github.com/Shougo/unite.vim). These extra-plugins are mainly
used to list the TOC of your current document. Take a look into `:h vimtex-unite`, to get more information.

## vimtex

This directory has the main files. Each file should be self-explaining but here
are some files which might be good to know!

## vimtex.vim

This file includes the main function: `vimtex#init()` which loads all the
functionalities from all other files and modules.

### delim.vim

This file includes some functions to detect the surrounding delimiters like
this:

```tex
\begin{Environment}
    Some awesome text |
\end{Environment}
```

The vertical line (`|`) should represent your cursor. Now you could use the
`vimtex#delim#get_surrounding('env_tex')` function in order to get the current
environment where the user is. Here's an example code:

```vim
" Return values are dictionaries
let [l:open, l:close] = vimtex#delim#get_surrounding('env_tex')

" Empty dicts mean we did not find a surrounding environment
if empty(l:open) | return | endif

" The dicts have several attributes, the most important are probably these:
echo l:open.name
echo l:open.lnum
echo l:open.cnum
```

For more information, take a look into [this
issue](https://github.com/lervag/vimtex/issues/1981#issuecomment-792263781).

### cache.vim
This file includes some functions to create and access your own caches.
Here's an example:

```vim
function VimTeXCacheExample()
    " create a new cache (if the name doesn't exist yet)
    " with an attribute 'number'. So the cache would be like that:
    "
    "   let l:test = {
    "     'number' = 10,
    "   }
    let l:my_cache = vimtex#cache#open('cache_name', {'number' : 10})

    " change the value in you cache
    let l:my_cache['number'] = 9001

    " will print '9001'
    echo l:my_cache['number']

    " save your changes
    " In general it'll be saved in your `$XDG_CACHE_HOME/vimtex/` directory
    " (normally '~/.cache/vimtex') in the appropriate tex-file where you accessed
    " cache file.
    call vimtex#cache#close('cache_name')
endfunction
```

### compiler
As the directory names says: This directory includes the vim files to interact
with the given LaTeX compiler. Each file have similar function names like
`s:compiler.start`. You can take a look into these function to get a better
understanding how they work.

### debug.vim
This file is used for interal debugging and is not related to LaTeX at all. It
parses the stacktrace from the `v:throwpoint` variable (see `:h v:throwpoint`
        for more information). If this does not exist, then we forcibly create
it and remove the top element.
You can try this code as an example:

```vim
function! Test() abort
  try<commit_msg>Set code indentation from 4 spaces to 2<commit_after># Documentation

Welcome to the high-level documentation of VimTeX.

This file should help you to understand the structure of this plugin and how
it works.

So first of all, we're taking a look into the first layer of the plugin, after
that, we're going to through each necessary directory, if it needs some more
description. We won't go through _every_ file, because it would take a little
bit too long the most should be probably self explained.

This file works as follows:
The table of contents has the same structure as the file structure of
VimTeX. If you want to know something about the
`vimtex/autoload/vimtex/compiler` directory, than you can lookup the path in the
table of contents and click on it. (Hopefully) It'll give you some nice
information.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [ftplugin](#ftplugin)
- [syntax](#syntax)
- [indent](#indent)
- [after/ftplugin](#afterftplugin)
- [autoload](#autoload)
  - [health](#health)
  - [unite/sources](#unitesources)
  - [vimtex](#vimtex)
    - [delim.vim](#delimvim)
    - [cache.vim](#cachevim)
    - [compiler](#compiler)
    - [debug.vim](#debugvim)
    - [complete (dir)](#complete-dir)
      - [tools](#tools)
    - [context](#context)
    - [fold](#fold)
    - [parser](#parser)
    - [qf](#qf)
    - [syntax](#syntax-1)
    - [text_obj](#text_obj)
    - [view](#view)
- [rplugin/python3/denite/source/vimtex.py](#rpluginpython3denitesourcevimtexpy)
- [test](#test)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# ftplugin
Well nothing really big to say here: If you open a `bib` or `tex` tiletype
it'll look, if you have VimTeX has been loaded.

# syntax
The main file which loads the syntax highlighting settings according to its
needs because all syntax rules might wouldn't be worth it.

# indent
The main function is `VimtexIndent` which returns the indent of the next line
you're writing. If you want to know how it's doing that, take a look into this
function!

# after/ftplugin

Currently there's only one file in it which makes sure that VimTeX loaded
successfully and that there're no conflicts with other plugins like LaTeX-Box.

# autoload

If you want to know more about the *special functionality* of the `autoload`
directory, you can read the `:h autoload` section or take a little look into
[this chapter](https://learnvimscriptthehardway.stevelosh.com/chapters/42.html)
of [Learn Vimscript the Hard
Way](https://learnvimscriptthehardway.stevelosh.com/chapters/42.html) by Steve
Losh.

## health

This directory has the following health-checks functions:

- If the user has a valid vim version
- If the user selected a valid compiler
- If their might be any plugin-clashes.
- If the user has the needed dependencies for their PDF-Viewer

**HINT:**** This file uses some functions provided by the `health.vim` framework
which is only available for `neovim`!

## unite/sources

This directory is used to combine VimTeX with
[denite](https://github.com/Shougo/denite.nvim) or
[unite](https://github.com/Shougo/unite.vim). These extra-plugins are mainly
used to list the TOC of your current document. Take a look into `:h vimtex-unite`, to get more information.

## vimtex

This directory has the main files. Each file should be self-explaining but here
are some files which might be good to know!

## vimtex.vim

This file includes the main function: `vimtex#init()` which loads all the
functionalities from all other files and modules.

### delim.vim

This file includes some functions to detect the surrounding delimiters like
this:

```tex
\begin{Environment}
  Some awesome text |
\end{Environment}
```

The vertical line (`|`) should represent your cursor. Now you could use the
`vimtex#delim#get_surrounding('env_tex')` function in order to get the current
environment where the user is. Here's an example code:

```vim
" Return values are dictionaries
let [l:open, l:close] = vimtex#delim#get_surrounding('env_tex')

" Empty dicts mean we did not find a surrounding environment
if empty(l:open) | return | endif

" The dicts have several attributes, the most important are probably these:
echo l:open.name
echo l:open.lnum
echo l:open.cnum
```

For more information, take a look into [this
issue](https://github.com/lervag/vimtex/issues/1981#issuecomment-792263781).

### cache.vim
This file includes some functions to create and access your own caches.
Here's an example:

```vim
function VimTeXCacheExample()
  " create a new cache (if the name doesn't exist yet)
  " with an attribute 'number'. So the cache would be like that:
  "
  "   let l:test = {
  "   'number' = 10,
  "   }
  let l:my_cache = vimtex#cache#open('cache_name', {'number' : 10})

  " change the value in you cache
  let l:my_cache['number'] = 9001

  " will print '9001'
  echo l:my_cache['number']

  " save your changes
  " In general it'll be saved in your `$XDG_CACHE_HOME/vimtex/` directory
  " (normally '~/.cache/vimtex') in the appropriate tex-file where you accessed
  " cache file.
  call vimtex#cache#close('cache_name')
endfunction
```

### compiler
As the directory names says: This directory includes the vim files to interact
with the given LaTeX compiler. Each file have similar function names like
`s:compiler.start`. You can take a look into these function to get a better
understanding how they work.

### debug.vim
This file is used for interal debugging and is not related to LaTeX at all. It
parses the stacktrace from the `v:throwpoint` variable (see `:h v:throwpoint`
for more information). If this does not exist, then we forcibly create
it and remove the top element.
You can try this code as an example:

```vim
function! Test() abort
  try
{'fraction_non_alphanumeric': 0.09436547353998972, 'fraction_numerical': 0.005651652680253468, 'mean_word_length': 4.133626373626374, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2434287', 'n_tokens_mistral': 3690, 'n_tokens_neox': 3401, 'n_words': 1501}