Re: [PATCH] docs: add vim syntax modeline [RFC]

> On 2025-01-13 at 21:03:14, M Hickford via GitGitGadget wrote:
>> From: M Hickford <mirth.hickford@gmail.com>
>>
>> Git documentation is written in AsciiDoc. This format is easily
>> mistaken for the pervasive Markdown.
>>
>> Add a vim modeline to help editors identify the format and provide
>> syntax highlighting, rendering and autocomplete.
> 
> I don't think this is a good idea.  To be clear, I use Vim and Neovim
> (mostly the latter), but I just don't think we should litter our project
> with editor-specific contents.  I know Junio uses Emacs, and other
> contributors use other things, and there's no uniform syntax that works
> everywhere.  (Nor could there be, because different editors have
> different names for different languages.)
> 
> We also don't set editor-specific ignore files in our `.gitignore`.
> Emacs users are responsible for ignoring backup files in the global
> (per-user) config, Vim users for swap files, and so on.
> 
>> This makes editing the documentation easier for prospective
>> contributors. This is particularly important because new contributors
>> often start with documentation changes.
> 
> I suspect prospective contributors who are moderately proficient with
> Vim and its descendants know how to do `:setf asciidoc`.  If this were a
> different editor that were easier to start with (say, one that didn't
> have tons of Internet posts asking how to quit it), such as VS Code or
> even Emacs, then I would be more convinced by this argument.
> 
>> A simpler alternative could be to rename files *.adoc. This would have
>> the advantage of being recognised by even more tools.
> 
> This I would be in favour of.  I use this extension on my personal
> AsciiDoc files and already have appropriate configuration set up.  In
> conjunction with appropriate settings in our `.editorconfig` file (to
> configure indents properly), I think this would be valuable indeed, and,
> importantly, helpful to users of all editors.