misleading information filetype.txt help doc

[rphodges]

Problem

The filetype section (filetype.txt) of the Neovim reference manual references the sourcing of the filetype.vim file in addition to the filetype.lua file. However, this filetype.vim file was removed a couple of years ago. Technically, I suppose this text is correct because the ex_filetype() function does in fact try to load that file even if it doesn't exist in Neovim's distribution. However, I was curious if ex_filetype still sources that file on purpose for backwards compatibility (in case the user has a filetype.vim file in her runtime path). Can we use this opportunity to remove that reference and only source the filetype.lua file.

If we choose to keep sourcing filetype.vim I think it would be more accurate for the Neovim reference manual to explain that Neovim no longer ships with that file but it is still loaded for backwards compatibility in case it exists in the users Neovim runtime path.

Also, one of the primary reasons I'm opening this request is that I thought it was cool that Neovim detected my filetype from a shebang line in a file without an extension. It wasn't clear from the reference manual how this was implemented. I went on this journey to figure it out, was slightly misdirected by the missing filetype.vim file, and then eventually figured out how filetype.lua and vim.filetype.detect implemented this logic.

I'd like to add some missing details to this section of the reference manual like:

1. StdinReadPost, in addition to the BufRead, BufNewFile events, is a third event that the filetype detection function is associated with
2. If the filetype detection function doesn't get hints from the name or extension of the file it will try to determine the filetype from shebang line and lastly from the other contents of the file.
3. The ftdetect/*.{vim,lua} files in the user's runtime path are sourced after the aforementioned autocommand is established.
4. Next an autocmd that sources the the scripts.vim file in the user's runtime path is sourced.

I can write up a proposal for this text that's a little more specific. However, first I wanted some guidance on why the code was still sourcing the filetype.vim file and whether the reference manual should more accurately describe the origin and nature of that file.

Steps to reproduce

N/A

Expected behavior

N/A

Neovim version (nvim -v)

0.10.0

Vim (not Nvim) behaves the same?

N/A

Operating system/version

N/A

Terminal name/version

N/A

$TERM environment variable

N/A

Installation

N/A

[clason]

However, I was curious if ex_filetype still sources that file on purpose for backwards compatibility (in case the user has a filetype.vim file in her runtime path).

Yes, precisely.

And note that this help file is part of the Vim manual, which we only edit for factual, objective inaccuracies. This means that most of these improvements apply to Vim as well and should be made there first.

[rphodges]

For Vim, really the only thing that's missing is a reference to the sourcing of ftdetect/* vimscript files. I'll consider making a proposal to them to include it. It could go into detail about how the scripts.vim uses shebang lines and other file contents to determine the filetype but it's not factually incorrect.

For NeoVim however, the logic for using the shebang line and other contents of the file to detect filetype is all built into filetype.lua rather than a scripts.vim file. It's a much cleaner design.

In Neovim, the scripts.vim and filetype.vim files are really only sourced for backwards compatibility. I'll write up some text that makes this more clear. I'll understand if you really want the manual to stay as close to the Vim reference manual as possible.

[clason]

I'll understand if you really want the manual to stay as close to the Vim reference manual as possible.

That is the general idea, yes. (There are many, many, places in the manual that could be rewritten for Neovim, and we have refrained from doing so until now in order to be able to more easily include documentation improvements from Vim.)