Vim's documentation (help files) - Some incomprehensible jumps

Dear All,

Using Vim's documentation quite intensely I found some perplexing behavior of tags within the help files, both on Gvim 8.0 (Win 7) and vim 7.4 (Ubuntu 16.04). Note: the tags files for Gvim 8.0 and vim 7.4 are respectively:
C:\Program Files (x86)\Vim\vim80\doc\tags
/usr/share/vim/vim74/doc/tags

The line numbers will refer to Gvim 8.0. They differ little in vim 7.4.

Allow me to give you first a short preamble to set the stage.

My investigation started when I tried to get an understanding of 'group' in Section 2 of autocmd.txt:

2. Defining autocommands *autocmd-define*

*:au* *:autocmd*
:au[tocmd] [group] {event} {pat} [nested] {cmd}
Add {cmd} to the list of commands that Vim will
execute automatically on {event} for a file matching
{pat} |autocmd-patterns|.
Vim always adds the {cmd} after existing autocommands,
so that the autocommands execute in the order in which
they were given. See |autocmd-nested| for [nested].

First I discovered a misconception of mine. I was thinking that any word in the documentation that is highlighted by coloring or enclosed between ||, '', [], (), "", {} or <> had a tag defined. Actually it is not. For sure, the words or WORDS between bars (|) do have a tag (e.g. autocmd-patterns). The destination of the tag appears between the stars (*), e.g. autocmd-define or :au or :augroup. For instance, still in section 2 of autocmd.txt, one reads (line 96+):

When the [group] argument is not given, Vim uses the current group (as defined
with ":augroup"); otherwise, Vim uses the group defined with [group]. Note
that [group] must have been defined before. You cannot define a new group
with ":au group ..."; use ":augroup" for that.

but there is no tag for the word 'group' (in color and between []) but there is one for ':augroup' (no color and between ""). You would indeed expect a tag for the latter because it is a : command (cmdline or Ex).

There are 2 ways to jump to a tag. Either one uses the command:

:tag someword

or

position the cursor over 'aword' and type 'Ctrl-]'

In the first case if there is indeed a tag named 'someword' in the tags file, Vim jumps to the defined destination. In the second case Vim looks for a tag named 'aword' and jumps to the destination if one exists. If there is no tag in the tags file, then one gets an error message:

E426: tag not found: someword

or

E149: Sorry, no help for aword

Hoping I have not made a mistake in the above introduction, let me guide you through the analysis that prompted me to write this post.

1) Is there a tag named 'group' ?

:tag /group^D

gives me a list of 11 matches containing the pattern 'group', while

:tag group^D

gives me one choice only, namely the tag 'group-name', while

:tag group

reports 'E426: tag not found: group'.

Answer: there is no tag named 'group'.

2) What about using 'Ctrl-]' instead of ':tag' ? (That's what I do instinctively).

This is where things begin to become incomprehensible. There are 21 occurrences of the pattern '[group]' in 'autocmd.txt' (:set hls /\[group\]). When positioning the cursor over the 1st occurrence (line 56) and typing 'Ctrl-]' vim jumps to 'index.txt' (line 687):

2.4 Commands starting with 'g' *g*

Trying to make sense out of this I thought that maybe the whole token '[group]' is taken into account and interpreted as a regular expression 'any character of the set g, r, o, u, p'. This I cannot verify but I made such an hypothesis.

Question A: Is this hypothesis correct ?

Now, it becomes really disturbing. All but 3 of the 21 occurrences of '[group]' behave as just described. These 3 exceptions are:

'[group]' in line 97 and 137 jump to line 1097 in 'syntax.txt':
CPP *cpp.vim* *ft-cpp-syntax*

'[group]' in line 156 jumps to line 1126 of 'motion.txt':
*g;* *E662*
g; Go to [count] older position in change list.

This is where I get lost.

Question B: What is happening for these 3 exceptions to exist ?

3) What about ':tag' and 'Ctrl-]' on the word 'group'.

Let us position our cursor on the word 'group' (line 99, char 11). The ':tag group' command reports the same E426 error but the 'Ctrl-]' command jumps to line 207 in 'syntax.txt':

NAMING CONVENTIONS *group-name* *{group-name}* *E669* *W18*

Question C: Is it correct to say that ':tag' simply searches for the exact given token while 'Ctrl-]' does perform some pattern logic before looking up for the token ?

4) What happens when adding the token 'group' in the 'tags file' ?

I opened the 'tags file' (refer to the note at the top) and added a line to it for an entry with 'group'. I know this is not proper doing but I wanted to try and understand.

group autocmd.txt /*autocmd-groups*
group-name syntax.txt /*group-name*

Now, with this line added, I have the following results:

:tag group --> brings me where I wanted to arrive (Section 8).
Ctrl-] on 'group' --> brings me where I want too.
Ctrl-] on '[group]' --> behaves as strangely as explained above with the following specifics: (i) most of the jumps take me now to line 1809 of 'insert.txt' with destination 'o' (the set of letters g, r, o, u, p in alphabetical order or ASCII ascending value is g, o, p, r, u - I'm simply making another hypothesis); (ii) the 3 exceptions listed above remain exactly the same by jump to the exact same destinations as written above.

Question D: Can this second hypothesis be linked to the first in Question A ?

In conclusion, the really incomprehensible jumps are the 3 exceptions outlined above.

Many thanks in advance for lightening me up.
Kind regards,
René

--
--
You received this message from the "vim_use" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php

---
You received this message because you are subscribed to the Google Groups "vim_use" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vim_use+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.