mirror of
https://github.com/zyedidia/micro.git
synced 2026-03-10 06:40:24 +09:00
Some documentation updates
This commit is contained in:
Zachary Yedidia
@@ -497,6 +497,7 @@ func (h *BufPane) HSplitCmd(args []string) {
|
||||
|
||||
// EvalCmd evaluates a lua expression
|
||||
func (h *BufPane) EvalCmd(args []string) {
|
||||
InfoBar.Error("Eval unsupported")
|
||||
}
|
||||
|
||||
// NewTabCmd opens the given file in a new tab
|
||||
|
||||
@@ -2,37 +2,52 @@
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
* 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:
|
||||
|
||||
@@ -75,9 +90,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.
|
||||
|
||||
Basically to create the colorscheme you need to link highlight groups with
|
||||
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:
|
||||
@@ -218,7 +236,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 +255,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 +334,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).
|
||||
|
||||
@@ -1,14 +1,35 @@
|
||||
# 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.
|
||||
|
||||
* `save filename?`: Saves the current buffer. If the filename is provided it
|
||||
will 'save as' the filename.
|
||||
# Commands
|
||||
|
||||
* `replace "search" "value" flags`: This will replace `search` with `value`.
|
||||
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 file is provided it
|
||||
will 'save as' the filename.
|
||||
|
||||
* `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
|
||||
@@ -16,71 +37,67 @@ Here are the possible commands that you can use.
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
@@ -89,11 +106,3 @@ The following commands are provided by the default plugins:
|
||||
* `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.
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
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`.
|
||||
@@ -13,7 +13,7 @@ For more information on keybindings see `> help keybindings`.
|
||||
|
||||
## 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`.
|
||||
|
||||
@@ -23,16 +23,16 @@ what they do. For more info on rebinding keys, see type `> help keybindings`.
|
||||
|
||||
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:
|
||||
|
||||
@@ -16,7 +16,7 @@ the settings and their values. To change an option, you can either change the
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user