Improve keybinding label consistency

[micro.git] / runtime / help / colors.md

diff --git a/runtime/help/colors.md b/runtime/help/colors.md
index 15bb05311d5e37ab53a4080ce524208ec84c9315..9ebb8689f223b1c5e1a0830440549c65e596dbc1 100644 (file)
--- a/runtime/help/colors.md
+++ b/runtime/help/colors.md
@@ -2,82 +2,115 @@
 
 This help page aims to cover two aspects of micro's syntax highlighting engine:
 
 
 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
+## Colorschemes

 
 

-Micro comes with a number of colorschemes by default. Here is the list:
+To change your colorscheme, press Ctrl-e in micro to bring up the command
+prompt, and type:

 
 

-* 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.
-
-* 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.)
-
-* 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! )
-
----
-
-### Creating a Colorscheme
+```
+set colorscheme twilight
+```

 
 

-Micro's colorschemes are also extremely simple to create. The default ones can be found
+(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.
+
+Omit color-link default "[fg color],[bg color]" will make the background color match the terminal's, and transparency if set.
+
+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.
+* `gruvbox-tc`: The true color version of the gruvbox colorscheme
+* `github-tc`: The true color version of the Github colorscheme
+* `material-tc`: Colorscheme based off of Google's Material Design palette
+
+## Creating a Colorscheme
+
+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).
 
 [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.

 
 

-Basically to create the colorscheme you need to link highlight groups with actual colors.
-This is done using the `color-link` command.
+A number of custom directives are placed in a `.micro` file. Colorschemes are 
+typically only 18-30 lines in total.
+
+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:
 
 
 For example, to highlight all comments in green, you would use the command:
 


@@ -99,7 +132,7 @@ If you would like no foreground you can just use a comma with nothing in front:
 color-link comment ",blue"
 ```
 
 color-link comment ",blue"
 ```
 

-You can also put bold, or underline in front of the color:
+You can also put bold, italic, or underline in front of the color:

 
 ```
 color-link comment "bold red"
 
 ```
 color-link comment "bold red"


@@ -109,20 +142,22 @@ color-link comment "bold red"
 
 There are three different ways to specify the color.
 
 
 There are three different ways to specify the color.
 

-Color terminals usually have 16 colors that are preset by the user. This means that
-you cannot depend on those colors always being the same. You can use those colors with
-the names `black, red, green, yellow, blue, magenta, cyan, white` and the bright variants
-of each one (brightblack, brightred...).
+Color terminals usually have 16 colors that are preset by the user. This means
+that you cannot depend on those colors always being the same. You can use those
+colors with the names `black, red, green, yellow, blue, magenta, cyan, white`
+and the bright variants of each one (brightblack, brightred...).

 
 

-Then you can use the terminals 256 colors by using their numbers 1-256 (numbers 1-16 will
-refer to the named colors).
+Then you can use the terminals 256 colors by using their numbers 1-256 (numbers
+1-16 will refer to the named colors).

 
 

-If the user's terminal supports true color, then you can also specify colors exactly using
-their hex codes. If the terminal is not true color but micro is told to use a true color colorscheme
-it will attempt to map the colors to the available 256 colors.
+If the user's terminal supports true color, then you can also specify colors
+exactly using their hex codes. If the terminal is not true color but micro is
+told to use a true color colorscheme it will attempt to map the colors to the 
+available 256 colors.

 
 

-Generally colorschemes which require true color terminals to look good are marked with a `-tc` suffix
-and colorschemes which supply a white background are marked with a `-paper` suffix.
+Generally colorschemes which require true color terminals to look good are
+marked with a `-tc` suffix and colorschemes which supply a white background are
+marked with a `-paper` suffix.

 
 ---
 
 
 ---
 


@@ -140,9 +175,10 @@ Here is a list of the colorscheme groups that you can use:
 * underlined
 * error
 * todo
 * underlined
 * error
 * todo

-* statusline ( Color of the statusline)
-* tabbar ( Color of the tabbar that lists open files.)
-* indent-char ( Color of the character which indicates tabs if the option is enabled)
+* statusline (Color of the statusline)
+* tabbar (Color of the tabbar that lists open files)
+* indent-char (Color of the character which indicates tabs if the option is
+  enabled)

 * line-number
 * gutter-error
 * gutter-warning
 * line-number
 * gutter-error
 * gutter-warning


@@ -150,29 +186,30 @@ Here is a list of the colorscheme groups that you can use:
 * current-line-number
 * color-column
 * ignore
 * current-line-number
 * color-column
 * ignore

-* divider ( Color of the divider between vertical splits. )
+* divider (Color of the divider between vertical splits)

 
 

-Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to be used.
+Colorschemes must be placed in the `~/.config/micro/colorschemes` directory to
+be used.

 
 ---
 
 In addition to the main colorscheme groups, there are subgroups that you can
 
 ---
 
 In addition to the main colorscheme groups, there are subgroups that you can

-specify by adding `.subgroup` to the group. If you're creating your own
-custom syntax files, you can make use of your own subgroups.
+specify by adding `.subgroup` to the group. If you're creating your own custom
+syntax files, you can make use of your own subgroups.

 
 

-If micro can't match the subgroup, it'll default to the root group, so 
-it's safe and recommended to use subgroups in your custom syntax files.
+If micro can't match the subgroup, it'll default to the root group, so  it's
+safe and recommended to use subgroups in your custom syntax files.

 
 

-For example if `constant.string` is found in your colorscheme, micro will
-use that for highlighting strings. If it's not found, it will use constant 
-instead. Micro tries to match the largest set of groups it can find in the
-colorscheme definitions, so if, for examle `constant.bool.true` is found then
-micro will use that. If `constant.bool.true` is not found but `constant.bool`
-is found micro will use `constant.bool`. If not, it uses `constant`. 
+For example if `constant.string` is found in your colorscheme, micro will us
+that for highlighting strings. If it's not found, it will use constant instead.
+Micro tries to match the largest set of groups it can find in the colorscheme
+definitions, so if, for examle `constant.bool.true` is found then micro will
+use that. If `constant.bool.true` is not found but `constant.bool` is found
+micro will use `constant.bool`. If not, it uses `constant`. 

 
 Here's a list of subgroups used in micro's built-in syntax files.
 
 
 Here's a list of subgroups used in micro's built-in syntax files.
 

-* comment.bright ( Some filetypes have distinctions between types of comments.)
+* comment.bright (Some filetypes have distinctions between types of comments)

 * constant.bool
 * constant.bool.true
 * constant.bool.false
 * constant.bool
 * constant.bool.true
 * constant.bool.false


@@ -180,68 +217,147 @@ Here's a list of subgroups used in micro's built-in syntax files.
 * constant.specialChar
 * constant.string
 * constant.string.url 
 * constant.specialChar
 * constant.string
 * constant.string.url 

-* identifier.class ( Also used for functions. )
+* identifier.class (Also used for functions)

 * identifier.macro
 * identifier.var
 * identifier.macro
 * 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.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` )
+* preproc.shebang (The #! at the beginning of a file that tells the os what
+  script interpreter to use)
+* 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`)

 
 In the future, plugins may also be able to use color groups for styling.
 
 
 In the future, plugins may also be able to use color groups for styling.
 

-### Syntax files

 
 

-The syntax files specify how to highlight certain languages.
+## Syntax files
+
+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 
+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 in for over 100 languages now! However, there may be 

 situations where you find Micro's highlighting to be insufficient or not to
 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 in 
-`~/.config/micro/syntax` and Micro will use those instead.
+your 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.

 
 

-The first statement in a syntax file will probably the syntax statement. This tells micro
-what language the syntax file is for and how to detect a file in that language.
+### Filetype definition

 
 

-Essentially, it's just
+You must start the syntax file by declaring the filetype:

 
 ```
 
 ```

-syntax "Name of language" "\.extension$"
+filetype: go

 ```
 
 ```
 

-For the extension, micro will just compare that regex to the filename and if it matches then it
-will use the syntax rules defined in the remainder of the file.
+### Detect definition

 
 

-There is also a possibility to use a header statement which is a regex that micro will compare
-with the first line of the file. This is almost only used for shebangs at the top of shell scripts
-which don't have any extension (see sh.micro for an example).
+Then you must provide information about how to detect the filetype:

 
 

----
+```
+detect:
+    filename: "\\.go$"
+```

 
 

-The rest of a syntax file is very simple and is essentially a list of regexes specifying how to highlight
-different expressions.
+Micro will match this regex against a given filename to detect the filetype.
+You may also provide an optional `header` regex that will check the first line
+of the file. For example:

 
 

-It is recommended that when creating a syntax file you use the colorscheme groups (see above) to
-highlight different expressions. You may also hard code colors, but that may not look good depending
-on what terminal colorscheme the user has installed.
+```
+detect:
+    filename: "\\.ya?ml$"
+    header: "%YAML"
+```
+
+### 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 single word as well. A region highlights between two patterns over multiple
+lines and may have rules of its own inside the region.

 
 

-Here is an example to highlight comments (expressions starting with `//`):
+Here are some example patterns in Go:

 
 ```
 
 ```

-color comment "//.*"
+rules:
+    - special: "\\b(break|case|continue|default|go|goto|range|return)\\b"
+    - statement: "\\b(else|for|if|switch)\\b"
+    - preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b"

 ```
 
 ```
 

-This will highlight the regex `//.*` in the color that the user's colorscheme has linked to the comment
-group.
+The order of patterns does matter as patterns lower in the file will overwrite
+the ones defined above them.

 
 

-Note that this regex only matches the current line. Here is an example for multiline comments (`/* comment */`):
+And here are some example regions for Go:

 
 ```
 
 ```

-color comment start="/\*" end="\*/"
+- constant.string:
+    start: "\""
+    end: "\""
+    rules:
+        - constant.specialChar: "%."
+        - constant.specialChar: "\\\\[abfnrtv'\\\"\\\\]"
+        - constant.specialChar: "\\\\([0-7]{3}|x[A-Fa-f0-9]{2}|u[A-Fa-f0-9]{4}|U[A-Fa-f0-9]{8})"
+
+- comment:
+    start: "//"
+    end: "$"
+    rules:
+        - todo: "(TODO|XXX|FIXME):?"
+
+- comment:
+    start: "/\\*"
+    end: "\\*/"
+    rules:
+        - todo: "(TODO|XXX|FIXME):?"

 ```
 
 ```
 

-Note: The format of syntax files will be changing with the view refactor.
-If this help file still retains this note but the syntax files are yaml
-please open an issue.
+Notice how the regions may contain rules inside of them. Any inner rules that
+are matched are then skipped when searching for the end of the region. For
+example, when highlighting `"foo \" bar"`, since `\"` is matched by an inner
+rule in the region, it is skipped. Likewise for `"foo \\" bar`, since `\\` is
+matched by an inner rule, it is skipped, and then the `"` is found and the
+string ends at the correct place.
+
+You may also explicitly mark skip regexes if you don't want them to be
+highlighted. For example:
+
+```
+- constant.string:
+    start: "\""
+    end: "\""
+    skip: "\\."
+    rules: []
+```
+
+#### Includes
+
+You may also include rules from other syntax files as embedded languages. For
+example, the following is possible for html:
+
+```
+- default:
+    start: "<script.*?>"
+    end: "</script.*?>"
+    rules:
+        - include: "javascript"
+
+- default:
+    start: "<style.*?>"
+    end: "</style.*?>"
+    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).