Vim plugin docs improvements

[matthewarmand]

Description

This is a few documentation changes for the Vim plugin. I included them in the same PR to avoid clutter and because they're all pretty minor and easily reviewed together. I also made a commit for each thematic change, so feel free to look at specific commits if you want to see the changes in isolation. I didn't think this was a substantial enough change to warrant a CHANGES.md entry, but am happy to add one if maintainers disagree.

There are 4 main changes in here:

Formatting and Organization

Commit: 26c56f2 and 197edbd

Currently there are no sub-headers under the Official Plugin section, which can make it a bit tough to read and especially to hyperlink to. Organized it into Installation, Usage, and Troubleshooting as felt appropriate.

Add missing configuration options

Commit: 9929893

A few configuration options exist but weren't mentioned with their defaults at the top of the Vim plugin documentation section, so I added those.

Add plugin documentation for Arch Linux

Commit: bb0f446

Refer to this issue on the Arch Linux python-black package: https://bugs.archlinux.org/task/73024

Since earlier this calendar year, the Black package distributed on Arch Linux (python-black) also ships the Vim plugin, so I added a section to the Installation section mentioning that Arch Linux users need no further steps to use the plugin than installing Black.

Fix the vim-plug installation recommendation

Commit: 1a73b72

Refer to this discussion on the vim-plug repo: junegunn/vim-plug#720 (comment)

Using the stable tag as a branch in vim-plug is a bit of an antipattern that doesn't work correctly, as it doesn't always re-resolve the SHA when the stable tag is moved. According to the maintainer, using the tag key with a shell wildcard is the better way to go. I selected '*.*.*' as the wildcard since it matches Black's documented versioning scheme and will not match on the current standard for Alpha versions (which only have one dot). You can see how this works in the image below; it matches on 22.12.0 (the latest stable release) even though the latest version overall at time of writing is 23.1a1.

Checklist - did you ...

• Add an entry in CHANGES.md if necessary? (Seems a small enough change to not need an entry, do maintainers agree?)
• Add / update tests if necessary? (just docs, not necessary)
• Add new / update outdated documentation?

[JelleZijlstra]

I think it may be worth calling out in CHANGES.md as we're changing the recommended way to install the vim plugin.

[JelleZijlstra]

Also there's a CI failure, you'll need to use prettier to reformat the .md file.

[JelleZijlstra]

Oh and the comment you linked about the versioning scheme refers to the stable tag. But a while ago we changed to have a stable branch, because using a tag that keeps changing is indeed weird. Does that change the situation?

[matthewarmand]

Oh and the comment you linked about the versioning scheme refers to the stable tag. But a while ago we changed to have a stable branch, because using a tag that keeps changing is indeed weird. Does that change the situation?

I'd missed that shift, I think it probably does change things. IIRC specifying a branch works better with PlugUpdate, so that would actually work fine. I guess at that point it's user preference whether they're fine with that branch or they prefer a branch pattern. Up to you really then whether we change this, add tag as an alternative, or just leave it as is, since I think functionally the current recommendation is probably fine.

I think it may be worth calling out in CHANGES.md as we're changing the recommended way to install the vim plugin.

I'm assuming this conditional is solely based on the vim-plug section, rather than the Arch one, correct? In other words, if it's decided above to leave the vim-plug docs alone, we can ignore the change log?

Also there's a CI failure, you'll need to use prettier to reformat the .md file.

All glory to the hypnotoad linter

[JelleZijlstra]

Oh and the comment you linked about the versioning scheme refers to the stable tag. But a while ago we changed to have a stable branch, because using a tag that keeps changing is indeed weird. Does that change the situation?

I'd missed that shift, I think it probably does change things. IIRC specifying a branch works better with PlugUpdate, so that would actually work fine. I guess at that point it's user preference whether they're fine with that branch or they prefer a branch pattern. Up to you really then whether we change this, add tag as an alternative, or just leave it as is, since I think functionally the current recommendation is probably fine.

I might like the tag: *.*.* pattern better because it provides an obvious way to instead pin a specific version if you're so inclined, or to pin to tag: 22.*.* if you want the 2022 stable style. I don't use the plugin though, so no strong opinion either way.

Also, users might have weird cached state from back when stable was a tag.

I think it may be worth calling out in CHANGES.md as we're changing the recommended way to install the vim plugin.

I'm assuming this conditional is solely based on the vim-plug section, rather than the Arch one, correct? In other words, if it's decided above to leave the vim-plug docs alone, we can ignore the change log?

Agree.

[matthewarmand]

I might like the tag: ..* pattern better because it provides an obvious way to instead pin a specific version if you're so inclined, or to pin to tag: 22.. if you want the 2022 stable style. I don't use the plugin though, so no strong opinion either way.

Also, users might have weird cached state from back when stable was a tag.

Yeah I agree, I kinda prefer the tag method anyway for a few reasons, and especially with the versatility of pinning to a year, that's a good callout. I'll expand the section just a bit to explain those options (and probably keep the old one) and then add a CHANGES entry as discussed.