xterm16.txt

*xterm16* An adjustable contrast color scheme for GUI & Terminals.

DESCRIPTION                                                      *xterm16.vim*
    An adjustable contrast fully customizable color scheme for GUI & 8, 16 or
    256 color terminals, designed to minimize eyestrain. The main features
    are:

	- Four color maps:
	    'allblue'   : A colormap with most foreground colors blueish (to
		          minimize contrast etc.)
	    'soft'      : A colormap with foreground colors of similar
		          intensities to reduce eyestrain.
	    'softlight' : A colormap with a bright background (for web
		          hosting etc.)
	    'standard'  : A colormap for use on terminals with only 8/16
			   colors.
	  The first three colormaps will work only on 256 color capable
	  terminals or the GUI. The last one will work anywhere.

	- Adjustable brightness / contrast. Lets you easily adjust the
	  brightness and contrast settings. Extremely useful (for instance)
	  when there is a glare on your monitor, or for long late dim light
	  dim light late at night :)

	- Terminal and GUI support. If you use xterm, rxvt or mrxvt (compiled
	  with 256 colors), then the colors on your terminal will be almost
	  identical to your GUI colors. On any other terminal emulator, a few
	  scripts (included) and parts of this help are designed to help you
	  get the colors you want.

	- LCD / CRT Monitor support. The color response of LCD and CRT
	  monitors is pretty different. This color scheme has an option to
	  adjust colors on CRT monitors to give a similar appearance.

	- Customizable colors. If you find any color unreadable or ugly, you
	  can change it easily. When adjusting the brightness, your custom
	  colors will be suitably adjusted too!

	- Customizable highlighting groups. If you don't like the highlighting
	  of any particular group, you can change it to suit your needs. This
	  is useful for instance if you want the cursor to be brighter than
	  everything else / etc.

INSTALLATION                                            *xterm16-installation*
    For local installation, put the |xterm16.vim| file in your ~/.vim/colors
    directory. To install globally put it in $VIMRUNTIME/colors. Finally add
    the following lines to your {.vimrc}: >

	" Select colormap: 'soft', 'softlight', 'standard' or 'allblue'
	let xterm16_colormap	= 'allblue'

	" Select brightness: 'low', 'med', 'high', 'default' or custom levels.
	let xterm16_brightness	= 'default'

	colo xterm16

<   You might also want to put |xterm16.txt| in the help directory (~/.vim/doc
    or $VIMRUNTIME/doc).

OPTIONS                                                      *xterm16-options*

  Colormap, brightness and contrast options: ~
    |xterm16_brightness|   : Set the brightness / contrast
    |xterm16_colormap|	   : Select the colormap (standard / soft)
    |:Brightness|	   : Adjust the brightness / contrast and or colormap

  Customizing colors or highlighting: ~
    |xterm16_custom_color| : Customize some (or all) colors.
    |xterm16_custom_group| : Customize some (or all) highlighting groups.
    |xterm16_CRTColors|	   : Setup defaults for CRT monitors.
    |xterm16_NoHtmlColors| : Disable remapping of html colors.
    |xterm16_example|	   : An example of these options :)

  Adjusting colors on terminals: ~
    |xterm16_trmcolors|	   : A short HOWTO to help you get the same colors on
			     the terminal and GUI.

  Options controlling colors on terminals: ~
    |xterm16_termtype|	   : Select the terminal emulator (xterm, rxvt)
    |xterm16_ccube|	   : Specify the color cube of the terminal.
    |xterm16_NoRemap|	   : Disable dark blue remapping on 8 color terminals
    |xterm16_TermRegexp|   : Regexp of terminals where darkblue is unreadable

PACKAGE CONTENTS                                            *xterm16_filelist*

    |changelog.txt|	: List of changes
    |cpalette.pl|	: Perl script to help you set colors in rxvt/xterm etc
    |xterm16.ct|	: Help change colors on Linux console.
    |xterm16.schema|	: Help change colors on KDE's terminal (Konsole).
    |xterm16.txt|	: This help file
    |xterm16.vim|	: Actual color scheme script

------------------------------------------------------------------------------
ADJUSTING THE BRIGHTNESS OR CONTRAST                      *xterm16_brightness*

    The brightness and contrast are controlled by the global variable
    |xterm16_brightness|. This color scheme uses three different color
    intensities: {low}, {medium} and {high}. These intensities are used
    differently in each of the colormaps. See the |xterm16_colormap| section
    for an explanation of how these intensities are used.

    The brightness / contrast can be controlled by changing these intensities.
    You can do this by setting the global variable |xterm16_brightness|, using
    any of the following formats: >

	let xterm16_brightness = '#llmmhh'
	let xterm16_brightness = 'lmh'
	let xterm16_brightness = 'low|default|med|high'

<   In the first format, 'll' 'mm' and 'hh' are the intensities (2 digit hex)
    of the {low}, {medium} and {high} levels respectively. In the second
    format 'l', 'm' and 'h' are numbers from 0 - 5 specifying the respective
    intensities. This corresponds to the levels in the 6x6x6 color cube used
    by a 256 color terminals. The final format selects either a low, medium or
    high brightness respectively. These are different depending on the
    colormap you are using. In the 'allblue' colormap they are '123'
    (#5f87af), '234' (#87afd7) and '345' (#afd7ff) respectively.

								 *:Brightness*
    You can change the brightness (and optionally the colormap) by using the
    command >

	:Brightness <brightness> [colormap]

<   This is convenient if you want to try out / temporarily change the
    brightness or colormap. Once you find a brightness / colormap you like,
    set the global variables |xterm16_brightness| and |xterm16_colormap| in
    your {.vimrc}.

CHANGING THE COLORMAP                                       *xterm16_colormap*

    This color scheme comes with four different color maps: 'standard',
    'soft', 'softlight' and 'allblue'. My preference is to use 'allblue' by
    default, 'softlight' when there is a glare on my screen, and 'standard'
    when I use a terminal with only 8/16 colors (e.g. when I ssh using Putty).
    
    You can select your colormap by setting the global variable
    |xterm16_colormap|. The default is to use the 'allblue' colormap if
    possible (in GUI or a terminal supporting 256 colors) and the 'standard'
    colormap otherwise.

    The 'standard' colormap uses 8 standard colors (of {medium} intensity),
    and the same colors of {high} intensity. Dark grey is of {low} intensity.

    The 'soft' colormap is designed so that all foreground colors appear to be
    of similar intensity (to reduce the strain on your eyes). We do this as
    follows: The {low} intensity is used for background colors. Some colors
    (like green for instance) appear a lot brighter than other colors (like
    blue). So we use the {medium} intensity for greenish colors and the {high}
    intensity for blueish colors. See |xterm16_brightness| for how to adjust
    these intensities to your taste.

    The 'softlight' colormap is designed to be readable on a bright
    background. It uses {low}, {medium} and {high} intensities in the same way
    as the 'soft' colormap. The {low} levels still represent backgrounds, so
    you might want to set it to some high number. For example, setting {low}
    to 4, {medium} to 1 and {high} to 2 in the 'softlight' colormap produces
    reasonable results.

    Finally the 'allblue' colormap is designed to that almost all colors are
    blueish. I have found this to be least strain on the eyes, while still
    being able to tell apart different syntax elements. In this colormap the
    {low} is again used for background color levels. The {medium} is the
    lowest (non-zero) intensity you want foreground colors, and {high} is the
    highest intensity you want foreground colors. For example setting the
    {low}, {medium} and {high} levels to 1, 1 and 3 produces reasonable (dark)
    results.

    NOTE: By default this color scheme is designed for LCD monitors. If you
    have a CRT monitor, see |xterm16_CRTColors| for how to adjust the colors
    to suit CRT monitors.

    NOTE: On terminals WITHOUT 256 colors, you can only use the 'standard'
    colormap. The reason for this is because the 'soft', and 'allblue' color
    maps have a few unreadable dark colors (used as backgrounds), and possibly
    use more than 16 colors in total. If you change your terminal palette to
    that of the 'soft' or 'allblue' colormap, then you'll have trouble reading
    text in non-Vim applications. If you want to use the 'soft' or 'allblue'
    colormaps (as I recommend), either use a terminal supporting 256 colors
    (xterm, rxvt, mrxvt), or modify the source :)

------------------------------------------------------------------------------
CUSTOMIZING COLORS                                      *xterm16_custom_color*

    Different monitors show colors differently. All colors of this color
    scheme are readable on my monitor. However if you have trouble with some
    colors, you can change them by setting the variable |xterm16_colorname|.
    The color names used are different on each colormap. The 'standard'
    colormap uses the colors: >

	none black darkred darkgreen darkyellow darkblue darkmagenta darkcyan
	grey darkgrey red green yellow blue magenta cyan white

<   The 'soft' and 'softlight' colormaps use the colors: >

	black darkred darkyellow darkcyan darkblue darkgrey grey lightgrey red
	lightbrown yellow green bluegreen skyblue magenta cyan purple white

<   The 'allblue' colormap uses the colors: >

	black darkred darkcyan darkblue grey1 grey2 grey3 grey4 grey5 grey
	white1 red lightbrown yellow dirtygreen green bluegreen yellowgreen
	skyblue lightblue lightcyan darkpurple purple lightpurple

<   (I know this looks like a lot of colors for a colormap that calls itself
    'allblue'. The point is that the colors that usually show up in regular
    text / code are all shades of blue (except "Type" and "Special", which are
    shades of green). So most code will look pretty much blueish. But error
    messages and other vim niceties will be in other colors.)

    The format of this variable is one of >

	let xterm16_blue = '#rrggbb'
	let xterm16_blue = 'nnn'
	let xterm16_blue = 'Ldddddd'

<   The first format specifies the red / green / blue intensities in two digit
    hex. The second format specifies the red / green / blue intensities as a
    level between 0-5 number. (This is like specifying the color in a 6x6x6
    RGB cube, as used by a 256 color terminals).

    Finally the most useful format is the 'Ldddddd'. Here 'L' is the intensity
    level (either 'l', 'm' or 'h' for low medium or high respectively). The
    first two digits 'dd' are HALF the percentage intensity of the red
    intensity. The second two, green and last two blue. So for instance
    'm005035' corresponds to a color with no red component, a green component
    equal to the 'medium' intensity level, and a blue component that is 70% of
    the 'medium' intensity level.

    The advantage is that when you change the brightness / contrast, this
    color will change accordingly. See |xterm16_example| for an example.

    NOTE: If you set the variable |xterm16_CRTColors| then some of your
    default colors will be overridden. If you want to use your custom colors,
    and the CRT settings, first set |xterm16_CRTColors| and load this color
    scheme. The global variables 'xterm16_colorname' will be set for all
    modified colors. Now unset |xterm16_CRTColors|, copy these colors into
    your vimrc, and modify any other color you like as desired.

CUSTOMIZING HIGHLIGHTING GROUPS                         *xterm16_custom_group*

    If you don't like a few highlighting groups, you can change them by
    setting the variables *xterm16fg_GroupName* *xterm16bg_GroupName* and / or
    *xterm16attr_GroupName* . These variables control the foreground color,
    background color and GUI/cterm attributes of {GroupName} respectively.
    {GroupName} is the name of the group whose highlighting you want to
    change. For a list of group names see |highlight-groups| and |group-name|.

    The format of these variables is the same as the format for colors. In
    addition you can also use a named color from the colormap. See
    |xterm16_custom_color| above. As an example: >

	let xterm16bg_Cursor = '#00ff00' " Make cursor bright green

CRT MONITORS                                               *xterm16_CRTColors*

    By default the colors in this color scheme are designed for LCD monitors.
    If you have a CRT monitor, set the vim variable |xterm16_CRTColors| in
    your .vimrc. This will adjust the colors to suit CRT monitors. With an
    unspecified brightness and 'standard' colormap, this will produce exactly
    the same colors as the original version of xterm16. If the colors still
    look unreadable and you want to change them, read the section on
    |xterm16_custom_color|.

    NOTE: Setting this variable will override some (maybe all) of your
    customized colors. See the note at the end of |xterm16_custom_color|.

    NOTE: Setting this variable will have no effect under the 'allblue'
    colormap. This colormap does not look too different under CRT monitors.
    Also modifications will probably render a few shades of blue used by this
    colormap indistinguishable.

HTML HIGHLIGHTING GROUPS                                *xterm16_NoHtmlColors*

    Html groups use cterm attributes (which SUCK), so we change them here. The
    GUI attributes are OK, and are unchanged. If you do not want your precious
    html groups touched, set the variable |xterm16_NoHtmlColors| in your
    {.vimrc}

    If html colors don't work correctly, set the variable |html_no_rendering|

							     *xterm16_example*
    As an example, the following will produce exactly the same colors as the
    original version of xterm16: >

	let g:xterm16_colormap		= 'standard'
	let g:xterm16_brightness	= '#80cdff'
	let g:xterm16_darkblue		= 'h000050'
	let g:xterm16_blue		= 'h002550'
	let g:xterm16_grey		= 'm474747'

<   NOTE: This is done by default if you set the variable |xterm16_CRTColors|,
    and use a terminal with less than 256 colors (or use the 'standard'
    colormap).

------------------------------------------------------------------------------
ADJUSTING COLORS ON TERMINALS                              *xterm16_trmcolors*

    Depending on which terminal emulator you use, you might have to tweak the
    settings a little to get good results on your terminal emulator. On 256
    color capable terminals, you might have to make vim aware that your
    terminal has 256 colors. On terminals that are only capable of using 16
    colors, you will have to adjust the palette.

    If you use recent versions of xterm, rxvt or mrxvt, or your terminal
    emulator claims to support 256 colors, then read the help topic
    |xterm16-256cterm|. If not, read the help topic |xterm16-16cterm|.

							    *xterm16-256cterm*
    Terminals which support 256 colors: ~

    Some terminal emulators like xterm, rxvt and mrxvt support 256 colors if
    compiled in. A simple way to check if 256 colors are supported in your
    terminal is to type the following the bash prompt: >

	$ echo -e "\e[38;5;196mred\e[38;5;46mgreen\e[38;5;21mblue\e[0m"

<   If you see the words red, green and blue in the correct colors, then
    you've got 256 colors. If not, I recommend compiling 256 color support in
    (use --enable-256-colors at compile time for xterm / mrxvt). If this is
    not possible, try looking under |xterm16-16cterm|.

    Once you know your terminal is 256 color capable, check to see if Vim is
    aware of this. Start up vim in your terminal emulator and type >

	:echo &t_Co

<   If vim reports "256", then you need not make any modifications. If vim
    reports 8 or 16, then add the following code snippet to your {.vimrc}: >

	au VimEnter *
        	\ if &term == 'xterm'		|
        	\ 	set t_Co=256		|
        	\ endif

<   Replace 'xterm' above with the value of $TERM.

    NOTE: You can also fix this by modifying the terminfo files on your
    system. See the man pages of terminfo, infocmp and tic.

    NOTE: rxvt users will need to set the variable |xterm16_termtype| and or
    |xterm16_ccube| to get colors which are identical to those on the GUI.
    
    NOTE: If in addition you want to adjust the default colors of your
    terminal (for consistency with other applications) read the section on
    |xterm16-modcolors|.

							 *xterm16-transparent*
    Finally, if you use a terminal that supports pseudo transparency (like
    mrxvt), and want your vim to appear transparent use: >

	if $DISPLAY != '' && !has('gui_running') && $MRXVT_TABTITLE != ''
	    let xterm16bg_Normal = 'none'
	endif

<   This might not work on 16 color terms, but you're welcome to try :). This
    definitely works on mrxvt versions 0.4.1 or later.

							     *xterm16-16cterm*
    Terminals with only 8 or 16 color support: ~

    If your terminal emulator does not support 256 colors, you will have to
    manually modify the terminal palette to obtain the colors in this color
    scheme. NOTE: You can only use the 'standard' colormap in such terminals.
    See the section on |xterm16_colormap| for details.

    First I suggest attempting to at least get 16 colors (and not settle for
    only 8 colors). This looks a little nicer than using bold fonts. Read the
    section on in the vim help under |xfree-xterm|, and hope that works.

							   *xterm16-modcolors*
    Now to modify your terminal colors, the first thing you need to do is to
    figure out the colors this color scheme is using. To do this, load this
    color scheme in gvim, and adjust the brightness / contrast to your taste.
    Don't forget to use the 'standard' colormap. Now the global variable
    |xterm16_palette| contains all the colors that are currently being used.

    If you use xterm, or some fork of rxvt (like mrxvt, aterm, wterm etc),
    follow the instructions in |xterm16-xdefaults|. For konsole or
    gnome-terminal see |xterm16-konsole| and |xterm16-gnome-terminal|
    respectively. Finally for the Linux console, see |xterm16-ctheme|.

							   *xterm16-xdefaults*
    For xterm or some fork of rxvt, do the following: Once the colors are
    adjusted to your taste, edit the file ~/.Xdefaults or ~/.Xresources (or
    ~/.mrxvtrc for mrxvt). Paste in the contents of the vim variable
    |xterm16_palette| (use <C-R>=xterm16_palette for instance). Now filter
    those lines through the supplied perl script *cpalette.pl* by typing >

	:'<,'>!perl -w /path/to/cpalette.pl -x --class trmname

<   where trmname is the resource class of your terminal. Generally this is
    the same as the terminal name. For xterm use "xterm.vt100" as the class,
    and for mrxvt use "Mrxvt" as the class. (|cpalette.pl| can do a few other
    things. Type "cpalette.pl -h" for options).

    If your terminal gets it's resources via the X window system [using
    XGetDefaults()], then you have to merge the above file with your current
    resource using >

	$ xrdb -merge ~/.Xresources

<   If your terminal directly reads the resource file, then just restart the
    terminal and you should be fine :). See the terminal version / man file to
    figure out if you need to merge your resources or not.

							     *xterm16-konsole*
    For konsole, the file *xterm16.schema* contains the colors of this color
    scheme with 'standard' colormap, default brightness and CRTColors. If you
    use a different colormap / brightness, get the palette from the variable
    |xterm16_palette|, and modify the file appropriately. You'll need to
    convert the palette from to decimal. The following few lines might help: >

	" Brightness 134 (high), colormap standard
	let palette = '#000000 #af0000 #00af00 #afaf00 #0000af #af00af #00afaf #9a9a9a #5f5f5f #d70000 #00d700 #d7d700 #0000d7 #d700d7 #00d7d7 #d7d7d7'

	let i = 0
	while i < 16
	    echo 'Color' i '0x'.strpart(palette,i*8+1,2)+0 '	'
		    \ '0x'.strpart(palette,i*8+3,2)+0 '	'
		    \ '0x'.strpart(palette,i*8+5,2)+0
	    let i = i + 1
	endwhile

<   To change the default colors on Konsole, add the file |xterm16.schema| to
    ~/.kde/share/apps/konsole. Select the "Xterm 16 Colors" schema from the
    schema menu.

						      *xterm16-gnome-terminal*
    For gnome-terminal you can change the colors by running gconf-editor and
    selecting the apps - gnome-terminal - profiles - Default menu, and change
    the palette option to the string (all in one line!) >

	#000000:#af0000:#00af00:#afaf00:#0000af:#af00af:#00afaf:#9a9a9a:#5f5f5f:#d70000:#00d700:#d7d700:#0000d7:#d700d7:#00d7d7:#d7d7d7

<   If you changed the brightness / colormap, you might want to replace the
    above line with your current colormap (obtained from the variable
    |xterm16_palette|).

							      *xterm16-ctheme*
    ctheme can be used to change the colors on your Linux console (neat huh?).
    Find more information about it at >

	http://www.sourceforge.net/projects/ctheme/

<   The file *xterm16.ct* contains the colors of this color scheme with
    'standard' colormap, default brightness and CRTColors. If you use a
    different colormap / brightness, get the palette from the variable
    |xterm16_palette|, and modify the file appropriately.

    If necessary, change the first line of |xterm16.ct| to point to the
    correct location of ctheme, then run it with your ctheme. Thanks to
    Juhapekka Tolvanen <juhtolv@iki.fi> (http://iki.fi/juhtolv) for providing
    this theme, and informing me of the existence of ctheme!

------------------------------------------------------------------------------
COLOR SCHEME PALETTE                                          *xterm16_palette*

    The global variable |xterm16_palette| contains the 16 color palette
    currently used by the color scheme. This is mainly so that you can easily
    obtain the palette, and use it to change the colors on your favourite
    terminal emulator.

CHANGING THE TERMINAL COLOR CUBE            *xterm16_termtype* *xterm16_ccube*

    The terminals that support 256 colors all have a 6x6x6 RGB color cube
    between the colors 16 to 231. Unfortunately, not all of them have the same
    color cube. Rxvt uses a uniform RGB color cube, but xterm and mrxvt do
    not.

    This color scheme tries to guess which terminal you're using, and use the
    appropriate color cube. The guessing is done as follows:

	1. If the environment variable MRXVT_TABTITLE is defined, then we
	   assume you're using mrxvt.
	2. Otherwise, if your TERM variable is set to something beginning with
	   "rxvt", then we assume you're using rxvt.
	3. Otherwise we assume you're using xterm.

    If the above will lead to an incorrect guess, set the vim variable
    |xterm16_termtype| to the terminal emulator you're using (currently only
    'rxvt' and 'xterm' are supported).

    If you use a different terminal with 256 colors, then you can get the
    colors right by setting the variable |xterm16_ccube|. The value of
    |xterm16_ccube| should be a 12 digit hex number (without the leading 0x).
    The first two digits are the intensity of the term level 0 (generally this
    is 00). The next two are the intensity of the term level 1, etc. The last
    two correspond to the level 5. (Remember the terminal colors are a 6x6x6
    RGB cube).
    
    You will probably have to read the source of your terminal emulator to
    figure out the intensities of the colors in the 6x6x6 color cube. However,
    if your terminal supports setting colors 16 - 231 using .Xdefaults or
    something, then you can use the supplied perl script |cpalette.pl| to
    generate a color cube of your choice. For example: >

	perl -w cpalette.pl --class xterm --ccube 002a557faad4 -g >> ~/.Xdefaults

<   will make the xterm color cube the same as the rxvt color cube.

UNREADABLE CONSOLE COLORS               *xterm16_NoRemap* *xterm16_TermRegexp*

    On a Linux console (and some other 8 color terminals), the dark blue
    (PreProc) is unreadable so we remap it. To disable this feature, set the
    variable |xterm16_NoRemap| in your {.vimrc}

    If this color gives you trouble on other terminals, and you want it
    changed elsewhere too set the variable |xterm16_TermRegexp| to a regexp
    matching all troublesome terminals.

    NOTE: This is only true in the 'standard' colormap. The 'soft' colormap
    does not use dark blue as a foreground, and hence no remapping is done.

------------------------------------------------------------------------------
>
 Maintainer	: Gautam Iyer <gautamATmathDOTuchicagoDOTedu>
 Modified	: Thu 18 May 2006 04:28:25 PM CDT
 vim: ft=help:tw=78:iskeyword=!-~,^*,^|,^":ai: