Improve implications of autocmd! in docs

[fxn]

If you put autocmd! in ~/.vimrc after syntax on, you get no syntax highlighting.

A posteriori, this is telling me that the :syntax command has autocommands going on behind the scenes, but this is not obvious to the user. As a user, your interface is the command itself.

Don't know enough Vim to contribute a patch that properly documents whatever needs to be documented to cover this gotcha, but at least I wanted to report it.

[jamessan]

If you're calling autocmd! outside of an augroup, then you're deleting ALL autocmds. Most likely, you want to define an augroup to contain your own autocmds, and the first line in the augroup is autocmd!.

augroup fxn
    autocmd!
    " Define the autocmds you want
augroup END

[fxn]

I use it at the top-level. My use case is being able to source ~/.vimrc several times from within Vim. This is a use case documented in the help for :autocmd.

I don't want to scope my autocommands, nor do I want to set a flag, the usage as documented is what I prefer for its simplicity.

The problem here is that :syntax on reads as "enable syntax highlighting", but it has (I guess) autocommands in its implementation. So there is a coupling going on here that in my view the docs should explain somehow.

[fxn]

Let me quote:

When your .vimrc file is sourced twice, the autocommands will appear twice.
To avoid this, put this command in your .vimrc file, before defining
autocommands:

    :autocmd!   " Remove ALL autocommands for the current group.

That is what I did, I put the call before my autocommands, but after :syntax on.

[chrisbra]

Okay, how about a documentation patch then?

[fxn]

Yeah, I'd be glad to contribute one, but I don't have the perspective to document Vim.

• I am facing just a particular case with :syntax on that deserves a generic note in :autocmd! docs?
• Is this an edge-case mostly affecting :syntax and should this be an implementation detail made public in :syntax docs?
• Should the docs document as good practice to put your autocmds in a group in such case?
• Etc.

In summary, I am not qualified to write Vim documentation.

[vim-ml]

On Sep 26, 2016 19:51, "Xavier Noria" vim-dev-github@256bit.org wrote:

Let me quote:

When your .vimrc file is sourced twice, the autocommands will appear
twice. To avoid this, put this command in your .vimrc file, before defining
autocommands: > :autocmd! " Remove ALL autocommands for the current group.

Note the "current group" phrase. If you don't scope with an augroup then
all kinds of things will break, including filetype detection and netrw.

---

Justin M. Keyes

[fxn]

@vim-ml so is it the case that a top-level syntax on and other commmon builtin stuff is (or should be) implemented in a way that re-evaluation is idempotent, and the best practice for your own autocommands is to use the augroup?

[brammool]

Xavier Noria wrote:

Let me quote:

When your .vimrc file is sourced twice, the autocommands will appear twice.
To avoid this, put this command in your .vimrc file, before defining
autocommands: >

  :autocmd!   " Remove ALL autocommands for the current group.

That is what I did, I put the call before my autocommands, but after
:syntax on.

That example is incomplete, it should mention using a group to only
deleted what you define. This should be better:

augroup vimrc
  autocmd!  " Remove all vimrc autocommands
  au BufNewFile,BufRead *.html so <sfile>:h/html.vim
augroup END

GUARD #1: What -- a swallow carrying a coconut?
ARTHUR: It could grip it by the husk!
GUARD #1: It's not a question of where he grips it! It's a simple question
of weight ratios! A five ounce bird could not carry a 1 pound
coconut.
The Quest for the Holy Grail (Monty Python)

/// Bram Moolenaar -- Bram@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 ///

[fxn]

@brammool awesome, let me write a patch then.

[chrisbra]

i think this can be closed.