Make debug mode flag, plugins can access logbuf

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

diff --git a/runtime/help/colors.md b/runtime/help/colors.md
index d26d8924e6a157e7240f1d82c8fc59a9e30fba93..81cbc194cca63707d913b13c91854e4f32bf07cc 100644 (file)
--- 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:
 
 
 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:
-
-* 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 Ctrl-e 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.
   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
 
 
 ## 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:
 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)
 * 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`)
 * 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
 
 
 ## 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
 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
 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
 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
 ```
 
 filetype: go
 ```
 

-#### Detect definition
+### Detect definition

 
 Then you must provide information about how to detect the filetype:
 
 
 Then you must provide information about how to detect the filetype:
 


@@ -242,7 +259,7 @@ detect:
     header: "%YAML"
 ```
 
     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
 
 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"
 ```
     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).