Don't use VimEnter initialization except when stating gui

This is another attempt at:

https://github.com/Valloric/YouCompleteMe/pull/2473

Which removed the apparently flawed attempt at "lazy" loading of YCM.
While it fails to get the load out of the critical startup path, it
*does* serve the useful purpose when starting up gvim of avoiding a
deadlock situation in gvim.

So, this time, we keep VimEnter, but only for the gui-starting case. We
update the comment to explain what is actually happening. And we can
keep the docs about how to defer loading.

README.md

@@ -2882,6 +2882,19 @@ executable first in your PATH when the virtual environment is active then if
 you set `g:ycm_python_binary_path` to just `'python'` it will be found as the
 first Python and used to run [JediHTTP][].
 
+### I want to defer loading of YouCompleteMe until after Vim finishes booting
+
+In recent versions of Vim, you can install YCM in a folder under
+`~/.vim/pack/*/opt` and then load it once the user is idle via an autocommand:
+
+```viml
+augroup load_ycm
+  autocmd!
+  autocmd CursorHold, CursorHoldI * :packadd YouCompleteMe
+                                \ | autocmd! load_ycm
+augroup END
+```
+
 Contributor Code of Conduct
 ---------------------------
 

plugin/youcompleteme.vim

@@ -128,14 +128,15 @@ let g:ycm_goto_buffer_command =
 let g:ycm_disable_for_files_larger_than_kb =
       \ get( g:, 'ycm_disable_for_files_larger_than_kb', 1000 )
 
-" On-demand loading. Let's use the autoload folder and not slow down vim's
+if has( 'vim_starting' ) && has ( 'gui' ) " loading at startup, in gui
-" startup procedure.
+  " We defer loading until after VimEnter to allow the gui to fork (see
-if has( 'vim_starting' ) " loading at startup
+  " `:h gui-fork`) and avoid a deadlock situation, as explained here:
+  " https://github.com/Valloric/YouCompleteMe/pull/2473#issuecomment-267716136
   augroup youcompletemeStart
     autocmd!
     autocmd VimEnter * call youcompleteme#Enable()
   augroup END
-else " manual loading with :packadd
+else " manual loading with :packadd, or not starting the gui
   call youcompleteme#Enable()
 endif