X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fcolors.md;h=e17107d048fdbf9c1610433c64b6bdc59986a5ac;hb=24a684cff25cd9f189a943d1dc2a98d3aa6c796f;hp=d26d8924e6a157e7240f1d82c8fc59a9e30fba93;hpb=74e79dc8f2a088d1c4e321ada11bb02159a1f6b9;p=micro.git diff --git a/runtime/help/colors.md b/runtime/help/colors.md index d26d8924..e17107d0 100644 --- a/runtime/help/colors.md +++ b/runtime/help/colors.md @@ -2,87 +2,104 @@ This help page aims to cover two aspects of micro's syntax highlighting engine: -- How to create colorschemes and use them -- How to create syntax files to add to the list of languages micro can highlight - +* How to create colorschemes and use them. +* How to create syntax files to add to the list of languages micro can highlight. ## Colorschemes -Micro comes with a number of colorschemes by default. Here is the list: - -* simple: this is the simplest colorscheme. It uses 16 colors which are set by - your terminal - -* mc: A 16-color theme based on the look and feel of GNU Midnight Commander. - This will look great used in conjunction with Midnight Commander. - -* nano: A 16-color theme loosely based on GNU nano's syntax highlighting. - -* monokai: this is the monokai colorscheme; you may recognize it as Sublime - Text's default colorscheme. It requires true color to look perfect, but the - 256 color approximation looks very good as well. It's also the default - colorscheme. - -* zenburn: The 'zenburn' colorscheme and works well with 256 color terminals - -* solarized: this is the solarized colorscheme. You should have the solarized - color palette in your terminal to use it. - -* solarized-tc: this is the solarized colorscheme for true color; just make sure - your terminal supports true color before using it and that the MICRO_TRUECOLOR - environment variable is set to 1 before starting micro. +To change your colorscheme, press CtrlE in micro to bring up the command +prompt, and type: -* atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme. It - requires true color to look good. - -* cmc-16: A very nice 16-color theme. Written by contributor CaptainMcClellan - (Collin Warren.) Licensed under the same license as the rest of the themes. - -* cmc-paper: Basically cmc-16, but on a white background. (Actually light grey - on most ANSI (16-color) terminals) +``` +set colorscheme twilight +``` -* cmc-tc: A true colour variant of the cmc theme. It requires true color to +(or whichever colorscheme you choose). + +Micro comes with a number of colorschemes by default. The colorschemes that you +can display will depend on what kind of color support your terminal has. + +Modern terminals tend to have a palette of 16 user-configurable colors (these +colors can often be configured in the terminal preferences), and additional +color support comes in three flavors. + +* 16-color: A colorscheme that uses the 16 default colors will always work but + will only look good if the 16 default colors have been configured to the user's + liking. Using a colorscheme that only uses the 16 colors from the terminal palette + will also preserve the terminal's theme from other applications since the terminal + will often use those same colors for other applications. Default colorschemes + of this type include `simple` and `solarized`. + +* 256-color: Almost all terminals support displaying an additional 240 colors on + top of the 16 user-configurable colors (creating 256 colors total). Colorschemes + which use 256-color are portable because they will look the same regardless of + the configured 16-color palette. However, the color range is fairly limited + due to the small number of colors available. Default 256-color colorschemes + include `monokai`, `twilight`, `zenburn`, `darcula` and more. + +* true-color: Some terminals support displaying "true color" with 16 million + colors using standard RGB values. This mode will be able to support displaying + any colorscheme, but it should be noted that the user-configured 16-color palette + is ignored when using true-color mode (this means the colors while using the + terminal emulator will be slightly off). Not all terminals support true color + but at this point most do. True color support in micro is off by default but + can be enabled by setting the environment variable `MICRO_TRUECOLOR` to 1. + In addition your terminal must support it (usually indicated by setting `$COLORTERM` + to `truecolor`). + True-color colorschemes in micro typically end with `-tc`, such as `solarized-tc`, + `atom-dark-tc`, `material-tc`, etc... If true color is not enabled but a true + color colorscheme is used, micro will do its best to approximate the colors + to the available 256 colors. + +Here is the list of colorschemes: + +### 256 color + +These should work and look nice in most terminals. I recommend these +themes the most. + +* `monokai` (also the `default` colorscheme) +* `zenburn` +* `gruvbox` +* `darcula` +* `twilight` +* `railscast` +* `bubblegum` + +### 16 color + +These may vary widely based on the 16 colors selected for your terminal. + +* `simple` +* `solarized` (must have the solarized color palette in your terminal to use this colorscheme properly) +* `cmc-16` +* `cmc-paper` +* `geany` + +### True color + +True color requires your terminal to support it. This means that the environment variable +`COLORTERM` should have the value `truecolor`, `24bit`, or `24-bit`. In addition, to enable +true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1. + +* `solarized-tc`: this is the solarized colorscheme for true color. +* `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme. +* `cmc-tc`: A true colour variant of the cmc theme. It requires true color to look its best. Use cmc-16 if your terminal doesn't support true color. - -* codeblocks: A colorscheme based on the Code::Blocks IDE's default syntax - highlighting. - -* codeblocks-paper: Same as codeblocks, but on a white background. (Actually - light grey) - -* github-tc: A colorscheme based on Github's syntax highlighting. Requires true - color to look its best. - -* paper-tc: A nice minimalist theme with a light background, good for editing - documents on. Requires true color to look its best. Not to be confused with - `-paper` suffixed themes. - -* geany: Colorscheme based on geany's default highlighting. - -* geany-alt-tc: Based on an alternate theme bundled with geany. - -* flamepoint-tc: A fire inspired, high intensity true color theme written by - CaptainMcClellan. As with all the other `-tc` suffixed themes, it looks its - best on a - -To enable one of these colorschemes just press CtrlE in micro and type -`set colorscheme solarized`. (or whichever one you choose). You can also use -`set colorscheme monochrome` if you'd prefer to have just the terminal's default -foreground and background colors. Note: This provides no syntax highlighting! - -See `help gimmickcolors` for a list of some true colour themes that are more -just for fun than for serious use. (Though feel free if you want!) - +* `gruvbox-tc`: The true color version of the gruvbox colorscheme +* `github-tc`: The true color version of the Github colorscheme ## Creating a Colorscheme -Micro's colorschemes are also extremely simple to create. The default ones ca -be found -[here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes). +Micro's colorschemes are also extremely simple to create. The default ones can +be found [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes). + +Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory. -They are only about 18-30 lines in total. +A number of custom directives are placed in a `.micro` file. Colorschemes are +typically only 18-30 lines in total. -Basically to create the colorscheme you need to link highlight groups with +To create the colorscheme you need to link highlight groups with actual colors. This is done using the `color-link` command. For example, to highlight all comments in green, you would use the command: @@ -195,7 +212,7 @@ Here's a list of subgroups used in micro's built-in syntax files. * identifier.var * preproc.shebang (The #! at the beginning of a file that tells the os what script interpreter to use) -* symbol.brackets ({}()[] and sometimes <>) +* symbol.brackets (`{}()[]` and sometimes `<>`) * symbol.operator (Color operator symbols differently) * symbol.tag (For html tags, among other things) * type.keyword (If you want a special highlight for keywords like `private`) @@ -205,14 +222,14 @@ In the future, plugins may also be able to use color groups for styling. ## Syntax files -The syntax files is written in yaml-format and specify how to highlight +The syntax files are written in yaml-format and specify how to highlight languages. Micro's builtin syntax highlighting tries very hard to be sane, sensible and provide ample coverage of the meaningful elements of a language. Micro has -syntax files built int for over 100 languages now. However, there may be +syntax files built in for over 100 languages now! However, there may be situations where you find Micro's highlighting to be insufficient or not to your -liking. Good news is you can create syntax files (.micro extension), place them +liking. The good news is that you can create your own syntax files, and place them in `~/.config/micro/syntax` and Micro will use those instead. ### Filetype definition @@ -223,7 +240,7 @@ You must start the syntax file by declaring the filetype: filetype: go ``` -#### Detect definition +### Detect definition Then you must provide information about how to detect the filetype: @@ -242,7 +259,7 @@ detect: header: "%YAML" ``` -#### Syntax rules +### Syntax rules Next you must provide the syntax highlighting rules. There are two types of rules: patterns and regions. A pattern is matched on a single line and usually a @@ -321,3 +338,16 @@ example, the following is possible for html: rules: - include: "css" ``` + +## Syntax file headers + +Syntax file headers are an optimization and it is likely you do not need to +worry about them. + +Syntax file headers are files that contain only the filetype and the detection +regular expressions for a given syntax file. They have a `.hdr` suffix and are +used by default only for the pre-installed syntax files. Header files allow micro +to parse the syntax files much faster when checking the filetype of a certain +file. Custom syntax files may provide header files in `~/.config/micro/syntax` as +well but it is not necessary (only do this if you have many (100+) custom syntax +files and want to improve performance).