From 079a60b8af9359516b68b713cc59ac6feb16d405 Mon Sep 17 00:00:00 2001 From: SteveJobzniak Date: Wed, 7 Dec 2016 23:49:01 +0100 Subject: [PATCH] Colors: Rewriting of documentation to fix errors and clarify usage --- layers/+themes/colors/README.org | 70 ++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/layers/+themes/colors/README.org b/layers/+themes/colors/README.org index b340b0ebd..2b2e32054 100644 --- a/layers/+themes/colors/README.org +++ b/layers/+themes/colors/README.org @@ -14,13 +14,13 @@ - [[#nyan-mode][Nyan Mode]] * Description -This layer colors your life with: -- [[https://github.com/Fanael/rainbow-identifiers][rainbow identifiers]] mode will colorize all identifiers (christmas tree mode :-)) - with an almost unique color. +This layer colors your life with the help of the following packages: +- [[https://github.com/Fanael/rainbow-identifiers][rainbow-identifiers]] mode will colorize all identifiers (christmas tree mode :-)) + with mostly unique colors, and the ability to choose saturation and lightness. - [[https://github.com/ankurdave/color-identifiers-mode][color-identifiers]] mode will colorize only identifiers recognized as variables. -- [[https://julien.danjou.info/projects/emacs-packages][rainbow mode]] displays strings representing colors with the color they +- [[https://julien.danjou.info/projects/emacs-packages][rainbow-mode]] displays strings representing colors with the color they represent as background. -- [[https://github.com/syl20bnr/nyan-mode][nyan mode]] display a Nyan cat progress bar in the mode-line. +- [[https://github.com/syl20bnr/nyan-mode][nyan-mode]] display a Nyan cat progress bar in the mode-line. * Install To use this configuration layer, add it to your =~/.spacemacs=. You will need to @@ -29,31 +29,39 @@ file. * Configuration ** Colorize identifiers -To colorize some identifiers by default in programming language buffers, set -the layer variables =colors-colorize-identifiers= to either =variables= or -=all=. =variables= will colorize only words recognized as variables, =all= -will colorize all the words. +To colorize variable identifiers using color-identifiers and its supported languages, +set the layer variable =colors-colorize-identifiers= to =variables=. + +If you want to colorize all identifiers using the more universal rainbow-identifiers +method instead, set the layer variable =colors-colorize-identifiers= to =all=. #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( (colors :variables colors-colorize-identifiers 'all))) #+END_SRC -When using the value =all= the Saturation and lightness of can be set per theme -by adding an entry in the variable =colors-theme-identifiers-sat&light=. This is -an alist where the key is a theme symbol and the value is a pair =(saturation -lightness)=. +When using the value =all= (rainbow-identifiers method), the Saturation and Lightness +used for colors can be set on a per-theme basis by adding an entry to the variable +=colors-theme-identifiers-sat&light=. This is an alist where the key is a theme symbol +and the value is a pair =(saturation lightness)=. -For now saturation and lightness are not supported with the =variables= value. +For now, saturation and lightness are not supported via a =variables= value! +Instead, you must push themes into the alist in your =dotspacemacs/user-config= section, +and then refresh the values to ensure your overrides are applied to your current theme. Example: #+BEGIN_SRC emacs-lisp - (push '(mytheme . (50 50)) colors-theme-identifiers-sat&light) + (defun dotspacemacs/user-config () + ;; add per-theme sat&light overrides and refresh values for your current theme + (push '(mytheme . (50 50)) colors-theme-identifiers-sat&light) + (push '(anothertheme . (90 40)) colors-theme-identifiers-sat&light) + (colors//tweak-theme-colors spacemacs--cur-theme) + ) #+END_SRC ** Enable Nyan cat -To enable the package =nyan-mode= set the variable +To enable the package =nyan-mode= just set the variable =colors-enable-nyan-cat-progress-bar= to =t=: #+BEGIN_SRC emacs-lisp @@ -61,8 +69,8 @@ To enable the package =nyan-mode= set the variable (colors :variables colors-enable-nyan-cat-progress-bar t))) #+END_SRC -It may be handy to enable it only in a GUI, you can do it by using -a quasi-quoted list: +It may be handy to enable it only when Emacs is running in a GUI. +You can do that by using a quasi-quoted list which checks the Emacs mode: #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( @@ -73,15 +81,15 @@ a quasi-quoted list: * Key bindings ** Colorize Identifiers -| Key Binding | Description | -|---------------+--------------------------------------------------------------| -| ~SPC t C a~ | colorize all identifiers in current buffer | -| ~SPC t C C-a~ | globally colorize all identifiers and all subsequent buffers | -| ~SPC t C v~ | colorize only variables in current buffer | -| ~SPC t C C-v~ | globally colorize only variables and all subsequent buffers | +| Key Binding | Description | +|---------------+-----------------------------------------------------------------------| +| ~SPC t C a~ | colorize all identifiers in current buffer (rainbow-identifiers mode) | +| ~SPC t C C-a~ | globally colorize all identifiers and all subsequent buffers | +| ~SPC t C v~ | colorize only variables in current buffer (color-identifiers mode) | +| ~SPC t C C-v~ | globally colorize only variables and all subsequent buffers | -The =saturation= and =lightness= of rainbow identifier mode's colors -can be adjusted live via the transient-state: +The =saturation= and =lightness= of rainbow-identifier mode's colors +can be adjusted live via the following transient-state: | Key Binding | Description | |-----------------+------------------------------------------| @@ -96,11 +104,19 @@ can be adjusted live via the transient-state: [[file:img/rainbow-mode.png]] -=rainbow-mode= mode can be toggled on and off with: +=rainbow-mode= mode is different from both rainbow-identifiers and color-identifiers. +It can be used together with either (or none) of the identifier colorizers. + +All detected color codes in the current buffer will be be highlighted as their +actual color. However, for accurate display, this mode requires that you use +GUI Emacs and that you haven't disabled sRGB mode (if your platform uses that). + +To enable, you must manually toggle it on and off on a per-buffer basis with: ~SPC t C c~ ** Nyan Mode + =nyan-mode= mode can be toggled on and off with: ~SPC t m n~