docs: deprecate <sfile>

runtime/doc/autocmd.txt

@@ -78,6 +78,9 @@ exception is that "<sfile>" is expanded when the autocmd is defined.  Example:
 	:au BufNewFile,BufRead *.html so <sfile>:h/html.vim
 
 Here Vim expands <sfile> to the name of the file containing this line.
+Use <script> instead to avoid that: >
+
+	:au BufNewFile,BufRead *.html so <script>:h/html.vim
 
 `:autocmd` adds to the list of autocommands regardless of whether they are
 already present.  When your .vimrc file is sourced twice, the autocommands
@@ -87,7 +90,7 @@ that you can easily clear them: >
 	augroup vimrc
 	  " Remove all vimrc autocommands
 	  autocmd!
-	  au BufNewFile,BufRead *.html so <sfile>:h/html.vim
+	  au BufNewFile,BufRead *.html so <script>:h/html.vim
 	augroup END
 
 If you don't want to remove all autocommands, you can instead use a variable

runtime/doc/cmdline.txt

@@ -937,14 +937,6 @@ Note: these are typed literally, they are not special keys!
 		   events).
 		   When the match is with a file name, it is expanded to the
 		   full path.
-							*:<sfile>* *<sfile>*
-	<sfile>    When executing a `:source` command, is replaced with the
-		   file name of the sourced file.  *E498*
-		   When executing a function, is replaced with the call stack,
-		   as with <stack> (this is for backwards compatibility, using
-		   <stack> or <script> is preferred).
-		   Note that filename-modifiers are useless when <sfile> is
-		   not used inside a script.
 							*:<stack>* *<stack>*
 	<stack>	   is replaced with the call stack, using
 		   "function {function-name}[{lnum}]" for a function line
@@ -952,7 +944,7 @@ Note: these are typed literally, they are not special keys!
 		   ".." in between items.  E.g.:
 		   "function {function-name1}[{lnum}]..{function-name2}[{lnum}]"
 		   If there is no call stack you get error *E489* .
-							*:<script>* *<script>*
+							*:<script>* *<script>* *E498*
 	<script>   When executing a `:source` command, is replaced with the file
 		   name of the sourced file.  When executing a function, is
 		   replaced with the file name of the script where it is
@@ -971,7 +963,7 @@ Note: these are typed literally, they are not special keys!
 							 *filename-modifiers*
 *:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* *::S*
      *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* *%:S*
-The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>",
+The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<script>",
 "<afile>" or "<abuf>".  They are also used with the |fnamemodify()| function.
 These modifiers can be given, in this order:
 	:p	Make file name a full path.  Must be the first modifier.  Also

runtime/doc/deprecated.txt

@@ -330,13 +330,12 @@ UI EXTENSIONS
 • *term_background*	Unused. The terminal background color is now detected
 			by the Nvim core directly instead of the TUI.
 
-VARIABLES
+VIMSCRIPT
+• *<sfile>*		Use |<script>| or |<stack>| instead.
 • *b:terminal_job_pid*	Use `jobpid(&channel)` instead.
 • *b:terminal_job_id*	Use `&channel` instead. To access in non-current buffer:
 			• Lua: `vim.bo[bufnr].channel`
 			• Vimscript: `getbufvar(bufnr, '&channel')`
-
-VIMSCRIPT
 • *buffer_exists()*	Obsolete name for |bufexists()|.
 • *buffer_name()*	Obsolete name for |bufname()|.
 • *buffer_number()*	Obsolete name for |bufnr()|.

runtime/doc/quickref.txt

@@ -1112,10 +1112,10 @@ Context-sensitive completion on the command-line:
 			   expected) (see |WORD|)
 |:<cfile>|  <cfile>	file name under the cursor (only where a file name is
 			   expected)
-|:<sfile>|  <sfile>	file name of a ":source"d file, within that file (only
+|:<script>| <script>	file name of a ":source"d file, within that file (only
 			   where a file name is expected)
 
-		After "%", "#", "<cfile>", "<sfile>" or "<afile>"
+		After "%", "#", "<cfile>", "<script>" or "<afile>"
 		|::p|	    :p		full path
 		|::h|	    :h		head (file name removed)
 		|::t|	    :t		tail (file name only)

runtime/doc/repeat.txt

@@ -413,12 +413,12 @@ make a top-down hierarchy of script files.  The ':source' command can be
 nested as deep as the number of files that can be opened at one time (about
 15).  The ':source!' command can be nested up to 15 levels deep.
 
-You can use the "<sfile>" string (literally, this is not a special key) inside
+You can use the "<script>" string (literally, this is not a special key) inside
 of the sourced file, in places where a file name is expected.  It will be
 replaced by the file name of the sourced file.  For example, if you have a
 "other.vimrc" file in the same directory as your |init.vim| file, you can
 source it from your |init.vim| file with this command: >
-	:source <sfile>:h/other.vimrc
+	:source <script>:h/other.vimrc
 
 In script files terminal-dependent key codes are represented by
 terminal-independent two character codes.  This means that they can be used

runtime/doc/syntax.txt

@@ -4616,11 +4616,11 @@ two different ways:
 	  that list. >
 
    " In perl.vim:
-   :syntax include @Pod <sfile>:p:h/pod.vim
+   :syntax include @Pod <script>:p:h/pod.vim
    :syntax region perlPOD start="^=head" end="^=cut" contains=@Pod
 <
 	  When {file-name} is an absolute path (starts with "/", "c:", "$VAR"
-	  or "<sfile>") that file is sourced.  When it is a relative path
+	  or "<script>") that file is sourced.  When it is a relative path
 	  (e.g., "syntax/pod.vim") the file is searched for in 'runtimepath'.
 	  All matching files are loaded.  Using a relative path is
 	  recommended, because it allows a user to replace the included file

runtime/doc/usr_41.txt

@@ -2556,7 +2556,7 @@ The following example shows how it's done: >
 		map <F19> :call BufNetWrite('something')<CR>
 
 		let s:did_load = 1
-		exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>')
+		exe 'au FuncUndefined BufNet* source ' .. expand('<script>')
 		finish
 	endif
 
@@ -2592,7 +2592,7 @@ startup.  This is the sequence of events that happens:
    event.  Since the pattern "BufNet*" matches the invoked function, the
    command "source fname" will be executed.  "fname" will be equal to the name
    of the script, no matter where it is located, because it comes from
-   expanding "<sfile>" (see |expand()|).
+   expanding "<script>" (see |expand()|).
 
 4. The script is sourced again, the "s:did_load" variable exists and the
    functions are defined.

runtime/doc/usr_44.txt

@@ -511,7 +511,7 @@ syntax file.  The ":syntax include" command reads in a syntax file and stores
 the elements it defined in a syntax cluster.  For Perl, the statements are as
 follows: >
 
-	:syntax include @Pod <sfile>:p:h/pod.vim
+	:syntax include @Pod <script>:p:h/pod.vim
 	:syntax region perlPOD start=/^=head/ end=/^=cut/ contains=@Pod
 
 When "=head" is found in a Perl file, the perlPOD region starts.  In this
@@ -522,7 +522,7 @@ region ends and we go back to the items defined in the Perl file.
 command in the included file.  And an argument such as "contains=ALL" will
 only contain items defined in the included file, not in the file that includes
 it.
-   The "<sfile>:p:h/" part uses the name of the current file (<sfile>),
+   The "<script>:p:h/" part uses the name of the current file (<script>),
 expands it to a full path (:p) and then takes the head (:h).  This results in
 the directory name of the file.  This causes the pod.vim file in the same
 directory to be included.

runtime/doc/vimfn.txt

@@ -2106,7 +2106,7 @@ expand({string} [, {nosuf} [, {list}]])                               *expand()*
 			<abuf>		autocmd buffer number (as a String!)
 			<amatch>	autocmd matched name
 			<cexpr>		C expression under the cursor
-			<sfile>		sourced script file or function name
+			<sfile>		deprecated, use <script> or <stack>
 			<slnum>		sourced script line number or function
 					line number
 			<sflnum>	script file line number, also when in

runtime/lua/vim/_meta/vimfn.lua

@@ -1863,7 +1863,7 @@ function vim.fn.exp(expr) end
 ---   <abuf>    autocmd buffer number (as a String!)
 ---   <amatch>  autocmd matched name
 ---   <cexpr>    C expression under the cursor
----   <sfile>    sourced script file or function name
+---   <sfile>    deprecated, use <script> or <stack>
 ---   <slnum>    sourced script line number or function
 ---       line number
 ---   <sflnum>  script file line number, also when in

src/nvim/eval.lua

@@ -2413,7 +2413,7 @@ M.funcs = {
       	<abuf>		autocmd buffer number (as a String!)
       	<amatch>	autocmd matched name
       	<cexpr>		C expression under the cursor
-      	<sfile>		sourced script file or function name
+      	<sfile>		deprecated, use <script> or <stack>
       	<slnum>		sourced script line number or function
       			line number
       	<sflnum>	script file line number, also when in