A Guide to Installing ColorSchemeEditor for Sublime Text 3

Hello and welcome to my ColorSchemeEditor (referred to here as CSE) installation guide. The task of building and installation is rather complex, so I’ll give the details for Windows, OS X, and Linux here.

As far as prerequisites are concerned, if you want to build from scratch you’ll need a recent copy of Python 2.7. OS X users, make sure you install Python from python.org, MacPorts, or Homebrew, as the version of Python included with OS X is not complete, and most likely won’t work for this task. Next, Windows and OS X users will need to install wxPython 2.8 or 2.9 (not 3.0) from here (Windows users, pick either the 32- or 64-bit versions for py27, OS X users pick the Cocoa .dmg file). Linux users, you can install the wxpython or wxgtk packages from your package manager. On Ubuntu, for example, the package is called python-wxgtk2.8. Again, make sure you’re getting version 2.8 or 2.9.

OK, now that we have the prereqs out of the way, let’s get the source. First, at the command line, navigate to Sublime’s Packages directory. On Windows, this is either %APPDATA%\Sublime Text 3\Packages (for a standard install) or the Sublime Text 3\Data\Packages directory for a portable install, on OS X it’s ~/Library/Application Support/Sublime Text 3/Packages, and on Linux it’s ~/.config/sublime-text-3/Packages (the ~ symbol means your home directory). Once in Packages, run

git clone https://github.com/facelessuser/ColorSchemeEditor.git

This will create the plugin directory, called ColorSchemeEditor. Linux users, enter this directory, and open the file called version.json in Sublime. In the "linux" section at the top, change "max" to "0.0.9", then save the file and close it. Windows and OS X users don’t need to do this step, as theirs is already set to the correct value.

Next, navigate to some other directory, like /tmp on OS X/Linux, or perhaps a directory where you keep your development files. Even the Desktop would be fine. There, run

git clone -b GUI_Source https://github.com/facelessuser/ColorSchemeEditor.git CSE_GUI

This will clone another branch of the ColorSchemeEditor repo into a directory called CSE_GUI. Enter that directory, and run

git clone https://github.com/pyinstaller/pyinstaller.git

This clones the PyInstaller repo inside the CSE repo, as it is needed to build the binary. Once this is out of the way, we’re ready to build! From inside the CSE_GUI directory, simply run

python build.py -c subclrschm

and wait for a while. If you’re lucky, you’ll get an output with lots of INFO: lines, but no ERROR: messages. After it’s all done, navigate to the dist subdirectory, and your new binary should be there. On Windows it’ll be called subclrschm.exe, on OS X it’ll be subclrschm.app, and on Linux it’ll be subclrschm (no extension) and should already be marked as an executable. As a test, try running the binary now to see if everything worked. On Windows, just type subclrschm, on OS X type open subclrschm.app, and on Linux type ./subclrschm. You should see a new window open up that looks like this:

CSE opening dialog

Just click on the X at this time, hit Cancel in the next dialog box, and the program will quit. Congratulations, you’ve just built yourself a new binary!

The next part can be done either via the command line, or through your platform’s file explorer (Windows Explorer, Finder, Nautilus, etc.). Navigate back to the Packages directory mentioned earlier and enter the User subdirectory. Next, create a subclrschm directory, and inside that create a subclrschm-bin-platform directory, where platform is one of windows, osx, or linux . Inside this directory, create a file called version.json with the following contents:

{
    "version": "0.0.9"
}

Save the file and close it. If you edit this file in Sublime, you may get a notice to download the binary – just cancel it. When Sublime started, you may have gotten a notice about how it can’t compare versions, or something similar. Again, just ignore it. Finally, with Sublime closed, copy the binary from your CSE_GUI/dist directory to the one containing the version.json file you just created.

And that should be it! You can now restart Sublime and play with ColorSchemeEditor. To access it, open the Command Palette with Ctrl-Shift-P on Windows/Linux or Command ⌘-Shift-P on OS X and start typing colorscheme until the options appear. There are six options, only four of which I’ve ever used:

  • Color Scheme: Editor (file picker)
  • Color Scheme: Editor (new theme)
  • Color Scheme: Editor (current theme)
  • Color Scheme: Editor (pick installed theme)

Since I’m typically interested in modifying the theme that’s currently active, I usually use the current theme option. By default, CSE creates a temp folder (Packages/User/ColorSchemeEditorTemp) where it stores the modified version of the .tmTheme file and the associated .tmTheme-JSON file it uses internally. If you make any modifications to your current theme, the plugin automatically changes your preferences file to point to the temp folder’s copy – the original theme file itself isn’t modified. This can be changed by copying Packages/ColorSchemeEditor/color_scheme_editor.sublime-settings to your Packages/User folder and editing it there (make sure you keep the original!). In particular, setting "direct_edit": true will make changes to the original theme file, without creating the temp. Use at your own risk. The only exceptions to this are themes that reside in a .sublime-package archive in the Installed Packages folder (which is in the same parent directory as Packages) – since CSE can’t/won’t write inside these archives, a temp file will always be used.

Using the app itself is pretty self-explanatory. The first pane that opens up shows the global settings, for things like the activeGuide and stackGuide colors, caret, findHighlight, etc. Here’s as many as I’ve come across before (they’re all included in my Neon Theme):

  • activeGuide if indent_guide_options in your preferences contains draw_active, this is the color of the guide marking the innermost tab stop of the current indented section of your code where the caret is currently placed.
  • background the default background color of the text entry area.
  • caret the color of the caret (cursor).
  • findHighlight when using one of the Find options, a highlighted (found) piece of text has this color set as its background.
  • findHighlightForeground the color of the highlighted (found) text itself.
  • foreground the default text color.
  • guide if indent_guide_options in your preferences contains draw_normal, this is the color of the lines marking tab stops in indented sections of code. activeGuide and stackGuide override this color if draw_active is set. Both draw_normal and draw_active can be set at the same time.
  • inactiveSelection if text is selected, and the window loses focus, this is the color of the background of the selected text.
  • invisibles I’m not sure what this does. I have it set to bright green, and I can’t seem to see an effect anywhere…
  • lineHighlight if highlight_line is set to true in your preferences, this is the default background of the line containing the caret.
  • selection the background color of selected text.
  • selectionBorder the color of the 1-pixel border surrounding selected text.
  • stackGuide if indent_guide_options in your preferences contains draw_active, this is the color of the guides marking the tab stops at all indented sections of your code, out to the outermost line (not indented at all) where the caret is currently placed.

The second pane in CSE is Scope Settings. This is where all the scopes of a theme are listed, with their name, foreground and background colors, font style (bold and/or italic) and scope definition. There are buttons for moving individual scopes up and down, as well as for adding new and removing current scopes. To edit an existing one, just double-click on it and the editing window will pop up. In here are text boxes for name and scope definition, check boxes for bold, italic, and underline (even though underlining via color scheme isn’t supported in Sublime Text yet), and color boxes for both foreground and background. If you click on the color box your platform’s color picker appears, and once you’ve made your selection and closed it the current color is in the box, and its hex code is in an editable text box next to it, allowing you to manually enter colors if desired. If you don’t want either a foreground or background color, and just wish to go with the defaults as defined in the Global Settings pane, just delete the hex code and you’re all set. When you’ve picked your colors, hit the Apply button, and, if you’ve kept "live_edit": true in the color_scheme_editor.sublime-settings file, you’ll see your syntax highlighting in Sublime update in real time. This makes it easy to tell if you’ve gotten the right scope selector(s), and shows you your results in a larger context.

And that’s about it! ColorSchemeEditor allows very fine-grained control over individual colors and scopes, which makes it great for both tweaking existing themes and developing completely new ones. However, if you’d like to change all the attributes of a theme wholesale, such as applying a sepia tone, changing contrast and brightness, rotating the hue, etc., then there are a couple of other tools to check out. The first is @facelessuser‘s ThemeTweaker, which is a Sublime plugin. It takes some time to set up all the custom commands, although an example keymap is included, but the results are pretty cool once it’s ready. The second resource is @aziz‘s tmTheme Editor, which requires a pretty recent version of Google Chrome or Firefox to run due to its dependence on several HTML5 APIs that haven’t necessarily made it into other browsers (coughIEcough) yet. This is a graphical theme editor similar to CSE, and although it does have some drawbacks – for example, the regex engine isn’t the one used internally in Sublime, so not all scopes will look exactly the same, and the fonts aren’t configurable (yet) – it is a really good online alternative. You can enter your own test text, or you can pick from samples of JavaScript, CoffeeScript, HTML, CSS, Ruby, Java, and Python. Like ScopeAlways the current scope is shown on the bottom bar, allowing for customization on the fly. It also has some other cool features, like the ability to adjust brightness and contrast with sliders, and you can choose to invert, gray-scale, or sepia-tone the theme. One recent enhancement is the ability to just point at a piece of text, and the list of scopes in the theme will automatically scroll until the most relevant one is showing.

I hope all of this has been helpful. If you have any questions, just leave a comment below, or open an issue, and somebody should be able to help you. Good luck!


Welcome to MattDMo.com!

Welcome!

Somehow, you’ve stumbled across my new(ish) blog at MattDMo.com, and I’m glad you’re here. I wanted to use this first real post to talk a little bit about who I am, what I do, and my plans for this site. This is still very much a work in progress, but unlike some of my earlier attempts I actually have something of a vision of what I’d like this to become, so hopefully it’ll last. I really do appreciate comments and feedback, so if that part of the site is working please leave a little something to let me know you stopped by.

About Me

My name is Matt Morrison, but you can generally find me online as MattDMo, hence the domain name. I generally hang out on GitHub and the StackOverflow/StackExchange network, and when it’s working at the forum for my favorite piece of software – the text editor/programming environment Sublime Text. You can occasionally find me on Facebook and Twitter, and I’ve got a pretty sweet LinkedIn profile too.

What I Do

It may surprise some people that know me online, but I’m not a programmer in real life, at least not professionally – I’m a scientist. I have a pretty broad range of experiences, but I’ve focused on biochemistry and cell and molecular biology for most of my career, with a little bit of manufacturing, quality, and various associated things thrown in for good measure. I’m currently working for Shire doing bioanalytical assay development, but I spent many years at Cell Signaling Technology before then developing, producing, validating, and supporting antibodies and antibody-based products. I went to grad school at Penn State Hershey, originally as a PhD student in the Integrative Biosciences – Molecular Medicine program, but I eventually realized that the academic life wasn’t for me, and with the support of my advisor I published a first-author paper as my Master’s thesis and headed out into the real world.

My Projects

I have lots of stuff going on, much of it related to Sublime Text in one way or another.

  • My Neon Color Scheme for Sublime Text and TextMate is designed to make as many languages as possible look as good as possible, through taking advantage of the many scopes found in the .tmLanguage language definition files and their possible combinations. It’s a “bright on black” scheme, but plans for Neon Light are in the works, so stay tuned! You can find the original project on GitHub.
  • As a related project, I just started Neon-pygments, my first stab at a Pygments style, based on Neon. I’ll submit it to the Pygments project and see if they’ll accept it in the code base, but even if they don’t it’ll be a good exercise.
  • Python Improved is a better Python .tmLanguage syntax definition for Sublime and TextMate that fixes a lot of issues with the current versions, and adds some additional features as well, including Django-specific syntax highlighting, support for Python 3 function annotations, and more. If you do any work with Python, I’d highly recommend getting it. Of course :)
  • There are a bunch of projects that I’ve contributed to, just because I can: Package Control (of course), ScopeHunter, GenerateUUID, and others.
  • This website and others tend to absorb a fairly large amount of my time. I have a really great hosting provider called WebFaction, and I have a ton of sites on there where I play with Django, Ruby on Rails, PHP (blech), HTML/JS/CSS, shell access, DNS, mail servers, and all sorts of other cool stuff. I’ll probably write another post at some point extolling all of WebFaction’s virtues, as there are many to behold, but their shell access via SSH and their very well put together online Control Panel are just terrific. They have all sorts of web services that can be installed very easily, unlimited subdomain names, and … but, I’m getting ahead of myself. Go check them out for yourself. You won’t be disappointed.

About This Site

No self-respecting nerd can start a technical blog without talking at least a little bit about the site itself. I’ve already mentioned my awesome hosting provider, so we’ll get down to the nitty-gritty details:

MattDMo.com is currently located on web351.webfaction.com, with dual 4-core Intel Xeon E3-1270 processors running at 3.4 GHz (54,402.16 bogomips total) and 16 GB RAM. It’s connected to the net using what looks like four bonded 100MB ethernet interfaces – not sure how I’d verify that, though. The machine is running CentOS 6.2 on kernel 2.6.32-358.6.2.el6.x86_64. Users can connect via SFTP and SSH with full shell access, and once logged in you have just about any development tool available to you that you could want, and if you don’t your 100 GB of disk space affords you the room to download and build it. They’re pretty good about keeping the latest (or nearly-latest) versions of things like Python and Ruby installed, and the one-click application installers are updated with bugfix releases all the time, which is a big deal when there’s so much PHP lying around.

As you can probably tell from a little blurb someplace around here, this site is running WordPress version something-or-other, with the whoziwhatsit theme (I don’t want to say here, because it changes frequently until I find something I like). I really don’t want to be running WP, just because of the huge potential security issues posed by running untrusted PHP code, but I’m having serious problems getting a decent blog up and running and looking good on Django. I’ve tried Zinnia and Mezzanine, and can usually (after quite a bit of configuring) get a bare-bones site running, but I can’t for the life of me get a decent theme installed that will give me a nice home page instead of just bare text and links – in that respect, WordPress has got them beat. Believe me, I’m not a dumb person, I know where to go looking for answers, and I’m not afraid to dive into the code and figure things out, but I really don’t want to build templates from scratch. I want to be able to install a plugin or an app, and get a pretty default page like you see here without trying to configure Bootstrap. In some cases it’s the documentation’s fault, it either plain doesn’t explain how to do something, or it breezes over it in such a trivialized manner that it’s assumed you already know how to configure everything yourself. But, enough about that for now, I’m sure I’ll have lots more complaining to do later, now that I got me my own expression platform!

Where I’m Going

If you’re still with me, great! You now get to share the secret of what I’m trying to do with this whole venture: write a book! But first, a little background. As you can probably already tell if you’ve been paying attention, I really like Sublime Text. If you’re not familiar with it, it’s a cross-platform (Win/Lin/OSX) text/source code editor that is almost completely customizable and extensible. All of the configuration files are either formatted in JSON or XML, and the main program is built around a central Python API that allows for the easy generation of plugins, from the very trivial to the incredibly complex. Nearly every aspect of the program has one or more configuration options associated with it, allowing you to do such diverse things as change buttons, fonts, and colors, tweak syntax highlighting, word wrapping, and auto-completion, and alter files at any point from as soon as they’re loaded to after they’re saved and closed.

I like messing around with things, and getting them to work just so. I’m one of those people that has to adjust the seat, the steering wheel, and all the mirrors when I get in the car, so everything is just right. I’m the same way with software – I can’t just take a default install of Microsoft Office and start working – I need to make sure it fits my needs, like not auto-selecting whole words, and being able to set print options every time I hit the Print button. I discovered Sublime Text sometime around the end of 2012, and I was hooked. I had run across TextMate a few months earlier, and liked it, but it wasn’t cross-platform (I work on Windows, Mac, and Linux (virtual) machines), and you weren’t able to do quite anything you wanted – it still had graphical Preferences menus, for example. Sublime had a pretty steep learning curve – everything was text, but once I figured out where everything was supposed to go, it just clicked. It certainly helped that Jon Skinner, the author of Sublime, was significantly influenced by TextMate, to the extent that many of the extensions can be used with very little, if any changes.

I had been aware of StackOverflow for a while, but hadn’t joined until the spring/summer of 2012, when I was in a bit of a career crisis and trying to decide if I should give up bench work and move into bioinformatics or some other kind of full-time programming. Early on I asked a question about Sublime, then started answering a few questions, because there’s no better way to learn than to have to explain something clearly to someone else. I now lurk on all the major ST tags, have a sublimetext2 badge (sublimetext3 should be coming shortly, with its increased use), and along the way have accumulated over 4000-something reputation points by answering over 200 questions. But, I’m not here to brag, I’m just pointing out my obsession with this piece of software. Other symptoms include publishing Neon and Python Improved, and getting more involved with troubleshooting on the sublimetext.com forum.

So, it wasn’t a huge surprise when I was contacted by Packt Publishing to be the Technical Reviewer for an upcoming Sublime Text book. I can easily think of six or eight more-qualified people than me (at least from a technical/Python programming perspective), but they asked me, so I said yes. Maybe the other guys said no, I don’t know. At any rate, I was pretty excited – I’d be able to help shape the direction of the book, plug my own projects in the front matter, and make sure that the right people/plugins/sites got mentioned in the text. I’d also get a free copy of the book when it’s printed, along with another free ebook of my choosing.

I wasn’t quite sure what to expect – I’m a bit of a grammar/spelling perfectionist when it comes to published material, and in fact at this very moment I’m helping a non-native speaker of English clean up his GitHub documentation. I give a lot of leeway to people for whom English is not their first language, as I understand it’s one of the toughest languages to learn as an adult. However, if I’m involved in any phase of document editing, I’ll be sure that things are spelled correctly and sentences make sense. This is why I have such a hard time writing first drafts – it’s got to be right when it comes out the first time, I can’t just speed-write and go back later to clean up. At any rate, I told the editorial staff this upfront, and they seemed OK with it.

To make a long story short, as of today I’m finishing up reviewing Chapter 4, with each chapter having 10-15 pages in it. Now, these aren’t the densely-packed pages one usually expects from a technical book, these are wide-margined Word documents with big fonts, inserted pictures, tables, etc. I’ve made between 60 and 100 comments on each chapter, from spelling mistakes to incomplete, nonsensical sentences to technical corrections and ideas. The writing is … atrocious. Like I said, while I will give a lot of leeway to non-native speakers of English, if you’re going to write a book for an American audience you should probably have more than a mediocre command of the language. There are many times during my reviews when I just throw my hands up in the air, because I can’t rewrite the entire chapter to my liking. It’s not just the grammar, spelling, and punctuation, but the content, too! The man is addicted to exclamation points in inappropriate places, and asks random dumb questions just to fill inches. A lot of the content is clearly taken directly from the Sublime Text docs, either unofficial or official, and he has this habit of posting links to his own gists instead of the main docs, which are maintained by the community.

I have never run across the author on StackOverflow or the Sublime forum, and he only has one extension on Package Control – a set of commands for creating Rails generators that as of right now has a grand total of 376 installs. Python Improved has been released for a month and already has over 800! Looking through his GitHub projects I’ve found that, except for his Package Control offering (which was made with several other people), none of his repos are original – they’re all forked, and none of the others have to do with Sublime. So, I’ve built a picture of this guy – not a real member of the community, with no discernible contributions, coming in to write a really lousy book, the need for which is demonstrably great, to judge from SO and the Sublime forum. They guy is not a Python programmer, and I just can’t wait until he gets to the plugin chapters. I’d be willing to bet that he’s just going to walk through one of the demo plugins already included in ST, and that will be that.

So, What to Do?

The need is clear – an extensive, well-written guide to configuring, using, customizing, and extending Sublime Text, and unfortunately “Mastering Sublime Text” is not going to be that book. I still haven’t decided if I’m going to stick it out through the end, or if I should just write to the editors and say, “Listen. I can write this book better than the guy you have now, with a ton of more relevant, useful information, and put it in a clear and well-presented manner. You can easily get an idea of my style by visiting SO and the Sublime forum, so it won’t be a mystery as to what kind of writer I am. I can speak and write the language as a native. What do you think?”

I’ve just filled out the initial “Potential Author” form on their website, so we’ll see where it goes. One of my ideas for this site was to start fleshing out the book with an outline, some sample chapters, etc., and perhaps publish the whole entire thing here if I can’t find a publisher who’s interested. My wife is an excellent graphic designer, and could do all the layout in InDesign and Acrobat. Who knows?

So, stay tuned. I really think there’s a market for this, and the market deserves more than it’s about to get. Any thoughts?