On Mon, Jan 13, 2025 at 4:05 PM M Hickford via GitGitGadget
<gitgitgadget@xxxxxxxxx> 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.
FWIW, Vim by default only has a single autocommand for *.txt files,
and it's to see if they are help files.
Now, there is a fallback $VIMRUNTIME/scripts.vim mechanism that
performs various "heuristic" checks, but I can't find a reference to
markdown in it either. So stock Vim treats them as "filetype=text."
>
> This makes editing the documentation easier for prospective
> contributors. This is particularly important because new contributors
> often start with documentation changes.
>
> An alternative could be to move the modeline up or down the file (the
> location is not important).
Not quite. :help modeline says
The number of lines that are checked can be set with the 'modelines' option.
If 'modeline' is off or 'modelines' is 0 no lines are checked.
and the default value of 'modelines' is 5.
>
> A simpler alternative could be to rename files *.adoc. This would have
> the advantage of being recognised by even more tools.
Indeed, Vim knows that *.adoc and *.asciidoc are "filetype=asciidoc".
You could also see about submitting a patch to Vim to check *.txt
files for asciidoc syntax, or add your own ftdetect rules [1] that say
that files with %:p matching "git.*/Documentation" (for example) get
the filetype asciidoc.
[1]: https://vi.stackexchange.com/a/23251/10604,
https://vi.stackexchange.com/a/18493/10604,
https://vi.stackexchange.com/a/28109/10604, etc.
--
D. Ben Knoble
