It's easy to create a stylesheet that quickly becomes overwhelming. This week, for the first time ever, I have created a style sheet this is easy to understand and will be easy to change in the future. And today, also for the first time, I see clearly the principles involved. Several Aha's and corollaries have emerged today in discussions with Terry. This post summarizes them:
*Aha 1: Start with the css* The guts of any theme is the @data qt-gui-plugin-style-sheet tree. It should organized this way: 1. Most css nodes should describe a single area of the screen. 2. Conversely, *everything* relating to a screen area should reside in a single node. This organization may seem obvious, but older themes did not always follow it. Putting "everything in its place" means that *css nodes contain all the @constants related to a screen area*. This is a big advantage of the new scheme. *Aha 2: Use only "obvious" settings* Settings should mean something *independently* of how those settings are used in the @data tree. The Leo Solarized Dark theme uses only these settings: - Syntax coloring settings. Their meanings are clear. They are necessary, but they are not used in the @data tree. - Font settings. These have obvious meanings. They are the font family, sizes, and styles for the body, log and tree panes, and for general text areas. Because their meanings are obvious, they can be changed without worrying where in the @data tree they are used. - Color settings. All such settings have clear meanings. *There are no "general" color settings!* - Settings related to plugins, especially the bookmark plugins. These are not so easy to understand, but people can search for them if they like. - Gradients. These are utility constants. The only design choice is whether to use them or not. *Aha 3: Be wary of using constants that appear only once*The meaning of constants is *given by the css*, so turning them into separate settings may just obscure what is going on. The settings in Aha2 are benign exceptions to this rule. *Corollary 1: Resist the temptation to be be clever with settings* Trying to be clever can instantly create massive confusion. For example, the the solarized light and dark themes will differ in "just a few" foreground/background colors. Suppose we just create a few settings that encapsulate those difference and use those *new *settings instead of the actual solarized color names. This might work, but a search for @solarized- shows that the Solarized Dark theme uses almost *all* of the solarized base colors. Thus, these is *no way* to describe how the theme uses those colors *except by looking at the css.*In fact, creating another level of redirection of @ constants will make things much *harder *to change. This is a crucial point, born out by past painful experience. In the new scheme, if I want to change some region of the screen I just go to the corresponding css node and change the desired *one-level* @ constant. *This can not have any other side effects.* In contrast, using another level of @constant indirection will create css that is difficult to understand in the moment, and impossible to remember for more than a few hours. Furthermore, two-level @constants make changing css nodes much more risky. So we have just "proved"... *Corollary 2: Avoid two-level @constantsCreating new style sheets* Following these principles means that creating a Solarized Light theme from the existing Solarized Dark theme will require an initial examination of *all* the (copied) css nodes. That's a *good* thing. Real choices have to be made for each area. That can't be helped. The solarized base colors have meaning *only* in the context provided by the css, so we must examine each css node in turn. Pretending otherwise is a *huge* mistake. This initial extra work (perhaps aided by find/replace) will immediately start to pay off. Tweaking css is *much *easier if we confine ourselves to one-level @ constants. No confusion. No side effects. Nothing difficult to remember. *Summary* These principles show how to create *maintainable *stylesheets. They are the simplest thing that could possibly work. Imo, they are the *only* thing that work well. They are a huge improvement over previous efforts. When we follow these principles we can tweak css without understanding arcane constants. We can change css without fear of causing unintended (cascading!) side effects. When creating a new theme, we must change one-level @ constants "by hand", or with search/replace. This "extra" work is easy. Any mistakes can be easily fixed *locally.* The result is a stylesheet that is maintainable from the get go. These Aha's have implications for the Themes menu, but that's another post. Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to leo-editor+unsubscr...@googlegroups.com. To post to this group, send email to leo-editor@googlegroups.com. Visit this group at https://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
