Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add vim syntax modeline [RFC] #1874

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Conversation

hickford
Copy link
Contributor

@hickford hickford commented Jan 13, 2025

cc: "brian m. carlson" sandals@crustytoothpaste.net
cc: "D. Ben Knoble" ben.knoble@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.

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

A simpler alternative could be to rename files *.adoc. This would have
the advantage of being recognised by even more tools.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
@hickford
Copy link
Contributor Author

/submit

Copy link

Submitted as pull.1874.git.git.1736802194760.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-git-1874/hickford/asciidoc-v1

To fetch this version to local tag pr-git-1874/hickford/asciidoc-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-git-1874/hickford/asciidoc-v1

Copy link

On the Git mailing list, "brian m. carlson" wrote (reply to this):

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.
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

Copy link

User "brian m. carlson" <sandals@crustytoothpaste.net> has been added to the cc: list.

Copy link

On the Git mailing list, "D. Ben Knoble" wrote (reply to this):

On Mon, Jan 13, 2025 at 4:05 PM M Hickford via GitGitGadget
<gitgitgadget@gmail.com> 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.

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

Copy link

User "D. Ben Knoble" <ben.knoble@gmail.com> has been added to the cc: list.

Copy link

On the Git mailing list, M Hickford wrote (reply to this):

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

Copy link

On the Git mailing list, Junio C Hamano wrote (reply to this):

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

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

Sounds quite sensible.

Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant