// EvalCmd evaluates a lua expression
func (h *BufPane) EvalCmd(args []string) {
+ InfoBar.Error("Eval unsupported")
}
// NewTabCmd opens the given file in a new tab
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.
+ 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:
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:
filetype: go
```
-#### Detect definition
+### Detect definition
Then you must provide information about how to detect the filetype:
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
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).
-# Possible commands
+# Command bar
-You can execute an editor command by pressing `Ctrl-e` followed by the command.
-Here are the possible commands that you can use.
+The command bar is opened by pressing Ctrl-e. It is a single-line buffer,
+meaning that all keybindings from a normal buffer are supported (as well
+as mouse and selection).
-* `quit`: Quits micro.
+When running a command, you can use extra syntax that micro will expand before
+running the command. To use an argument with a space in it, simply put it in
+quotes. You can also use environment variables in the command bar and they
+will be expanded to their value. Finally, you can put an expression in backticks
+and it will be evaluated by the shell beforehand.
+
+# Commands
+
+Micro provides the following commands that can be executed at the command-bar by
+pressing `Ctrl-e` and entering the command. Arguments are placed in single
+quotes here but these are not necessary when entering the command in micro.
+
+* `bind 'key' 'action'`: creates a keybinding from key to action. See the
+ `keybindings` documentation for more information about binding keys.
+ This command will modify `bindings.json` and overwrite any bindings to
+ `key` that already exist.
+
+* `help 'topic'?`: opens the corresponding help topic. If no topic is provided
+ opens the default help screen.
-* `save filename?`: Saves the current buffer. If the filename is provided it
- will 'save as' the filename.
+* `save 'filename'?`: saves the current buffer. If the file is provided it
+ will 'save as' the filename.
-* `replace "search" "value" flags`: This will replace `search` with `value`.
+* `quit`: quits micro.
+
+* `replace 'search' 'value' 'flags'?`: This will replace `search` with `value`.
The `flags` are optional. Possible flags are:
* `-a`: Replace all occurrences at once
* `-l`: Do a literal search instead of a regex search
Note that `search` must be a valid regex (unless `-l` is passed). If one
of the arguments does not have any spaces in it, you may omit the quotes.
-* `replaceall "search" "value"`: This will replace `search` with `value` without
- user confirmation.
+* `replaceall 'search' 'value'`: this will replace all occurrences of `search`
+ with `value` without user confirmation.
See `replace` command for more information.
-* `set option value`: sets the option to value. See the `options` help topic for
- a list of options you can set.
+* `set 'option' 'value'`: sets the option to value. See the `options` help topic for
+ a list of options you can set. This will modify your `settings.json` with the
+ new value.
-* `setlocal option value`: sets the option to value locally (only in the current
- buffer).
+* `setlocal 'option' 'value'`: sets the option to value locally (only in the current
+ buffer). This will *not* modify `settings.json`.
-* `show option`: shows the current value of the given option.
+* `show 'option'`: shows the current value of the given option.
-* `run sh-command`: runs the given shell command in the background. The
+* `run 'sh-command'`: runs the given shell command in the background. The
command's output will be displayed in one line when it finishes running.
-* `bind key action`: creates a keybinding from key to action. See the sections
- on keybindings above for more info about what keys and actions are available.
-
-* `vsplit filename`: opens a vertical split with `filename`. If no filename is
+* `vsplit 'filename'`: opens a vertical split with `filename`. If no filename is
provided, a vertical split is opened with an empty buffer.
-* `hsplit filename`: same as `vsplit` but opens a horizontal split instead of a
+* `hsplit 'filename'`: same as `vsplit` but opens a horizontal split instead of a
vertical split.
-* `tab filename`: opens the given file in a new tab.
+* `tab 'filename'`: opens the given file in a new tab.
-* `tabswitch tab`: This command will switch to the specified tab. The `tab` can
+* `tabswitch 'tab'`: This command will switch to the specified tab. The `tab` can
either be a tab number, or a name of a tab.
-* `textfilter sh-command`: filters the current selection through a shell command
+* `textfilter 'sh-command'`: filters the current selection through a shell command
as standard input and replaces the selection with the stdout of the shell command.
For example, to sort a list of numbers, first select them, and then execute
`> textfilter sort -n`.
* `log`: opens a log of all messages and debug statements.
-* `plugin list`: lists all installed plugins.
+* `plugin 'list'`: lists all installed plugins.
-* `plugin version pl`: shows version for specified plugin.
+* `plugin version 'pl'`: shows version for specified plugin.
-* `plugin info pl`: shows additional info for specified plugin.
+* `plugin info 'pl'`: shows additional info for specified plugin.
* `reload`: reloads all runtime files.
-* `cd path`: Change the working directory to the given `path`.
+* `cd 'path'`: Change the working directory to the given `path`.
* `pwd`: Print the current working directory.
-* `open filename`: Open a file in the current buffer.
+* `open 'filename'`: Open a file in the current buffer.
-* `reset option`: resets the given option to its default value
+* `reset 'option'`: resets the given option to its default value
* `retab`: Replaces all leading tabs with spaces or leading spaces with tabs
depending on the value of `tabstospaces`.
-* `raw`: Micro will open a new tab and show the escape sequence for every event
+* `raw`: micro will open a new tab and show the escape sequence for every event
it receives from the terminal. This shows you what micro actually sees from
the terminal and helps you see which bindings aren't possible and why. This
is most useful for debugging keybindings.
* `showkey`: Show the action(s) bound to a given key. For example
- running `> showkey CtrlC` will display `main.(*View).Copy`. Unfortuately
- showkey does not work well for keys bound to plugin actions. For those
- it just shows "LuaFunctionBinding."
+ running `> showkey CtrlC` will display `Copy`.
---
* `lint`: Lint the current file for errors.
* `comment`: automatically comment or uncomment current selection or line.
-
-# Command Parsing
-
-When running a command, you can use extra syntax that micro will expand before
-running the command. To use an argument with a space in it, simply put it in
-quotes. You can also use environment variables in the command bar and they
-will be expanded to their value. Finally, you can put an expression in backticks
-and it will be evaluated by the shell beforehand.
Micro is a terminal-based text editor that aims to be easy to use and intuitive,
while also taking advantage of the full capabilities of modern terminals.
-To open the command bar, press CtrlE. This enables a `>` prompt for typing
+To open the command bar, press Ctrl-e. This enables a `>` prompt for typing
commands. From now on when the documentation says to run a command such as
-`> help`, this means press CtrlE and type `help` (and press enter to execute
+`> help`, this means press Ctrl-e and type `help` (and press enter to execute
the command).
For a list of the default keybindings run `> help defaultkeys`.
## Quick-start
-Press CtrlQ to quit, and CtrlS to save. Press CtrlE to start typing commands and
+Press Ctrl-q to quit, and Ctrl-s to save. Press Ctrl-e to start typing commands and
you can see which commands are available by pressing tab, or by viewing the help
topic `> help commands`.
If the colorscheme doesn't look good, you can change it with
`> set colorscheme ...`. You can press tab to see the available colorschemes, or
-see more information with `> help colors`.
+see more information about colorschemes and syntax highlighting with `> help colors`.
-Press CtrlW to move between splits, and type `> vsplit filename` or
+Press Ctrl-w to move between splits, and type `> vsplit filename` or
`> hsplit filename` to open a new split.
## Accessing more help
-Micro has a built-in help system much like Vim's (although less extensive).
+Micro has a built-in help system which can be accessed with the `help` command.
-To use it, press CtrlE to access command mode and type in `help` followed by a
+To use it, press Ctrl-e to access command mode and type in `help` followed by a
topic. Typing `help` followed by nothing will open this page.
Here are the possible help topics that you can read:
value in the `settings.json` file, or you can type it in directly while using
micro.
-Simply press CtrlE to go to command mode, and type `set option value` (in the
+Press CtrlE to go to command mode, and type `set option value` (in the
future, I will use `> set option value` to indicate pressing CtrlE). The change
will take effect immediately and will also be saved to the `settings.json` file
so that the setting will stick even after you close micro.
projects / micro.git / commitdiff