X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fcolors.md;h=81cbc194cca63707d913b13c91854e4f32bf07cc;hb=f3e8413e772924947238bdb9f928375e24ff7213;hp=38ea17844bede48e9a533b66d399d62eb5aeec02;hpb=532f932712e7bb549678c016891163d4fa7e67ed;p=micro.git diff --git a/runtime/help/colors.md b/runtime/help/colors.md index 38ea1784..81cbc194 100644 --- a/runtime/help/colors.md +++ b/runtime/help/colors.md @@ -2,37 +2,54 @@ 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 -To change your colorscheme, press Ctrl-E in micro to bring up the command +To change your colorscheme, press Ctrl-e in micro to bring up the command prompt, and type: ``` -set colorscheme monokai +set colorscheme twilight ``` (or whichever colorscheme you choose). -Micro comes with a number of colorschemes by default. Modern terminals tend to -have three different kinds of color support. The most common is 256 color where -the terminal provides 256 standardized colors (except the first 16 may be configured -by the user). A 256-color theme requires a terminal with 256 color support and -is the most portable. - -A 16-color theme uses the 16 user-configurable colors (or 16 default colors on -old terminals). These colorschemes are guranteed to work, but won't look great -unless the 16 colors are configured to the user's liking. Using a 16-color theme -will also preserve the terminal's theme because the terminal usually uses its 16 -colors for prompts or other coloring. - -Some terminals support "true color" with 16 million colors (using standard RGB values). -There is no one standard for this color support among terminals so this method -is not guaranteed to work. Usually truecolor must also be enabled by the user. The -colorschemes using true color will look exactly as intended. If true color is not -supported, a true color colorscheme will approximate its colors to 256-color. +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: @@ -61,7 +78,9 @@ These may vary widely based on the 16 colors selected for your terminal. ### True color -These require terminals that support true color and require `MICRO_TRUECOLOR=1` (this is an environment variable). +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. @@ -75,9 +94,12 @@ These require terminals that support true color and require `MICRO_TRUECOLOR=1` 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). -They are only about 18-30 lines in total. +Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory. + +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: @@ -200,7 +222,7 @@ 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 @@ -218,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: @@ -237,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 @@ -316,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).