Trying to understand "g:vimtex_syntax_custom_envs"

Description

Hello there, im trying to learn how to define custom envs, and im having some difficulty understanding the documentation on g:vimtex_syntax_custom_envs

    region ~
      Default: `tex{Name}Zone`
      The syntax group used to match the defined region.

      Note: If `math` is |v:true|, then the region will always be set to
      `texMathZoneEnv`.

What is a region, where can i see the existing regions so i can match what is expected.

    opts ~
      Default: Undefined
      A string with additional options that will be passed to the `syntax
      region` command (see |syn-region|).

    contains ~
      Default: Undefined
      A comma-separated string of syntax groups that should be contained in
      within the matched region (see |syn-contains|).

i read :help syn-region but still am quite confused what region stands for here, what kind of options should i provide? same for "contains"

    nested ~
      Default: Undefined
      This can be either a string or a dictionary:

        |String|:     specify nested syntax to load inside the environment
        |Dictionary|: specify "predicated" nested syntaxes (more flexible)

      The dictionary uses the target syntax as the key and the "predicate" as
      the value. This predicate is a string that must be contained within the
      optional argument. See below for an example.

      Notice that one should also be aware of |g:vimtex_syntax_nested|.

im not sure if im understanding this right but this means what kind of language should be inside the environment

im trying to cross-over some environments that i used to neovim, maybe we could define one environment as example:

this is the sectionBox that simply organizes a single environment that defines if its a section, subsection or subsubsection, if its starred or not, puts inside a minipage if no m is specified, puts inside a tcolorbox if no b is inserted.

\NewDocumentEnvironment{sectionBox}
{
    s       % #1 - Numbered
    t1      % #2 - section
    t2      % #3 - Subsection
    t3      % #4 - Subsubsection
    tb      % #5 - Background
    tm      % #6 - Minipage (samepage)
    O{1ex}  % #7 - vspace
    m       % #8 - title
    +b      % #9 - content
}{
    \vspace{#7}\relax
    \IfBooleanF{#6}{\noindent\begin{minipage}{\linewidth}}
        \IfBooleanTF{#1}{%
            \IfBooleanT{#2}{       \section*{#8}\relax}
            \IfBooleanT{#3}{    \subsection*{#8}\relax}
            \IfBooleanT{#4}{ \subsubsection*{#8}\relax}
        }{%
            \IfBooleanT{#2}{      \section {#8}\relax}
            \IfBooleanT{#3}{   \subsection {#8}\relax}
            \IfBooleanT{#4}{\subsubsection {#8}\relax}
        }
        \IfBooleanTF{#5}
            { #9 }
            { \begin{tcolorbox}[%
                \IfBooleanT{#6}{breakable}%
            ] #9 \end{tcolorbox}\relax }
        \IfBooleanF{#6}{\end{minipage}\relax}
}{      \relax }

this is an example how its used:

\begin{sectionBox}1bm{Introduction} % S1
  Our objective is to take a \emph{feed} spend energy applying \emph{unit operations} to it so that we get a \emph{product} with smaller particles

\end{sectionBox}

\begin{sectionBox}2{Unit operations} % S1.1
  Normally a crusher or a mill is an unitary operation that receives a feed and spends energy to reduce to a product

  The whole process takes several stages of size reduction each specifying on reducing its specific feed particle sizes:
  \begin{enumerate}
    \item Coarse reduction
    \item intermediate reduction
    \item Fine reduction
  \end{enumerate}
\end{sectionBox}

i tried defining in vimtex like this so far, im clueless how else i should specify.

    vim.g.vimtex_syntax_custom_envs = {
      {
        name = "sectionBox",
        starred = true,
      }
    }

Steps to reproduce

No response

Expected behavior

No response

Actual behavior

No response

Do you use a latexmkrc file?

VimtexInfo

not applicable

i read #2745 but im not sure if i should add relation tag to that

    region ~
      Default: `tex{Name}Zone`
      The syntax group used to match the defined region.

What is a region,

In this context, a region is the syntax group used to match the defined region. Sorry, I couldn't help it. :p

Now, "a defined region" here refers to the syntax region, which is one of three types of syntax items supported in the legacy syntax engine. See :help syn-define, which explains:

Vim understands three types of syntax items:

1. Keyword ...

2. Match ...

3. Region
   This starts at a match of the "start" regexp pattern and ends with a match
   with the "end" regexp pattern.  Any other text can appear in between.  A
   "skip" regexp pattern can be used to avoid matching the "end" pattern.

where can i see the existing regions so i can match what is expected.

You can do :syntax list to list all defined syntax items, and :syntax list GROUP to list all items defined for the specified syntax group. Each item consists of a specific rule, which is either a keyword, a match, or a region.

    opts ~
      Default: Undefined
      A string with additional options that will be passed to the `syntax
      region` command (see |syn-region|).

    contains ~
      Default: Undefined
      A comma-separated string of syntax groups that should be contained in
      within the matched region (see |syn-contains|).

i read syn-region but still am quite confused what region stands for here, what kind of options should i provide? same for "contains"

So, I think you may need some more context to understand this thing. For each item in g:vimtex_syntax_custom_envs, VimTeX will create a syntax item with :syntax region .... The opts and contains are used to build the :syntax region command.

    nested ~
      Default: Undefined
      This can be either a string or a dictionary:

        |String|:     specify nested syntax to load inside the environment
        |Dictionary|: specify "predicated" nested syntaxes (more flexible)

      The dictionary uses the target syntax as the key and the "predicate" as
      the value. This predicate is a string that must be contained within the
      optional argument. See below for an example.

      Notice that one should also be aware of |g:vimtex_syntax_nested|.

im not sure if im understanding this right but this means what kind of language should be inside the environment

Yes, more or less. You can make a custom environment rule that would allow to highlight the env content as another language.

this is the sectionBox that simply organizes a single environment that defines if its a section, subsection or subsubsection, if its starred or not, puts inside a minipage if no m is specified, puts inside a tcolorbox if no b is inserted. … i tried defining in vimtex like this so far, im clueless how else i should specify.

This environment is very complex, and I'm not sure that you will be able to match it properly with g:vimtex_syntax_custom_envs. It seems the following is the proper rule here:

\begin{sectionBox}OPTS{Title}
  contents here
\end{sectionBox}

% OPTS: a sequence of characters, never empty
% {Title}: title (mandatory)

If I'm right, then you could make a rule similar to this in after/syntax/tex.vim:

syntax match texSectionBoxEnvBgn "\\begin{sectionBox}"
      \ nextgroup=texSectionBoxOpts skipwhite skipnl
      \ contains=texCmdEnv
syntax match texSectionBoxOpts "[s123bm]\+"
      \ contained
      \ nextgroup=texSectionBoxTitle skipwhite skipnl
call vimtex#syntax#core#new_arg('texSectionBoxTitle')

highlight def link texSectionBoxOpts texOpt
highlight def link texSectionBoxTitle texPartArgTitle

lervag / vimtex