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

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Jan 13, 2025, 22:37 UTC
Message-ID: <CALnO6CCLhsQbkC6nsaeiFDksbh_UAxC9igFD3r5V1Bz+YLyWaw@mail.gmail.com>
In-Reply-To: <pull.1874.git.git.1736802194760.gitgitgadget@gmail.com>

On Mon, Jan 13, 2025 at 4:05 PM M Hickford via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 8 quoted lines

>
> 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.

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."

Show 7 quoted lines

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