Genericize zsh plugin manager instructions

[jackcogdill]

Zplug is a zsh package manager.

This will save users the time of figuring out how to install the package and only have it run dircolors once per install / update.

[rpdelaney]

This is the difficulty we have with supporting different implementations for packaging plugins in zsh. We do not want to take on maintaining installation instructions for different zsh plugins. I wish there were some kind of repository for zsh because this is more to do with zsh than LS_COLORS :(

I'm not sure what to do, honestly. Why don't these plugin managers have their own repository?

[jackcogdill]

Ah, I understand completely. Zplug does have its own repository with instructions, which is how I figured out how to install this package. But it was not straightforward.

Perhaps we could change the current instructions for Zplugin to be more generic (and explain how a user should set it up for their plugin manager of choice). Namely, the part about only running dircolors once per install/update and not each time the plugin is sourced.

[rpdelaney]

Based on your description, it sounds like zplug's documentation should be expanded.

Perhaps we could change the current instructions for Zplugin to be more generic

Why can't this be solved in the zsh ecosystem?

I had a feeling about #110 but I'm not sure why I didn't raise my concerns then.

[jackcogdill]

it was not straightforward

I actually meant this in regards to installing this repo as a plugin. zplug has great documentation; I would like to improve this repo's documentation.

Why can't this be solved in the zsh ecosystem?

I'm not sure I understand. What do you mean by ecosystem?

I think we could rewrite the install instructions for zplugin to make them more generic, to apply to any plugin manager (and keep zplugin as an example). Thoughts on that?

TL;DR, I think the instructions in the "zsh integration with Zplugin" section are difficult to understand. I think at least rewording them could help.

[rpdelaney]

I'm not sure I understand. What do you mean by ecosystem?

Consider alternatives for supporting installation of a hypothetical software application onto archlinux:

1. Update the README of the app explaining how to build the thing differently to take into account its specific oddities that interact with that platform. OR-
2. Write a PKGBUILD and put it in the AUR.

This isn't a perfectly clean analogy since manually installing things is bad, especially when the thing could be installed in a package manager. What I'm getting at is that #2 is much better for app developers who don't have to worry about maintaining installation docs for various platforms and package managers.

I'm lamenting that the zsh plugin managers don't have such a thing. It feels like a documentation task for the plugin manager, not LS_COLORS.

I think we could rewrite the install instructions for zplugin to make them more generic, to apply to any plugin manager (and keep zplugin as an example). Thoughts on that?

That does sound like an improvement, but maybe removing it altogether is better still.

@trapd00r Any thoughts?

[jackcogdill]

maybe removing it altogether is better still

I think having some instructions about plugin managers would still be useful for those using them. But open to any other thoughts.

[rpdelaney]

I think having some instructions about plugin managers would still be useful for those using them.

Certainly -- but I have this intuition that that should be documented with the plugin manager.

Regardless, whichever way we go I appreciate your offering to contribute and continuing to work on this as I chew on it.

Edit: I should have mentioned that I haven't looked at your latest changes yet. I'll try to get to that soon.

[jackcogdill]

Thanks, I appreciate your review as well.

I think the key point is: it may not be obvious that dircolors is slow and should only be run once.

[rpdelaney]

it may not be obvious that dircolors is slow and should only be run once.

You are right about this, but that affects correct installation on all platforms. The AUR package does it this way now, for instance, which benefits users in any shell.

[rpdelaney]

Okay, I had a peek. I like this change and I think it's a step in the right direction.

I wonder if only zsh users should benefit from this though. I feel like it's probably our generic installation instructions that are wrong. What if we changed that to recommend this approach instead? Would that make this whole zsh plugin section unnecessary?

[jackcogdill]

How about we delete zsh from the title and say this is for any shell plugin managers. And then here is an example if you are using a zsh plugin manager. This would be similar to the "quick install" instructions where it says "assuming bash."

[rpdelaney]

Would the "assuming bash" instructions also work on zsh as written? Maybe we could just rework that part and make it generic for posix inspired shells. People using weird stuff like fish are already used to adapting bash code by now. Or maybe that's what you were suggesting?

[rpdelaney]

See #142 for an example sort of problem with zsh-specific docs.

[Terobero]

zplugin didnt work for me but "assuming bash" worked (replacing .bashrc with .zshrc)

[jackcogdill]

Yes, I think we should reword the install instructions to be shell-agnostic. Underneath that, we can also include shell-agnostic plugin guidelines (not claiming to be specific to any particular manager). How does that sound?

[rpdelaney]

Sounds good, but can we split that up? I feel like the first part is unambiguously necessary and I could also do it myself when I get around to it. Of course if you feel like taking a shot, that's welcome. I'm likely to continue being a stick in the mud about documenting support for shell plugin managers and that shouldn't block the first part, hopefully.

[trapd00r]

@rpdelaney, I think it would be enough to have installation instructions that would work regardless of shell, people using plugin managers would or should be aware of how to apply that specific magic to this project. There's just so many possible setups people could use that we can't document them all.

[rpdelaney]

Alright. Basically I think our installation instructions should be reworked to do it more or less how the AUR package does it. I just threw this shell script together based on that. We could either adapt this into the readme or just commit this to the repo and suggest people use it. Thoughts?

#!/usr/bin/env sh
#

lscolors_data_dir="${XDG_DATA_HOME:-$HOME/.local/share}"
mkdir -p "$lscolors_data_dir"

dircolors -b LS_COLORS > lscolors.sh
dircolors -c LS_COLORS > lscolors.csh

if mv -t "$lscolors_data_dir" lscolors.sh lscolors.csh ; then
    echo
    echo "  To enable the colors, add the following line to your shell's start-up script:"
    echo
    echo "  For Bourne shell (e.g. ~/.bashrc or ~/.zshrc):"
    echo "    . $lscolors_data_dir/dircolors.sh"
    echo
    echo "  For C shell (e.g. ~/.cshrc):"
    echo "    . $lscolors_data_dir/dircolors.csh"
    echo
fi

[dnedrow]

@rpdelaney I think adding the script directly to the repo is the better option, and then add the "use this" instructions to the README.

I find it irritating when a script is provided in a document, meaning I have to copy and paste it into a new file. I figure if the author of a package suggests the use of a script, the script should just be available in the repo.

[ahmedelgabri]

Apologies for commenting on an old issue, but wouldn't this be better if the generated files are part of the repo itself?

And then it will contain lscolors.sh & lscolors.csh. This will work with any plugin manager, or manual process & will eliminate issues like #163 or #176 where dircolor is not installed by default on macOS for example.

[rpdelaney]

Apologies for commenting on an old issue, but wouldn't this be better if the generated files are part of the repo itself?

I think so, yes. Github actions may be the way forward, but I haven't put the time into researching that. PRs are welcome :D

It may be useful to make a separate issue for this topic, if there isn't already on old stale one...