From fcf5dd34fdfde3a6632b96a88f66c1053cba08d1 Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Mon, 17 Jan 2022 14:11:59 -0700
Subject: refactor: enable filetype detection before user startup scripts
 (#17040)

---
 runtime/doc/starting.txt | 20 +++++++++++---------
 runtime/doc/vim_diff.txt |  8 ++++++--
 2 files changed, 17 insertions(+), 11 deletions(-)

(limited to 'runtime')

diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index bb775ec884..7c4b684ca4 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -409,7 +409,17 @@ accordingly, proceeding as follows:
 
 4. Setup |default-mappings| and  |default-autocmds|.
 
-5. Load user config (execute Ex commands from files, environment, …).
+5. Enable filetype and indent plugins.
+	This does the same as the command: >
+		:filetype plugin indent on
+<	which in turn is equivalent to: >
+		:runtime! filetype.lua
+		:runtime! filetype.vim
+		:runtime! ftplugin.vim
+		:runtime! indent.vim
+<	Skipped if the "-u NONE" command line argument was given.
+
+6. Load user config (execute Ex commands from files, environment, …).
 	$VIMINIT environment variable is read as one Ex command line (separate
 	multiple commands with '|' or <NL>).
 					*config* *init.vim* *init.lua* *vimrc* *exrc*
@@ -453,14 +463,6 @@ accordingly, proceeding as follows:
 	-  The file ".nvimrc"
 	-  The file ".exrc"
 
-6. Enable filetype and indent plugins.
-	This does the same as the commands: >
-		:runtime! filetype.vim
-		:runtime! ftplugin.vim
-		:runtime! indent.vim
-<	Skipped if ":filetype … off" was called or if the "-u NONE" command
-	line argument was given.
-
 7. Enable syntax highlighting.
 	This does the same as the command: >
 		:runtime! syntax/syntax.vim
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 4fcaf15717..32a97779e0 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -23,8 +23,12 @@ centralized reference of the differences.
 ==============================================================================
 2. Defaults					            *nvim-defaults*
 
-- Syntax highlighting is enabled by default
-- ":filetype plugin indent on" is enabled by default
+- ":filetype plugin indent on" is enabled by default. This runs before
+  init.vim is sourced so that FileType autocommands in init.vim run after
+  those in filetype.vim.
+- Syntax highlighting is enabled by default. This runs after init.vim is
+  sourced so that users can optionally disable syntax highlighting with
+  ":syntax off".
 
 - 'autoindent' is enabled
 - 'autoread' is enabled
-- 
cgit