Playing Nice with Existing Color Schemes (or not)

[polyglot-jones]

My biggest issue with ST4 color schemes is that you can only have one selected at a time. So, it seems to me that we should endeavor to (a) make sure that our scope naming plays nice with existing color-schemes, and (b) make sure that any adoc-specific color schemes we come up with do a decent job at colorizing non-adoc syntaxes.

...(a) being important for anyone who really likes his favorite color scheme and only dabbles in adoc work, so doesn't care if the color scheme reflects the adoc nuances; while (b) being important for the person like us who cares more about the adoc nuances and only cares that non-adoc files are colorized "enough".

One particular non-adoc situation that concerns me is the technical writer who has to work with multiple markup languages simultaneously -- switching back and forth between MD, RST, and ADOC day by day (hour by hour? minute by minute?) I'm not saying that we need to actively worry about us playing nice with "rival" markup packages right now, but it's something to keep in mind.

QUESTION: I haven't taken advantage of project/workspace switching in ST much. (I'm not even sure what the difference is between a project and a workspace.) Can you have a different color scheme specified for each project? workspace? If so, then maybe my concerns will go away if we document a standard tactic for doing ADOC work in a separate project/workspace than doing other work?

[tajmone]

My biggest issue with ST4 color schemes is that you can only have one selected at a time.

I'm not sure I follow you here. ST allows you to select three default color schemes: (1) default, (2) default dark, (3) default light — where the latter two only apply when ST is set to follow the OS dark/light mode.

Other than that, you're free to override the default scheme on a per-syntax bases — which is what I was trying to do via the package settings. You can enforce a colour scheme for any given syntax either via the GUI menus or by editing you syntax settings in the User folder.

So, it seems to me that we should endeavor to (a) make sure that our scope naming plays nice with existing color-schemes, and (b) make sure that any adoc-specific color schemes we come up with do a decent job at colorizing non-adoc syntaxes.

Point (a) is hardly achievable if we strive to use proper semantics in our package scoping names; whereas (b) is beyond the scope of the package since it would require huge maintenance efforts and testing with syntaxes (just finding decent syntax samples for visual testing is a time consuming task, since most languages don't provide such samples, and there are literally hundreds of languages to keep into account). Unfortunately, the trick of adding -hidden to a color scheme name only works with the old TextMate schemes, not with the new ST scheme format, otherwise I would have made the AsciiDoc Dark scheme a hidden scheme (i.e. that doesn't show up in the list of selectable schemes, but can only be applied manually via setting files).

One particular non-adoc situation that concerns me is the technical writer who has to work with multiple markup languages simultaneously -- switching back and forth between MD, RST, and ADOC day by day (hour by hour? minute by minute?) I'm not saying that we need to actively worry about us playing nice with "rival" markup packages right now, but it's something to keep in mind.

Again, I'm not sure that I understand you correctly here. I do work with multiple syntaxes at once, including those you mentioned, and I use different colour schemes for different group of syntaxes (which also makes it easy for me to distinguish what is what by its canvas color). The Markdown package comes with its own dedicated schemes, so I stick to the light-greyish scheme for MD docs (which I believe is the default scheme which the package enforces, although I'm not sure if I've enabled it manually).

QUESTION: I haven't taken advantage of project/workspace switching in ST much. (I'm not even sure what the difference is between a project and a workspace.) Can you have a different color scheme specified for each project? workspace? If so, then maybe my concerns will go away if we document a standard tactic for doing ADOC work in a separate project/workspace than doing other work?

As far as I know, color scheme settings are detached from projects and workspaces: you have the global defaults (by ST, then by the User), and on top of that you have syntax specific settings (by package, then by User) which override the global settings.

Projects allow to customize a number of settings: included folders, excluded files, file patterns for indexing or indexing exclusion, ecc. I'm not entirely sure what workspaces are for, but when you create a project ST automatically attaches to it also a workspace file, so surely they are handled in part by ST, automatically, e.g. to store GUI related settings (like window size, open tabs, ecc., probably) — what I do not know is whether the user has some slack in terms of customizing the workspace, but I'm sure the documentation should provide more info on that.

I hope it helped.

[polyglot-jones]

Aha! I see the light. I was confused by that cache bug getting in my way. (It mysteriously went away, BTW, and so all of a sudden the syntax-specific settings started working for me. -- Not that I even remembered that ST4 supports syntax-specific settings until you mentioned it just now. I was further confused by the fact that the Preferences -> Select Color Scheme... command makes no mention of anything other than a single selection.) Anyway, the bottom line is I am now unconfused and totally on board with not worrying about what the non-ADOC color schemes might expect in the way of scope naming.

[polyglot-jones]

With my clarified understanding, I rewrote docs-src\color-schemes.adoc. (See attached.)

If you agree that my understanding is now correct, I'll commit it in a PR toward dev.

color-schemes.adoc.txt

[tajmone]

Aha! I see the light. I was confused by that cache bug getting in my way.

I know, that's a really annoying issue — it's often triggered when a package renames a scheme or syntax, and sometimes it fixes by itself by closing and restarting ST, other times it doesn't. A good workaround is also to close in ST all the files that rely on that syntax, because it appears that ST cache works on a per-file basis, so at times restarting ST doesn't fix the problem since the files opened in the tabs are still associated to the old scheme/syntax path.

BTW, yesterday I met a friend who has installed our Asciidoctor package, and checked how the update went for him: the scheme was working all right for him (he didn't have any scheme for AsciiDoc before). But you're right about the bug being there and the risk that enforcing the scheme via the package could trigger it for some users.

If you agree that my understanding is now correct, I'll commit it in a PR toward dev.

Seems all good to me, and anyhow the docs are an evolving WIP.

CAUTION: Do not specify any folder names. Just give the name of the scheme file alone (My-Favorite-Scheme.sublime-color-scheme). SublimeText will find it automatically, wherever it resides.

I gather that this is correct — i.e. that ST scans the packages and User folder for all color schemes, and that therefore the name is sufficient (unless there are same-named schemes in different subfolders, in which case I guess a more qualified path is required to disambiguate between them).

Anyhow, so far just passing the scheme name (without the extra path info) worked fine for me.

[tajmone]

Added as collaborator

@polyglot-jones, I've added you as a collaborator, so you'll have more freedom to commit to the repository directly, on your own.

I'm not a strong in believer in technical restrictions (e.g. blocking commits on the main branch via branch rules) because I prefer to rely on mutual understanding.

As long as we commit our changes to the dev baseline branch, we're fairly safe in making mistakes and fixing things without affecting end users of the package — and we are all bound to make the occasional mistake or unwise choice, but then, again, this is a WIP in package and we aren't really granting to end users a fully polished product right now, since ahead of much there is a lot of trial-and-error and learn-as-you-go awaiting us, before the syntax can be considered production ready.

I'm confident that as we go along we'll find the mutual understanding on where the package is ultimately heading to, benefiting from each other's insights and idea, since every AsciiDoc user has his own peculiar way of using the syntax, and hence his/her own grasp of the different workflows.

I wish I had more time to dedicate to this package, but as of lately there have been many major events in my life that have deprived me of the free-time I used to enjoy before. But having seen all the important contributions you've provided so far, I'm confident you know your way through the project — in any case, it's not as if the consequences or "things going wrong" are going to cause real harm to anyone (it's just a package).

For this project to succeed, we need to gradually involve more people into it, gain more collaborators. It's really a pity that AsciiDoc still lacks a full-fledged editor syntax, especially since it's been around for decades and it's adopted by a very large user-base.

[polyglot-jones]

I'm honored. I'll refrain from doing anything directly here unless you either tell me to or if you go incommunicado for some reason (and even then it would likely only be in cases where I or another collaborator is being blocked from further progress).

[tajmone]

I'm honored.

You've earned.

I'll refrain from doing anything directly here unless you either tell me to or if you go incommunicado for some reason (and even then it would likely only be in cases where I or another collaborator is being blocked from further progress).

Don't be. Every collaboration has to start somewhere, it's just the normal process. Initial bumps are to be expected, but as long as we work on the dev branch nothing really drastic can happen, since we can roll back commits, rewrite history, etc. — it's all part of the natural process of getting to know each other, and even so called "mistakes" are just opportunities to get to known each other better.

If I go incommunicado (as I actually might from time to time, since I'm going through complicate times right now), then you'll simply have to make choices on your own. That's the whole point of being collaborators, i.e. to act as a team, but also to take charge when the other is absent, as it often happens.

This is an open source project in Alpha (almost pre-Beta) stage, so it's basically "our project" mainly an mostly. Sure, things might go wrong, bu that's part and parcel with the challenge that comes with it. It would be nice if we had a magic sphere that could reveal to us the path ahead to accomplish the goal, and if that was the case we could just write down a ROADMAP file with all the steps ahead. But we're far from that stage right, we're still trying to make sense from the original syntax file and put it back into shape — which entails experimenting and, at times, guess work too.

[tajmone]

To be clear, @polyglot-jones, for me open source projects are something I take on in my free time as a form of pleasure. So I tend to take a relaxed approach to these projects.

Collaboration in an important part of the FOSS movement, and technical skills are nothing without a good attitude to collaboration: if one can't work nicely in a team, his skills are useless. So, being able to interact nicely with collaborators, and treat them as peers, is a key aspect of the FOSS movement.

The worst thing that can happen is that we mess up the repository — although I doubt that anything really irreversible can happen. But even so, then what? Good collaborators can always start again, from scratch, with a new project, as long as collaboration is and remains a pleasant experience. When collaborators fight (as unfortunately you see sometimes) then projects become simply "poisoned".

So, if you are worried about making mistakes, be assured: we're doomed to make them, both of us, there's escaping this simple truth. On the other hand, collaboration can make us stronger, since we can complement each other's strengths and weaknesses, as a team.

Collaborations develop into "virtual friendships" in the course of time, which are something more precious than any single free-time project. All the people I've worked with in the FOSS movement are people I eventually grew to know and trust, in terms of how we can work together, and people that I can count on when a new project is at hand. That's something in its own right.