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@xxxxxxxxx>
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
