updated documentation issue #1180

[Christian Brabandt]

Bram,
this patch adds the documentation suggestion from #1180 to the manual.
The basic work was done by Gary Johnson, I just improved it a little by
adding it to the TOC.

Best,
Christian
--
Allerhop, der
Das, was passiert, wenn man in einer vollbesetzten U-Bahn: "Verdammt,
wo ist meine Vogelspinne hin?" ruft.
-- Douglas Adams, John Lloyd, Sven Böttcher ("Der tiefere Sinn des Labenz")

[Nikolay Aleksandrovich Pavlov]

2016-10-21 12:32 GMT+03:00 Christian Brabandt <cbl...@256bit.org>:
> Bram,
> this patch adds the documentation suggestion from #1180 to the manual.
> The basic work was done by Gary Johnson, I just improved it a little by
> adding it to the TOC.

This is missing some descriptions regarding what “myfile” is.
Specifically in the example

- myfile was already opened once (no BufNew or BufAdd)
- and is either hidden or displayed in another buffer (no BufNewFile
or BufRead* which would be seen if myfile buffer was unloaded after
opening)

>
> Best,
> Christian
> --
> Allerhop, der
> Das, was passiert, wenn man in einer vollbesetzten U-Bahn: "Verdammt,
> wo ist meine Vogelspinne hin?" ruft.
> -- Douglas Adams, John Lloyd, Sven Böttcher ("Der tiefere Sinn des Labenz")
>

> --
> --
> You received this message from the "vim_dev" 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_dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to vim_dev+u...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Christian Brabandt]

Hi Nikolay!

On Fr, 21 Okt 2016, Nikolay Aleksandrovich Pavlov wrote:

> 2016-10-21 12:32 GMT+03:00 Christian Brabandt <cbl...@256bit.org>:
> > Bram,
> > this patch adds the documentation suggestion from #1180 to the manual.
> > The basic work was done by Gary Johnson, I just improved it a little by
> > adding it to the TOC.
>
> This is missing some descriptions regarding what “myfile” is.
> Specifically in the example
>
> - myfile was already opened once (no BufNew or BufAdd)
> - and is either hidden or displayed in another buffer (no BufNewFile
> or BufRead* which would be seen if myfile buffer was unloaded after
> opening)

So we are missing BufNew, BufAdd and BufReadCmd. So how about this then.

Best,
Christian
--
Computer können nicht denken.
Nur Menschen denken, daß Computer denken.
-- Michael Uhlemann

[Nikolay Aleksandrovich Pavlov]

2016-10-21 13:25 GMT+03:00 Christian Brabandt <cbl...@256bit.org>:
> Hi Nikolay!
>
> On Fr, 21 Okt 2016, Nikolay Aleksandrovich Pavlov wrote:
>
>> 2016-10-21 12:32 GMT+03:00 Christian Brabandt <cbl...@256bit.org>:
>> > Bram,
>> > this patch adds the documentation suggestion from #1180 to the manual.
>> > The basic work was done by Gary Johnson, I just improved it a little by
>> > adding it to the TOC.
>>
>> This is missing some descriptions regarding what “myfile” is.
>> Specifically in the example
>>
>> - myfile was already opened once (no BufNew or BufAdd)
>> - and is either hidden or displayed in another buffer (no BufNewFile
>> or BufRead* which would be seen if myfile buffer was unloaded after
>> opening)
>
> So we are missing BufNew, BufAdd and BufReadCmd. So how about this then.

There are three BufRead commands: BufReadPre, BufReadCmd and
BufReadPost. There also is BufNewFile.

Actually when I open non-existing non-opened file `b` with `tabnew b`
while I have file `a` opened I get

WinLeave 1 a
TabLeave 1 a
WinNew 1 a
WinEnter 1 a
TabNew 1 a
TabEnter 1 a
BufNew 2 b
BufAdd 2 b
BufCreate 2 b
BufLeave 1 a
BufReadCmd 2 b
BufEnter 2 b
BufWinEnter 2 b

(event bufnr bufname). If I use previously unloaded `b`:

WinLeave 1 a
TabLeave 1 a
WinNew 1 a
WinEnter 1 a
TabNew 1 a
TabEnter 1 a
BufLeave 1 a
BufReadCmd 2 b
BufEnter 2 b
BufWinEnter 2 b

. When I use existing file instead (`tabnew /var/log/messages`):

WinLeave 1 a
TabLeave 1 a
WinNew 1 a
WinEnter 1 a
TabNew 1 a
TabEnter 1 a
BufNew 4 messages
BufAdd 4 messages
BufCreate 4 messages
BufLeave 1 a
BufReadCmd 4 messages
BufEnter 4 messages
BufWinEnter 4 messages

. When I use `a` which is opened in the first tab:

WinLeave 1 a
TabLeave 1 a
WinNew 1 a
WinEnter 1 a
TabNew 1 a
TabEnter 1 a
BufEnter 1 a
BufWinEnter 1 a

. When I use `messages` which was previously hidden:

WinLeave 1 a
TabLeave 1 a
WinNew 1 a
WinEnter 1 a
TabNew 1 a
TabEnter 1 a
FileChangedShell 4 messages
BufLeave 1 a
BufEnter 4 messages
BufWinEnter 4 messages

(FileChangedShell is there because I hooked *all* events and
/var/log/messages is a log file which is being written).

When I use `tabnew /var/log/messages` with `messages` buffer wiped
out, but *without* BufReadCmd defined:

WinLeave 1 a
TabLeave 1 a
WinNew 1 a
WinEnter 1 a
TabNew 1 a
TabEnter 1 a
BufNew 5 messages
BufAdd 5 messages
BufCreate 5 messages
BufLeave 1 a
BufReadPre 5 messages
Syntax 5 messages
FileType 5 messages
BufRead 5 messages
BufReadPost 5 messages
BufEnter 5 messages
BufWinEnter 5 messages

Note: you get either BufReadPre+BufReadPost or BufReadCmd (unless
BufReadCmd author had written code so that these events are
intentionally launched with `:doautocmd`). If listing Syntax and
FileType events there should be a remark: it is there because filetype
is detected at BufReadPost and the relevant BufRead event in
`filetypedetect` augroup was defined before my events, not because
Syntax and FileType are generally run before BufReadPost.

Basically to test I use the following one-liners:

1. In a helpfile, after selecting a toc with autocmd events:

let d={}|'<,'>g/^|\(\w\+\)|/let d[matchstr(getline('.'),
'^|\zs\w\+')] = 1

. Created dictionary

{'BufRead': 1, 'FocusLost': 1, 'TabEnter': 1,
'EncodingChanged': 1, 'InsertLeave': 1, 'BufWinEnter': 1,
'FileWritePre': 1, 'FileWriteCmd': 1, 'FileAppendCmd': 1,
'CmdwinLeave': 1, 'GUIEnter': 1, 'StdinReadPost': 1, 'FileAppendPost':
1, 'RemoteReply': 1, 'TermChanged': 1, 'CompleteDone': 1,
'FileChangedRO': 1, 'BufLeave': 1, 'Syntax': 1, 'SourcePre': 1,
'InsertCharPre': 1, 'FuncUndefined': 1, 'BufFilePost': 1, 'BufUnload':
1, 'FilterWritePre': 1, 'BufAdd': 1, 'ShellFilterPost': 1,
'TabClosed': 1, 'InsertEnter': 1, 'OptionSet': 1, 'CmdUndefined': 1,
'InsertChange': 1, 'MenuPopup': 1, 'BufDelete': 1, 'VimLeave': 1,
'FileReadPost': 1, 'CmdwinEnter': 1, 'CursorMovedI': 1, 'BufWritePre':
1, 'BufWriteCmd': 1, 'FocusGained': 1, 'GUIFailed': 1, 'BufWritePost':
1, 'BufNew': 1, 'SessionLoadPost': 1, 'BufWrite': 1, 'CursorMoved': 1,
'VimLeavePre': 1, 'FileType': 1, 'BufEnter': 1, 'TabLeave': 1,
'QuickFixCmdPre': 1, 'TextChangedI': 1, 'WinEnter': 1, 'StdinReadPre':
1, 'FileChangedShell': 1, 'FileReadPre': 1, 'FileReadCmd': 1,
'VimResized': 1, 'FilterReadPost': 1, 'TabNew': 1, 'QuickFixCmdPost':
1, 'TextChanged': 1, 'WinLeave': 1, 'FileChangedShellPost': 1,
'FilterReadPre': 1, 'VimEnter': 1, 'BufWinLeave': 1, 'BufReadPre': 1,
'BufReadCmd': 1, 'BufWipeout': 1, 'BufFilePre': 1, 'SwapExists': 1,
'ShellCmdPost': 1, 'QuitPre': 1, 'CursorHold': 1, 'WinNew': 1,
'SourceCmd': 1, 'CursorHoldI': 1, 'User': 1, 'BufHidden': 1,
'BufNewFile': 1, 'BufReadPost': 1, 'BufCreate': 1, 'SpellFileMissing':
1, 'TermResponse': 1, 'ColorScheme': 1, 'FileWritePost': 1,
'FileAppendPre': 1, 'FilterWritePost': 1}

which was then saved to a file for future reference.

(Also do not forget: BufAdd and BufCreate, and BufRead and
BufReadPost are aliases, but here they appear separately.)
2. With this dictionary saved into `aue` (actually I used the saved
file, not original `d`):

let g:auevents_log = []|exe 'augroup Events'|exe 'autocmd!'|for
k in keys(aue)|exe 'autocmd' k '*' ':call add(g:auevents_log, {"evt":
'.string(k).', "match": expand("<amatch>"), "buf":
expand("<abuf>")})'|endfor|augroup END

3. To print the results:

for e in g:auevents_log | echo e.evt e.buf
fnamemodify(e.match, ":t") | endfor

4. And, of course, after copying these results here before proceeding
to the next test:

let g:auevents_log = []

>
> Best,
> Christian
> --
> Computer können nicht denken.
> Nur Menschen denken, daß Computer denken.
> -- Michael Uhlemann
>

[Bram Moolenaar]

Christian Brabandt wrote:

> Bram,
> this patch adds the documentation suggestion from #1180 to the manual.
> The basic work was done by Gary Johnson, I just improved it a little by
> adding it to the TOC.

I thought I already mentioned this: I think it's better to explain this
with the command, instead of having some sequences in autocmd.txt. The
idea is that you are explaining what the command is doing.

It's probably best to specify the order of autocmd events. Some may not
always be triggered (e.g., when a buffer was hidden). That is something
that needs to be explained with the autocommand, not repeating it in
every place where it might be triggered.


--
Communication is one of the most compli..., eh, well, it's hard.
You know what I mean. Not?

/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///

[Christian Brabandt]

Hi Bram!

On Fr, 21 Okt 2016, Bram Moolenaar wrote:

> I thought I already mentioned this: I think it's better to explain this
> with the command, instead of having some sequences in autocmd.txt. The
> idea is that you are explaining what the command is doing.

I am not sure I follow. You mean to add the sequences to every command
that edits a new file (:tabedit, :new, :sp :argedit, :pedit, ...)?

Wouldn't that add possibly the same info at way to many places?

I would rather have this at autocmd.txt at least in the beginning.
Later, if we have examples for all different commands, we can move it to
a different place.

> It's probably best to specify the order of autocmd events. Some may not
> always be triggered (e.g., when a buffer was hidden). That is something
> that needs to be explained with the autocommand, not repeating it in
> every place where it might be triggered.

I tend to agree, however since there are so different autocommands, I
think to have a sample for e.g. tabedit makes sense, since it is not
always obvious, in what order the different autocommands are executed.

Best,
Christian
--
Der Undank ist immer eine Art Schwäche. Ich habe nie gesehen, daß
tüchtige Menschen undankbar gewesen wären.
-- Johann Wolfgang von Goethe

[Bram Moolenaar]

Christian Brabandt wrote:

> On Fr, 21 Okt 2016, Bram Moolenaar wrote:
>
> > I thought I already mentioned this: I think it's better to explain this
> > with the command, instead of having some sequences in autocmd.txt. The
> > idea is that you are explaining what the command is doing.
>
> I am not sure I follow. You mean to add the sequences to every command
> that edits a new file (:tabedit, :new, :sp :argedit, :pedit, ...)?
>
> Wouldn't that add possibly the same info at way to many places?

But it's not the same info. Perhaps if some sequences are in common,
e.g., when editing a new file in a window, those can be referred to.

> I would rather have this at autocmd.txt at least in the beginning.
> Later, if we have examples for all different commands, we can move it to
> a different place.
>
> > It's probably best to specify the order of autocmd events. Some may not
> > always be triggered (e.g., when a buffer was hidden). That is something
> > that needs to be explained with the autocommand, not repeating it in
> > every place where it might be triggered.
>
> I tend to agree, however since there are so different autocommands, I
> think to have a sample for e.g. tabedit makes sense, since it is not
> always obvious, in what order the different autocommands are executed.

With the autocommand you can only explain the simple parts, such as
whether BufEnter comes before or after BufReadPost.

Currently it's a bit of a puzzle, I guess most plugin writers just try
it out and see what happens.

--
An SQL statement walks into a bar. He approaches two tables
and says, "Mind if I join you?"