Re-structure repository and potentially include `.tmTheme` files

[sgoudham]

Background

This issue assumes the context of the comments made in issue: https://github.com/catppuccin/catppuccin/issues/2278#issuecomment-1959010956

I'm continuing the conversation in here to avoid valuable information being buried in a closed issue.

Description

I will provide a more explicit definition in the theme-making documentation/template for Yazi in the next few days - A Yazi theme that does not include a tmTheme file is considered an invalid theme, and each theme must be a directory.

- @sxyazi

Thanks for giving us a heads up! In regards to directory restructure, I think it then makes sense to have something like the following:

.
├── assets
│   └── latte.webp
│   └── frappe.webp
│   └── macchiato.webp
│   └── mocha.webp
│   └── preview.webp
├── frappe
│   └── theme.toml
├── latte
│   └── theme.toml
├── macchiato
│   └── theme.toml
├── mocha
│   └── theme.toml
├── README.md
├── LICENSE
└── ...

I understand that you'd like yazi themes to include the .tmTheme files in the same directory since it would be invalid and cause further inconvenience for the user. One potential "solution" is via git submodules if @uncenter is happy with managing the additional complexity. The .tmTheme files could be git symlinked into each directory, meaning the user could clone with git clone --recurse-submodules and then copy the files? However, I don't really believe this is worth it.

Personally, I still think its fine including the theme.toml files and telling users in the README to go download the .tmTheme file elsewhere, of course not ideal in yazi's case but I'd really like to avoid the duplication of files in the organisation.

 

The reason for making such a request is because I really love catppuccin and can't go a day without it. You might find it hard to believe that in earlier versions of Yazi, the color of catppuccin was hardcoded directly into the code, and it has appeared as the official theme until now. Therefore, I will be more stringent in my requirements for it.

- @sxyazi

I really appreciate how much you care about the theme, and I appreciate you being involved in this discussion. When it comes to decisions like the above, I'm looking at it from the perspective of the organisation as a whole.

Duplication of files ultimately harms the organisation overall as files may get updated in one place and not the other, and I'm okay with slightly inconveniencing the user's installation process in return for no duplicated files across repositories. I hope you can continue to understand my position on this.

[sxyazi]

Thank you for bringing this issue here and responding, much appreciated! @sgoudham

I agree with your point that using catppuccin/bat as Git submodules would introduce additional complexity. And it's also not really ideal - users would need to add --recurse-submodules when cloning, and downloading the zip file from GitHub would not include them, which kinda ruins the point.

From Yazi's position, I can totally accept that these files are not always the latest, and in fact, always being the latest might be problematic. catppuccin/bat, as its repository name, always prioritizes bat, and Yazi and bat have their own release cycles. I can't guarantee that updating these files for bat won't cause issues in Yazi and result in malfunction.

This is also one of the reasons I downloaded them to yazi-rs/themes, I wanted something a bit more fixed. Therefore, I think simply copying them over, locking the versions, and manually testing and updating them would make more sense, and I'm willing to take on that extra work if you'd like - just not sure about catppuccin's maintenance policy, if one repository can have multiple maintainers?

Again, thank you for your response, giving me the opportunity to explain my position and exchange viewpoints!

[uncenter]

Yes, you can be a maintainer! Happy to make that happen. Also, I have an idea for a potential solution... we manually copy the .tmTheme files in and have a CI run daily to check for differences between them and the upstream versions. If there is a difference, CI makes a PR and we can review it to test if it works or not.

[sgoudham]

Thanks for replying, we can have multiple maintainers yup! @sxyazi

In response to files not being the latest and mismatch of versions, I'm a bit confused here because I thought the .tmTheme files are pretty much syntax highlighting files in isolation? Does yazi do something special with them aside from parsing it and using them for syntax highlighting? I've been operating under the assumption that any improvements to a .tmTheme file would "just" be applicable to any application that parses it. (The reason why its in bat at the moment is just because its the only repository at the moment that needs .tmTheme files to be available - I believe sublime-text used to have it but has moved to another format)

I'd like to avoid the introduction of CI here @uncenter

[nullishamy]

When thinking about possible approaches to tmTheme inclusion, it might be worth considering our target audience here.

For repositories that are sufficiently complex (e.g ctp/vscode), we'd expect some sort of distribution system for the plugin/extension/addon that doesn't involve manually copying files around in some capacity. This inherently means you are not cloning repositories yourself, unless you plan on developing the port.

On the flip side, for projects that are relatively simple (e.g ctp/yazi), the primary workflow is to copy a few files yourself. I personally do not see a usecase where people are cloning the entire repository to take <=3 files out of it?

With this in mind, a submodule doesn't seem insane for this purpose. GitHub will allow you to jump to the submodule'd directory to copy from. Even if we don't use a submodule, this should be similar for other embedding approaches.

[sxyazi]

Thanks for replying, we can have multiple maintainers yup! @sxyazi

In response to files not being the latest and mismatch of versions, I'm a bit confused here because I thought the .tmTheme files are pretty much syntax highlighting files in isolation? Does yazi do something special with them aside from parsing it and using them for syntax highlighting? I've been operating under the assumption that any improvements to a .tmTheme file would "just" be applicable to any application that parses it. (The reason why its in bat at the moment is just because its the only repository at the moment that needs .tmTheme files to be available - I believe sublime-text used to have it but has moved to another format)

I'd like to avoid the introduction of CI here @uncenter

I think the issue here is not what Yazi did, but what Yazi didn't do, while bat did, this is often the cause of the problem and is also a thing I'm not sure/cannot guarantee.

For example, bat supports ANSI colors, which is not included in the tmTheme format, bat extended it itself, and some Yazi users reported to me that they couldn't use it, and Yazi didn't support it until v0.2.0.

I have been trying to keep up with bat as much as possible, but that's not always the case, especially considering different release cycles.

[sgoudham]

Hmmm that's quite interesting, is bat technically going against the schema of the .tmTheme to do that? Is the .tmTheme file versioned in anyway?

If bat has a quicker release cycle than yazi, I suppose you could pin the link to the file via a commit?

This is really interesting though, thanks for sharing and updating my understanding of how the files are used across these applications. It's definitely a headache for an organisation like Catppuccin where we want to prevent duplication :sweat_smile:

[sxyazi]

Hmmm that's quite interesting, is bat technically going against the schema of the .tmTheme to do that? Is the .tmTheme file versioned in anyway? This is really interesting though, thanks for sharing and updating my understanding of how the files are used across these applications. It's definitely a headache for an organisation like Catppuccin where we want to prevent duplication 😅

Maybe this is why Sublime Text switched to another format, I don't know. 😄 But currently, the Rust ecosystem I can only use it.

I think if catppuccin doesn't use these proprietary color values in tmTheme files, there is no such problem, but this is also what I am worried about, because it is in the bat repository, there may be contributors who are not clear about other projects still depend on these files to commit these things for it.

If bat has a quicker release cycle than yazi, I suppose you could pin the link to the file via a commit?

The release cycle here refers to the "feature" release cycle of Yazi, as mentioned above, ANSI is only supported from Yazi v0.2.0, Yazi cannot have the features supported by bat immediately, unless contributors are willing to promote them, because we are not in the same user scale, and the number of contributors is also very few.

Yes, I can manually pin them, but still need to manually test whether they work properly in Yazi after each change of these tmTheme files (or after problems occur?), from the workload, it seems that there is no difference between directly copying them.

[uncenter]

I'd be willing to move forward with the switch to flavors by building a CI workflow to generate the themes using Whiskers, copy the license files, fetch/pull in the tmtheme files, etc but I really don't like the mandating of only PNG files for preview images. Any chance that could change @sxyazi? Yazi supports WebP and from what I can gather it seems like you are looking at making a theme viewer/manager inside Yazi which would require viewing these files (readme, license, previews) and seeing as Yazi has no issues with WebP I don't get the requirement.

[mikavilpas]

Someone mentioned https://vimcolorschemes.com here and I thought that was the idea... But now I realize it wasn't a comment by @sxyazi so it might be just a random idea.

Either way, I'm not sure I understand the desire to use .png. If it's a website, my browser can display both formats. If it's somehow inside yazi, yazi can also display both formats.

Maybe this restriction could be lifted?