The `*.plugin.zsh` pattern leads to non-DRY filenames
Tarrasch opened this issue · 12 comments
According to the readme it says that antigen looks for *.plugin.zsh files. My gut feeling (and somewhat experience) is that you'll end up in a file structure like this
my-antigen-plugins
├── syntax-highlight
│ └── syntax-highlight.plugin.zsh
└── zaw
└── zaw.plugin.zsh
I personally would prefer
my-antigen-plugins
├── syntax-highlight
│ └── plugin.zsh
└── zaw
└── plugin.zsh
The second is more dry and more concise, plus adopting that standard would not let ambiguity in determining which *.plugin.zsh file should be loaded if there were many.
I know that you can "fake this" by knowing that you can have only one .zsh file and let that be named plugin.zsh but it feels so much like a hack then. Alternatively one can set the standard to *plugin.zsh, that is both zaw.plugin.zsh and plugin.zsh will work, but I personally would prefer a strict plugin.zsh pattern, allowing only the file to be named plugin.zsh.
So, have anyone else thought about this, any opinions? Sorry for bikeshedding this but I think it's worth considering this while antigen is in beta. Or probably the author have already thought about this but haven't documented the reaso n that the *.plugin.zsh pattern is better.
Oh, two other advantages:
1: Filenames with two dots are a bit ugly
2: More importantly, the plugin authors have to think when naming their loading script. The point of frameworks and tools like these should be that one can just adopt to the standard without thinking and stuff will just work. The The plugin authors are confident that the antigen authors have thought through the naming conventions, so they don't have to.
The main reason why antigen use filenames like this is "legacy" in some excent support for oh-my-zsh's plugins
I'll make a few points that should answer your concerns as a whole.
- The directory structure of the plugins directory is not intended to look good. Its just an internal works-well-this-way kind of thing.
- The file name redundancy is not something antigen introduced. It comes from the way oh-my-zsh did (and still does) plugins.
- In the same lines as the above point, I don't want to specify a format saying plugins should be structured this way and that the files names should be this way. I want the plugin authors to just write their plugin and not think about antigen. Antigen should be able to pick it up.
- That is the reason I have no objections if someone wants to write a plugin as
name/plugin.zsh. As you say antigen loads is perfectly fine. How it loads is not straight forward, but when you want to support many different code organisations, that's what you get. I don't see this as a problem.
1: Filenames with two dots are a bit ugly
Again, its personal taste and I leave it to the plugin authors to write whichever way they like. Antigen will work with it.
2: More importantly, the plugin authors have to think when naming their loading script. The point of frameworks and tools like these should be that one can just adopt to the standard without thinking and stuff will just work. The The plugin authors are confident that the antigen authors have thought through the naming conventions, so they don't have to.
You are right. Plugin authors don't need to think about antigen when writing them. They don't have to think about anything currently. The way I see it, antigen doesn't specify any conventions. Just make your own. As long as its a sane one, antigen will just work. That's the point of having a framework right ;)
And yes, we should clear out these things in the beta stage :)
Ok, personally I (as a plugin writer) would prefer that antigen told me "Do it exactly this way and it will work". I'll just do it and I know I'm following a convention that the antigen authors have thought hard about.
If antigen tells me "Do it in one of these 100 ways, and it will just work", I have to consult my own judgement 100 times to determine which style I like best. More likely I will even browse a lot of other antigen-compliant projects to see if developers are currently adopting one of the ways more than the other.
I'm saying that the point of a framework is not to provide the flexibility to use any convention. No, it should be strict in naming (as rails) so the developer don't need to think when naming their files. And hey, we are only talking about one file.
At the same time I think I understand why you want antigen to be accepting different ways. Shells have existed for decades before we were born, and zsh plugins and omz have been on github long before antigen too, so antigen shouldn't come and tell everyone to switch standard. But I really think antigen is respected enough to be forming the plugins file structures. Even if a plugin doesn't follow a antigen structure it takes only 5 minutes for any developer to fork the project and pull request a patch that forms the project to follow an antigen standard.
I really like antigen since it not only solves the ease-of-install problem that pathogen and vundle does, it also resolves that omz is too centralized. Antigen will be a respected project and people wouldn't mind renaming a file to be part of creating a consistent flora of zsh plugins.
I have to consult my own judgement 100 times to determine which style I like best.
That's one way to look at it. Perhaps we can just suggest/recommend one way of doing things. If we are to do that, I don't want to introduce a new way of doing things. If any directory structure is to be recommended by antigen, it will be something that is currently widely in use. Probably the oh-my-zsh way. Such a recommendation will be quite convincing if its the same format use by something like oh-my-zsh. What say?
I would be happy if the documentation said something like:
Antigen will autoload your library by sourcing the file
*.plugin.zsh, for backwards compatibility and for easier adoptability, antigen supports these other formats too: ...
Or even better, let plugin.zsh be the standard file and *.plugin.zsh be a temporarily supported file format. My hope is that in some time everyone have switched to the recommended file structure, and then we can safely drop support for the other 100 methods. Keeping both antigen simple and the plugins consistent.
Also, consider if somebody else wants to write something like antigen, they would really appreciate if all existing plugins looks consistent so their sourcing logic would just be source_plugin() { . plugin.zsh }.
I don't think that is a good idea. As I said, I'd not want antigen to recommend a completely new way of organizing plugins. Being able to load plugins organized as *.plugin.zsh should not be considered legacy, as there are so many written in this way and there is no real benefit from deprecating it.
I don't want plugin authors to switch their plugin format just becouse one framework wants them to. Instead I'd prefer they made the plugin more awesome :)
Again, if any recommendation is to be made, it will be something currently in use by plugin authors. Unless there is a real benefit with a new format, not just cosmetic.
As for making it easy for new frameworks, it will actually make it more work, to support this new plugin.zsh format.
Again, if any recommendation is to be made, it will be something currently in use by plugin authors. Unless there is a real benefit with a new format, not just cosmetic.
- Cosmetic is a benefit
- Again, mainly I want antigen to be strongly imposing a way, if you don't like imposing a new format like
plugin.zsh, can you consider imposing a existing one like*.plugin.zsh? The goal being to deprecating the others formats so we will get consistency in the long run?
I don't want plugin authors to switch their plugin format just becouse one framework wants them to. Instead I'd prefer they made the plugin more awesome :)
That's a valid point, but I personally think consistency should go first, again, it's no work at all for the open minded and fast paced github community. But I do respect your point.
As for making it easy for new frameworks, it will actually make it more work, to support this new plugin.zsh format.
What? Simply I'm stating that if everyone uses the plugin.zsh format, then the code to load any arbitrary plugin would be to just do source plugin.zsh. It definitely can't be simpler, but maybe you meant that not everyone will adapt that standard, and we will end up with this. However I believe that the community is way more adoptable than you think, just look how everyone overnight started to use the build status image on the top of their readmes.
Note that recommending the *.plugin.zsh will not create a new standard and it will make antigen help the community to be striving for consistency and new frameworks will still be able to do source *.plugin.zsh
Also, I really appreciate that you take your time to discuss this. You also seem to understand the points I make, so I think this is really a healthy and productive discussion. If anybody else have any opinions please comment.
Cosmetic is a benefit
Not if it requires all plugin authors to rename their plugin files when everything is already working just fine.
can you consider imposing a existing one like *.plugin.zsh?
Definitely. Will do.
I personally think consistency should go first
Sure. I too believe that consistency is important. There is some consistency in the way oh-my-zsh did plugins. If we adopt the same standard, achieving this consistency will be much easier. After all, consistency in the format is much more important than the format itself, don't you think?
but maybe you meant that not everyone will adapt that standard, and we will end up with this.
Yes, I did. I even searched for that comic ;)
community is way more adoptable than you think
The way I see it, the community will adapt if there is a real benefit from all the trouble taken to adapt. Then yes, it is very adaptable.
just look how everyone overnight started to use the build status image on the top of their readmes
Good point, but probably not the best thing to compare with. Adding that image meant that the project could show off the build status to the visitor, giving more confidence. That's the reason it became so popular. It added value. I don't see any immediate value in re-organising all the plugins that are working just fine, just the way they are.
As long as antigen doesn't create and recommend a new standard, I don't think we are making anything difficult for upcoming frameworks.
Also, I really appreciate that you take your time to discuss this. You also seem to understand the points I make, so I think this is really a healthy and productive discussion. If anybody else have any opinions please comment.
Absolutely. I've almost done all I wished for, when I started antigen. So, we need more such discussions to find what the community and we want from antigen :)
Cosmetic is a benefit
Not if it requires all plugin authors to rename their plugin files when everything is already working just fine.
Nah, the fact is without conditions actually, it might not be worth the time to switch format. But cosmetics is a benefit in the end no matter what.
Anyway, you definitely don't like the plugin.zsh pattern, look at my other proposal then:
An alternative idea is to support *plugin.zsh rather than *.plugin.zsh. We'll then see if people start to use the one or the other. While it'll be a tiny bit more inconsistent, you can always do source *plugin.zsh to load a project.
However, let's separate the cosmetic issue (this ticket) from the issue that the documentation should recommend one way, be it *.plugin.zsh or not. I'll create another ticket for that right away.
Sorry, couldn't get to this sooner.
But cosmetics is a benefit in the end no matter what.
Sure, opinions differ.
Anyway, you definitely don't like the plugin.zsh pattern
That aside, I don't see any value in recommending a new standard and making everyone switch their plugins to it. If cosmetics is your only reason, its not enough for work it needs.
I'll add to the README recommending to write plugins the oh-my-zsh way (against #24). But its not a strict necessity. I can't remember the last time I thought of code organisation when writing a shell utiluty/plugin. But yeah, I see the value in a recommendation.
Lets close this then.