{"thread":{"id":"62799","subject":"[PATCH] docs: add vim syntax modeline [RFC]","startedAt":"2025-01-13T21:03:17Z","lastAt":"2025-01-16T18:56:13Z","messageCount":6,"participants":["M Hickford via GitGitGadget","brian m. carlson","D. Ben Knoble","M Hickford","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"510452","messageId":"pull.1874.git.git.1736802194760.gitgitgadget@gmail.com","threadId":"62799","inReplyTo":null,"subject":"[PATCH] docs: add vim syntax modeline [RFC]","fromName":"M Hickford via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-01-13T21:03:14Z","receivedAt":"2025-01-13T21:03:17Z","isPatch":true,"sender":{"key":"mirth.hickford@gmail.com","avatar":"https://avatars.githubusercontent.com/u/105314?v=4"},"body":"From: M Hickford \n\nGit documentation is written in AsciiDoc. This format is easily\nmistaken for the pervasive Markdown.\n\nAdd a vim modeline to help editors identify the format and provide\nsyntax highlighting, rendering and autocomplete.\n\nThis makes editing the documentation easier for prospective\ncontributors. This is particularly important because new contributors\noften start with documentation changes.\n\nAn alternative could be to move the modeline up or down the file (the\nlocation is not important).\n\nA simpler alternative could be to rename files *.adoc. This would have\nthe advantage of being recognised by even more tools.\n\nSigned-off-by: M Hickford \n---\n docs: add vim syntax modeline [RFC]\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1874%2Fhickford%2Fasciidoc-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1874/hickford/asciidoc-v1\nPull-Request: https://github.com/git/git/pull/1874\n\n Documentation/git-add.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 5f2c3592b8d..123c98541b1 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -1,5 +1,6 @@\n git-add(1)\n ==========\n+// vim: syntax=asciidoc\n \n NAME\n ----\n\nbase-commit: fbe8d3079d4a96aeb4e4529cc93cc0043b759a05\n-- \ngitgitgadget\n"},{"id":"510454","messageId":"Z4WGwCwnNj_XeHiI@tapette.crustytoothpaste.net","threadId":"62799","inReplyTo":"pull.1874.git.git.1736802194760.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: add vim syntax modeline [RFC]","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-01-13T21:33:52Z","receivedAt":"2025-01-13T21:33:56Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2025-01-13 at 21:03:14, M Hickford via GitGitGadget wrote:\n> From: M Hickford \n> \n> Git documentation is written in AsciiDoc. This format is easily\n> mistaken for the pervasive Markdown.\n> \n> Add a vim modeline to help editors identify the format and provide\n> syntax highlighting, rendering and autocomplete.\n\nI don't think this is a good idea. To be clear, I use Vim and Neovim\n(mostly the latter), but I just don't think we should litter our project\nwith editor-specific contents. I know Junio uses Emacs, and other\ncontributors use other things, and there's no uniform syntax that works\neverywhere. (Nor could there be, because different editors have\ndifferent names for different languages.)\n\nWe also don't set editor-specific ignore files in our `.gitignore`.\nEmacs users are responsible for ignoring backup files in the global\n(per-user) config, Vim users for swap files, and so on.\n\n> This makes editing the documentation easier for prospective\n> contributors. This is particularly important because new contributors\n> often start with documentation changes.\n\nI suspect prospective contributors who are moderately proficient with\nVim and its descendants know how to do `:setf asciidoc`. If this were a\ndifferent editor that were easier to start with (say, one that didn't\nhave tons of Internet posts asking how to quit it), such as VS Code or\neven Emacs, then I would be more convinced by this argument.\n\n> A simpler alternative could be to rename files *.adoc. This would have\n> the advantage of being recognised by even more tools.\n\nThis I would be in favour of. I use this extension on my personal\nAsciiDoc files and already have appropriate configuration set up. In\nconjunction with appropriate settings in our `.editorconfig` file (to\nconfigure indents properly), I think this would be valuable indeed, and,\nimportantly, helpful to users of all editors.\n-- \nbrian m. carlson (they/them or he/him)\nToronto, Ontario, CA\n"},{"id":"510459","messageId":"CALnO6CCLhsQbkC6nsaeiFDksbh_UAxC9igFD3r5V1Bz+YLyWaw@mail.gmail.com","threadId":"62799","inReplyTo":"pull.1874.git.git.1736802194760.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: add vim syntax modeline [RFC]","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-01-13T22:37:55Z","receivedAt":"2025-01-13T22:38:08Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Jan 13, 2025 at 4:05 PM M Hickford via GitGitGadget\n wrote:\n>\n> From: M Hickford \n>\n> Git documentation is written in AsciiDoc. This format is easily\n> mistaken for the pervasive Markdown.\n>\n> Add a vim modeline to help editors identify the format and provide\n> syntax highlighting, rendering and autocomplete.\n\nFWIW, Vim by default only has a single autocommand for *.txt files,\nand it's to see if they are help files.\n\nNow, there is a fallback $VIMRUNTIME/scripts.vim mechanism that\nperforms various \"heuristic\" checks, but I can't find a reference to\nmarkdown in it either. So stock Vim treats them as \"filetype=text.\"\n\n>\n> This makes editing the documentation easier for prospective\n> contributors. This is particularly important because new contributors\n> often start with documentation changes.\n>\n> An alternative could be to move the modeline up or down the file (the\n> location is not important).\n\nNot quite. :help modeline says\n\n The number of lines that are checked can be set with the 'modelines' option.\n If 'modeline' is off or 'modelines' is 0 no lines are checked.\n\nand the default value of 'modelines' is 5.\n\n>\n> A simpler alternative could be to rename files *.adoc. This would have\n> the advantage of being recognised by even more tools.\n\nIndeed, Vim knows that *.adoc and *.asciidoc are \"filetype=asciidoc\".\n\nYou could also see about submitting a patch to Vim to check *.txt\nfiles for asciidoc syntax, or add your own ftdetect rules [1] that say\nthat files with %:p matching \"git.*/Documentation\" (for example) get\nthe filetype asciidoc.\n\n[1]: https://vi.stackexchange.com/a/23251/10604,\nhttps://vi.stackexchange.com/a/18493/10604,\nhttps://vi.stackexchange.com/a/28109/10604, etc.\n\n-- \nD. Ben Knoble\n"},{"id":"510460","messageId":"2c43a19c-91b7-45d4-bf95-3157ddfe81d0@gmail.com","threadId":"62799","inReplyTo":"Z4WGwCwnNj_XeHiI@tapette.crustytoothpaste.net","subject":"Re: [PATCH] docs: add vim syntax modeline [RFC]","fromName":"M Hickford","fromEmail":"mirth.hickford@gmail.com","sentAt":"2025-01-13T22:50:52Z","receivedAt":"2025-01-13T22:51:03Z","isPatch":true,"sender":{"key":"mirth.hickford@gmail.com","avatar":"https://avatars.githubusercontent.com/u/105314?v=4"},"body":"On 2025-01-13 21:33, brian m. carlson wrote:\n> On 2025-01-13 at 21:03:14, M Hickford via GitGitGadget wrote:\n>> From: M Hickford \n>>\n>> Git documentation is written in AsciiDoc. This format is easily\n>> mistaken for the pervasive Markdown.\n>>\n>> Add a vim modeline to help editors identify the format and provide\n>> syntax highlighting, rendering and autocomplete.\n> \n> I don't think this is a good idea. To be clear, I use Vim and Neovim\n> (mostly the latter), but I just don't think we should litter our project\n> with editor-specific contents. I know Junio uses Emacs, and other\n> contributors use other things, and there's no uniform syntax that works\n> everywhere. (Nor could there be, because different editors have\n> different names for different languages.)\n> \n> We also don't set editor-specific ignore files in our `.gitignore`.\n> Emacs users are responsible for ignoring backup files in the global\n> (per-user) config, Vim users for swap files, and so on.\n> \n>> This makes editing the documentation easier for prospective\n>> contributors. This is particularly important because new contributors\n>> often start with documentation changes.\n> \n> I suspect prospective contributors who are moderately proficient with\n> Vim and its descendants know how to do `:setf asciidoc`. If this were a\n> different editor that were easier to start with (say, one that didn't\n> have tons of Internet posts asking how to quit it), such as VS Code or\n> even Emacs, then I would be more convinced by this argument.\n> \n>> A simpler alternative could be to rename files *.adoc. This would have\n>> the advantage of being recognised by even more tools.\n> \n> This I would be in favour of. I use this extension on my personal\n> AsciiDoc files and already have appropriate configuration set up. In\n> conjunction with appropriate settings in our `.editorconfig` file (to\n> configure indents properly), I think this would be valuable indeed, and,\n> importantly, helpful to users of all editors.\n\nThe more I think about it, I prefer renaming to *.adoc too. It's easy to \nidentify and obviously distinct from Markdown. GitHub and GitLab render \nadoc files beautifully [1][2]. Visual Studio Code offers to install an \nextension with syntax highlighting and previewing.\n\nThe vim modeline had no effect in Visual Studio Code. It could also be \nintimidating.\n\n[1] \nhttps://github.com/couchbase-guides/how-to-write-a-guide/blob/master/README.adoc\n[2] https://docs.gitlab.com/ee/user/asciidoc.html\n"},{"id":"510461","messageId":"xmqqv7ui72e4.fsf@gitster.g","threadId":"62799","inReplyTo":"Z4WGwCwnNj_XeHiI@tapette.crustytoothpaste.net","subject":"Re: [PATCH] docs: add vim syntax modeline [RFC]","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-13T22:52:19Z","receivedAt":"2025-01-13T22:52:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n>> A simpler alternative could be to rename files *.adoc. This would have\n>> the advantage of being recognised by even more tools.\n>\n> This I would be in favour of.\n\nSounds quite sensible.\n\nThanks.\n"},{"id":"510725","messageId":"CAGJzqs=rtJ3yv2YCTTphsrE=0_1EpZXCA+pGNLuTVQNps9TNzg@mail.gmail.com","threadId":"62799","inReplyTo":"xmqqv7ui72e4.fsf@gitster.g","subject":"Re: [PATCH] docs: add vim syntax modeline [RFC]","fromName":"M Hickford","fromEmail":"mirth.hickford@gmail.com","sentAt":"2025-01-16T18:55:00Z","receivedAt":"2025-01-16T18:56:13Z","isPatch":true,"sender":{"key":"mirth.hickford@gmail.com","avatar":"https://avatars.githubusercontent.com/u/105314?v=4"},"body":"On Mon, 13 Jan 2025 at 22:52, Junio C Hamano wrote:\n>\n> \"brian m. carlson\" writes:\n>\n> >> A simpler alternative could be to rename files *.adoc. This would have\n> >> the advantage of being recognised by even more tools.\n> >\n> > This I would be in favour of.\n>\n> Sounds quite sensible.\n\nGreat, we seem to have reached a consensus in favour of renaming\nDocumentation AsciiDoc files to *.adoc.\n\nI'll leave this to someone more familiar with the documentation build\nprocess (or patient to experiment). #leftoverbits\n"}]}