feat!: change default cmd parser and add docs

refer: #2628

autoload/vimtex/cmd.vim

@@ -270,8 +270,7 @@ endfunction
 " }}}1
 
 function! vimtex#cmd#parser_separator_check(separator_string) abort " {{{1
-  return empty(substitute(a:separator_string, '\_s\+', '', 'g'))
-        \ && count(a:separator_string, "\n") < 2
+  return a:separator_string =~# '\v^%(\n\s*)?$'
 endfunction
 
 " }}}1

doc/vimtex.txt

@@ -1266,14 +1266,71 @@ OPTIONS                                                        *vimtex-options*
 <
   Default value: `bibtex`
 
+*g:vimtex_parser_cmd_separator_check*
+  This option specifies the function that is used to check the separator
+  string between command arguments. The option should be either the name of
+  the function (a string) or a |Funcref|. The function takes a single argument,
+  which is the separator string. It should return |v:true| if the parser
+  should continue and |v:false| if the parser should stop.
+
+  It is a hard problem to parse a LaTeX command without additional knowledge.
+  When we read `\foo{bar}{baz}` — is `{baz}` going to be consumed as an
+  argument to `\foo`? The only way to know this is to read the definition of
+  the `\foo` command/macro.
+
+  A pragmatic choice when we write a parser is therefore to instead rely on
+  some heuristics and common practises. This will never be perfect, but it can
+  be good enough for practical use. In VimTeX, the core heuristics are that
+  a command will look like this: >tex
+
+    \foo<overlay>[[opt]{arg}]...
+    \begin{name}<overlay>[[opt]{arg}]...
+<
+  The parser is greedy and will swallow as many groups of `[opts]` and
+  `{args}` as possible as long as the condition on the separator string
+  between the arguments is satisfied (i.e. this option!). The default function
+  will allow a line break and possibly white space on the preceding line
+  before a new group. E.g.: >tex
+
+    % command                number of args
+    % -------                --------------
+    \foo{bar}{baz}           % 2
+    \foo{bar} {baz}          % 1
+    \foo{bar}
+    {baz}                    % 2
+    \foo{bar}
+      {baz}                  % 2
+    \foo{bar}__
+      {baz}                  % 1 (_ indicates spaces)
+<
+  A user may want to change this behaviour e.g. to specify that all whitespace
+  should be allowed, including and up to a single newline: >vim
+
+    function! MyCmdSeparatorRule(separator_string)
+      return a:separator_string =~# '^\_s\+$'
+            \ && count(a:separator_string, "\n") < 2
+    endfunction
+
+    let g:vimtex_parser_cmd_separator_check = 'MyCmdSeparatorRule'
+<
+  Note: This option is relevant for any feature that relies on the parsing of
+        a command. This includes, but is not limited to the
+        |<plug>(vimtex-ac)| text object (|vimtex-text-objects|).
+
+  Note: |Funcref|s are only possible when it is used with neovim Lua
+        configuration, because in Vimscript, variable names must be
+        capitalized in order to point to |Funcref|s.
+
+  Default: `'vimtex#cmd#parser_separator_check'`
+
 *g:vimtex_bibliography_commands*
-    A list of command names for commands that include bibliography files.
-    Each list entry is interpreted as a pattern (very magic, see |/\v|) to
-    match a particular command name. This option may be useful if one defines
-    custom commands that includes bibliography files.
+  A list of command names for commands that include bibliography files. Each
+  list entry is interpreted as a pattern (very magic, see |/\v|) to match
+  a particular command name. This option may be useful if one defines custom
+  commands that includes bibliography files.
 
-    Default value: >
-        ['%(no)?bibliography', 'add%(bibresource|globalbib|sectionbib)']
+  Default value: >
+      ['%(no)?bibliography', 'add%(bibresource|globalbib|sectionbib)']
 
 *g:vimtex_complete_bib*
   This option is a dictionary for controlling the citation completion. The
@@ -3778,6 +3835,9 @@ cursor position before the operation. >
     \item hello moon|          dam     \end{itemize}
   \end{itemize}
 
+Note: The "greediness" of the command text objects (`ic` and `ac`) can be
+      controlled with |g:vimtex_parser_cmd_separator_check|.
+
 Note: Some of the text objects rely on syntax highlighting (|vimtex-syntax|)
       to work. That is, some text objects check the syntax groups to determine
       the proper regions. Examples include the math text objects (e.g.