From: M Hickford <mirth.hickford@gmail.com>
Date: Mon, 13 Jan 2025 22:50:52 GMT
Subject: Re: [PATCH] docs: add vim syntax modeline [RFC]
Message-ID: <2c43a19c-91b7-45d4-bf95-3157ddfe81d0@gmail.com>
In-Reply-To: <Z4WGwCwnNj_XeHiI@tapette.crustytoothpaste.net>

On 2025-01-13 21:33, brian m. carlson wrote:
> 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.

The more I think about it, I prefer renaming to *.adoc too. It's easy to 
identify and obviously distinct from Markdown. GitHub and GitLab render 
adoc files beautifully [1][2]. Visual Studio Code offers to install an 
extension with syntax highlighting and previewing.

The vim modeline had no effect in Visual Studio Code. It could also be 
intimidating.

[1] 
https://github.com/couchbase-guides/how-to-write-a-guide/blob/master/README.adoc
[2] https://docs.gitlab.com/ee/user/asciidoc.html