Merge pull request #78 from jan-warchol/devel

Update contributing guidelines

Author: jan-warchol

CONTRIBUTING.md

@@ -1,75 +1,33 @@
-Syntax highlighting design principles
--------------------------------------
-
-Here are some general guidelines for deciding which types of tokens should be
-colored with which color:
-
-- overall effect shouldn't be overwhelming - don't color everything, strive for
-  harmony (compare with [this monokai
-  example](https://i.imgur.com/ATVTHr6.png), which has colors all over the
-  place)
-- contrasting colors shouldn't appear next to each other too often
-- structurally most important elements should be most visible
-- less important content should be visually "in the background"
-- short tokens (and punctuation, if it's to be colored) should preferably use
-  stronger colors 
-- long tokens should use "softer" colors to avoid making the result too
-  aggressive
-- rare tokens should use a color that draws attention and is not used by some
-  common tokens
-- try to leverage common color associations wherever possible (e.g. red ->
-  problem, green -> no problem)
-- warm colors (orange, yellow) are best for tokens associated with action
-- cold colors (cyan, blue) are best for things that don't change
-- [non-spectral colors](https://en.wikipedia.org/wiki/Spectral_color) (purple,
-  magenta) are best for things with special meaning/behavior
-
-This means that, for example:
-
-- comments must be gray, so that they fade into background (unlike many schemes
-  in which comments are green and clutter the view)
-- function and class definitions must be clearly visible from distance (perhaps
-  bright bold foreground)
-- orange is a good color for numbers
-- exceptions should probably be bold and they must not be green
-- preprocessor, interpolation, macros and other meta-processing things "feel"
-  magenta
-- cyan is a good color for `CONSTANTS`
-- should boilerplate be blue? or gray? or not colored at all?
-
-
-Development
------------
-
-Selenized is still work-in-progress.  Here are some of my plans for the future:
-- add ready-to-use config files for more terminals
-- support more command-line programs (add selenized skins/configs for them - in
-  particular I'd like to fine-tune dircolors to look as good as possible with
-  Selenized)
-- add a dark-on-light variant of the palette
-- extend Selenized to 8 accent colors (add orange and violet, like in
-  Solarized)
-- add color schemes for popular IDEs
-- add a script that would allow [adjusting Selenized to your taste](#forking)
-  using a web interface
-- maybe even create a library that would allow adjusting LAB lightness in
-  arbitrary color palettes based on the experience I got creating Selenized
-- research perceptually uniform color spaces - maybe they could be used to
-  improve consistency of Selenized colors even further?  See
+Contributing to Selenized
+=========================
+
+Development roadmap
+-------------------
+
+Selenized is quite complete, but there are some things that could still be done.
+Some ideas for the future:
+
+- better, more nuanced syntax highlighting rules (see [issue
+  68](https://github.com/jan-warchol/selenized/issues/68))
+- web interface for [adjusting Selenized to your taste](#forking)
+- a library that would allow "fixing" existing color palettes (by adjusting Lab
+  lightness of their colors while keeping original hue and saturation)
+- learn more about perceptually uniform color spaces - maybe they could be used
+  to improve consistency of Selenized colors even further? See
   [here](www.brucelindbloom.com/UPLab.html) and
   [here](https://en.wikipedia.org/wiki/Munsell_color_system).
 
-If you'd like to help with any of these, please get in touch - open a pull
-request or contact me at jan.warchol@gmail.com.
+And of course, adding support for more programs, terminals, editors, IDEs etc.
 
-Also, open an issue if you found a program that doesn't look good with
-Selenized terminal or encountered a situation where Selenized was not readable
-enough.  Until version 1.0 I'm open to suggestions on adjusting the colors.
+If you'd like to help but are not sure where to start, contact me at
+jan.warchol@gmail.com. Also, please [open an
+issue](https://github.com/jan-warchol/selenized/issues) if you found a program
+that doesn't look good with Selenized colors in your terminal.
 
 
 
-Forking
--------
+Customization
+-------------
 
 You are welcome to adjust Selenized to your taste - I can imagine that some
 people may want to change the hue of the background/content colors or adjust

manual-installation.md

@@ -5,8 +5,8 @@ Guidelines for creating a selenized theme for your terminal emulator.
 
 Each Selenized variant defines 3 background shades (`bg_*`), 3 content shades
 (`dim_*`, `fg_*`) and 8 accent colors (each with a bright version). This
-document explains which color to use for what. You can find RGB values of the
-colors [here](the-values.md).
+document explains which color to use for what. You can find [RGB values of the
+colors **here**](the-values.md).
 
 
 ### Color mapping
@@ -56,8 +56,20 @@ ANSI palette:
 | 14  | bright cyan    | br_cyan         |
 | 15  | bright white   | fg_1            |
 
+
+### Creating a template
+
+Theme files should be generated from templates (so that it's easy to create
+configs for all selenized variants, and update them whenever colors change).
+
+See
+[`utils/templates/template-test.example.template`](./utils/templates/template-test.example.template)
+for an example template and [`utils/README.md`](./utils/README.md) for
+instructions on how to use templating machinery.
+
 That's it!
 
 Please send me a [pull request](https://github.com/jan-warchol/selenized/pulls)
-with the resulting configuration so that I can make your terminal officially
-supported :-)
+with the resulting configs and template so that I can make your terminal
+officially supported :-)
+

utils/README.md

@@ -9,7 +9,7 @@ templates.
 ### Requirements
 
 - [Python](https://www.python.org/) with development files. Python 3.7
-  and 2.7 is known works; 3.5 and 3.6 might work, but nobody tried yet,
+  and 2.7 is known to work; 3.5 and 3.6 might work, but nobody tried yet.
 - [Colormath](https://github.com/gtaylor/python-colormath) Python library.
 
 Example requirements installation for Debian/Ubuntu Linux and Python 2.7:
@@ -27,13 +27,13 @@ Example requirements installation for Debian/Ubuntu Linux and Python 2.7:
 To generate config file, use `evaluate_template.py` script. You need to provide
 it with two arguments: path to the palette module (with the palette you want to
 use) and path to a template config for your terminal. For example, if you
-wanted to generate selenized medium config file for iTerm, you would do it like
+wanted to generate selenized dark config file for iTerm, you would do it like
 this:
 
     selenized/utils$ python evaluate_template.py \
-                         palettes/selenized_medium.py \
+                         palettes/selenized_dark.py \
                          templates/itermcolors.template
-    [...]
+
     Processing templates/itermcolors.template...
     Result written to output/Selenized medium.itermcolors