From 9daa05d696078e50d3e3b95027ffffa9e3e7d556 Mon Sep 17 00:00:00 2001 From: Camille Scholtz Date: Wed, 11 Oct 2017 15:16:53 +0200 Subject: [PATCH] Use more consisten syntax in md files, format tp 80 collumns, fix some typos --- runtime/help/colors.md | 193 +++++++++++++++++-------------- runtime/help/commands.md | 51 ++++----- runtime/help/defaultkeys.md | 32 +++--- runtime/help/gimmickcolors.md | 6 +- runtime/help/help.md | 65 ++++++----- runtime/help/keybindings.md | 70 ++++++------ runtime/help/options.md | 209 +++++++++++++++++++--------------- runtime/help/plugins.md | 197 ++++++++++++++++++-------------- runtime/help/tutorial.md | 54 ++++----- 9 files changed, 479 insertions(+), 398 deletions(-) diff --git a/runtime/help/colors.md b/runtime/help/colors.md index 9047cc5b..d26d8924 100644 --- a/runtime/help/colors.md +++ b/runtime/help/colors.md @@ -5,79 +5,85 @@ 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 + ## 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 +* 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. +* 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: 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. +* 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. +* 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-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. +* 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: 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. ) +* 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. +* 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. +* 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 +* 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! +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! ) +just for fun than for serious use. (Though feel free if you want!) ---- -### Creating a Colorscheme +## Creating a Colorscheme -Micro's colorschemes are also extremely simple to create. The default ones can be found +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). They are only about 18-30 lines in total. -Basically to create the colorscheme you need to link highlight groups with actual colors. -This is done using the `color-link` command. +Basically 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: @@ -109,20 +115,22 @@ color-link comment "bold red" 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 +148,10 @@ Here is a list of the colorscheme groups that you can use: * 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 @@ -150,29 +159,30 @@ Here is a list of the colorscheme groups that you can use: * 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 -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. -* 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 @@ -180,29 +190,32 @@ Here's a list of subgroups used in micro's built-in syntax files. * constant.specialChar * constant.string * constant.string.url -* identifier.class ( Also used for functions. ) +* identifier.class (Also used for functions) * 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. + ## Syntax files -The syntax files is written in yaml-format and specify how to highlight languages. +The syntax files is 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 +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 -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. +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. -### Filetype defintion +### Filetype definition You must start the syntax file by declaring the filetype: @@ -219,8 +232,9 @@ detect: filename: "\\.go$" ``` -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: +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: ``` detect: @@ -230,9 +244,10 @@ detect: #### 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. +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 are some example patterns in Go: @@ -243,7 +258,8 @@ rules: - preproc: "\\b(package|import|const|var|type|struct|func|go|defer|iota)\\b" ``` -The order of patterns does matter as patterns lower in the file will overwrite the ones defined above them. +The order of patterns does matter as patterns lower in the file will overwrite +the ones defined above them. And here are some example regions for Go: @@ -269,12 +285,15 @@ And here are some example regions for Go: - todo: "(TODO|XXX|FIXME):?" ``` -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. +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: +You may also explicitly mark skip regexes if you don't want them to be +highlighted. For example: ``` - constant.string: @@ -286,8 +305,8 @@ You may also explicitly mark skip regexes if you don't want them to be highlight #### Includes -You may also include rules from other syntax files as embedded languages. For example, the following is possible -for html: +You may also include rules from other syntax files as embedded languages. For +example, the following is possible for html: ``` - default: diff --git a/runtime/help/commands.md b/runtime/help/commands.md index 7323873b..e6577294 100644 --- a/runtime/help/commands.md +++ b/runtime/help/commands.md @@ -5,24 +5,23 @@ Here are the possible commands that you can use. * `quit`: Quits micro. -* `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 filename is provided it + will 'save as' the filename. * `replace "search" "value" flags`: This will replace `search` with `value`. - The `flags` are optional. - At this point, there is only one flag: `-a`, which replaces all occurrences - at once. + The `flags` are optional. At this point, there is only one flag: `-a`, which + replaces all occurrences at once. - Note that `search` must be a valid regex. If one of the arguments - does not have any spaces in it, you may omit the quotes. + Note that `search` must be a valid regex. 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. + user confirmation. - See `replace` command for more information. + 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. * `setlocal option value`: sets the option to value locally (only in the current buffer). @@ -30,27 +29,25 @@ Here are the possible commands that you can use. * `show option`: shows the current value of the given option. * `eval "expression"`: Evaluates a Lua expression. Note that micro will not - print anything so you should use `messenger:Message(...)` to display a - value. + print anything so you should use `messenger:Message(...)` to display a value. * `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. +* `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 provided, a vertical split is opened with an empty buffer. -* `hsplit filename`: same as `vsplit` but opens a horizontal split instead of - a vertical split. +* `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. -* `tabswitch tab`: This command will switch to the specified tab. - The `tab` can either be a tab number, or a name of a tab. - - +* `tabswitch tab`: This command will switch to the specified tab. The `tab` can + either be a tab number, or a name of a tab. + * `log`: opens a log of all messages and debug statements. * `plugin install plugin_name`: installs the given plugin. @@ -61,15 +58,15 @@ Here are the possible commands that you can use. * `plugin update`: updates all installed plugins. -* `plugin search plugin_name`: searches for the given plugin. - Note that you can find a list of all available plugins at +* `plugin search plugin_name`: searches for the given plugin. Note that you can + find a list of all available plugins at github.com/micro-editor/plugin-channel. - You can also see more information about the plugin manager - in the `Plugin Manager` section of the `plugins` help topic. + You can also see more information about the plugin manager in the + `Plugin Manager` section of the `plugins` help topic. -* `plugin available`: list plugins available for download (this includes - any plugins that may be already installed). +* `plugin available`: list plugins available for download (this includes any + plugins that may be already installed). * `reload`: reloads all runtime files. diff --git a/runtime/help/defaultkeys.md b/runtime/help/defaultkeys.md index ffba008a..cdff4ae9 100644 --- a/runtime/help/defaultkeys.md +++ b/runtime/help/defaultkeys.md @@ -1,13 +1,13 @@ # Default Keys -Below are simple charts of the default hotkeys and their functions. -For more information about binding custom hotkeys or changing -default bindings, please run `> help keybindings` +Below are simple charts of the default hotkeys and their functions. For more +information about binding custom hotkeys or changing default bindings, please +run `> help keybindings` -Please remember that *all* keys here are rebindable! -If you don't like it, you can change it! +Please remember that *all* keys here are rebindable! If you don't like it, you +can change it! -# Power user +### Power user | Key | Description of function | |-------- |-------------------------------------------------------------------------------------------------- | @@ -15,7 +15,7 @@ If you don't like it, you can change it! | Tab | In command prompt, it will autocomplete if possible. | | Ctrl+B | Run a shell command (this will close micro while your command executes). | -# Navigation +### Navigation | Key | Description of function | |-------------------------- |------------------------------------------------------------------------------------------ | @@ -34,7 +34,7 @@ If you don't like it, you can change it! | Ctrl+L | Jump to a line in the file (prompts with #) | | Ctrl+W | Cycle between splits in the current tab (use `> vsplit` or `> hsplit` to create a split) | -# Tabs +### Tabs | Key | Description of function | |-------- |------------------------- | @@ -42,7 +42,7 @@ If you don't like it, you can change it! | Alt+, | Previous tab | | Alt+. | Next tab | -# Find Operations +### Find Operations | Key | Description of function | |-------- |------------------------------------------ | @@ -50,7 +50,7 @@ If you don't like it, you can change it! | Ctrl+N | Find next instance of current search | | Ctrl+P | Find previous instance of current search | -# File Operations +### File Operations | Key | Description of function | |-------- |---------------------------------------------------------------- | @@ -58,7 +58,7 @@ If you don't like it, you can change it! | Ctrl+O | Open a file (prompts for filename) | | Ctrl+S | Save current file | -# Text operations +### Text operations | Key | Description of function | |--------------------------------- |------------------------------------------ | @@ -80,14 +80,14 @@ If you don't like it, you can change it! | AltBackspace or AltCtrl+H | Delete word left | | Ctrl+A | Select all | -# Macros +### Macros | Key | Description of function | |-------- |---------------------------------------------------------------------------------- | | Ctrl+U | Toggle macro recording (press Ctrl+U to start recording and press again to stop) | | Ctrl+J | Run latest recorded macro | -# Multiple cursors +### Multiple cursors | Key | Description of function | |---------------- |---------------------------------------------------------------------------------------------- | @@ -97,7 +97,7 @@ If you don't like it, you can change it! | Alt+X | Skip multiple cursor selection | | Ctrl-MouseLeft | Place a multiple cursor at any location | -# Other +### Other | Key | Description of function | |-------- |----------------------------------------------------------------------------------- | @@ -105,7 +105,7 @@ If you don't like it, you can change it! | Ctrl+H | Backspace (old terminals do not support the backspace key and use Ctrl+H instead) | | Ctrl+R | Toggle the line number ruler | -# Emacs style actions +### Emacs style actions | Key | Description of function | |------- |------------------------- | @@ -114,7 +114,7 @@ If you don't like it, you can change it! | Alt+A | Move to start of line | | Alt+E | Move to end of line | -# Function keys. +### Function keys. Warning! The function keys may not work in all terminals! diff --git a/runtime/help/gimmickcolors.md b/runtime/help/gimmickcolors.md index 334a8c09..b13a6456 100644 --- a/runtime/help/gimmickcolors.md +++ b/runtime/help/gimmickcolors.md @@ -8,7 +8,7 @@ We have included a few colorschemes that are for fun: Nintendo Entertainment System color palette. * symbian-tc: Colorscheme based on SymbOS's GUI. * matrix: Pretend it's 1981 with a colorscheme based on a monochrome - IBM 5151. ( Does not include the ghosting and trailing. ) + IBM 5151. (Does not include the ghosting and trailing) -Check the plugin repo periodically for gimmick-color extension packs -and genuine additional themes. \ No newline at end of file +Check the plugin repo periodically for gimmick-color extension packs and genuine +additional themes. \ No newline at end of file diff --git a/runtime/help/help.md b/runtime/help/help.md index 2996f11b..094d588a 100644 --- a/runtime/help/help.md +++ b/runtime/help/help.md @@ -1,6 +1,7 @@ # Micro help text Thank you for downloading and using micro. + 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. @@ -8,44 +9,52 @@ If you want to see all the keybindings press CtrlE and type `help keybindings`. See the next section for more information about documentation and help. -### Quick-start -Press CtrlQ to quit, and CtrlS to save. Press CtrlE to start typing commands -and you can see which commands are available by pressing tab, or by -viewing the help topic `> help commands`. When I write `> ...` I mean press -CtrlE and then type whatever is there. +## Quick-start + +Press CtrlQ to quit, and CtrlS to save. Press CtrlE to start typing commands and +you can see which commands are available by pressing tab, or by viewing the help +topic `> help commands`. When I write `> ...` I mean press Ctrl0E and then type +whatever is there. + +Move the cursor around with the mouse or the arrow keys. Type +`> help defaultkeys` to get a quick, easy overview of the default hotkeys and +what they do. For more info on rebinding keys, see type `> help keybindings`. -Move the cursor around with the mouse or the arrow keys. Type `> help defaultkeys` to -get a quick, easy overview of the default hotkeys and 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`. -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`. +Press CtrlW to move between splits, and type `> vsplit filename` or +`> hsplit filename` to open a new split. -Press CtrlW to move between splits, and type `> vsplit filename` or `> hsplit filename` -to open a new split. -### Accessing more help +## Accessing more help Micro has a built-in help system much like Vim's (although less extensive). -To use it, press CtrlE to access command mode and type in `help` followed by a topic. -Typing `help` followed by nothing will open this page. +To use it, press CtrlE 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: -* tutorial: A brief tutorial which gives an overview of all the other help topics -* keybindings: Gives a full list of the default keybindings as well as how to rebind them -* defaultkeys: Gives a more straight-forward list of the hotkey commands and what they do. +* tutorial: A brief tutorial which gives an overview of all the other help + topics +* keybindings: Gives a full list of the default keybindings as well as how to + rebind them +* defaultkeys: Gives a more straight-forward list of the hotkey commands and what + they do. * commands: Gives a list of all the commands and what they do * options: Gives a list of all the options you can customize -* plugins: Explains how micro's plugin system works and how to create your own plugins -* colors: Explains micro's colorscheme and syntax highlighting engine and how to create your - own colorschemes or add new languages to the engine - -For example, to open the help page on plugins you would press CtrlE and type `help plugins`. - -I recommend looking at the `tutorial` help file because it is short for each section and -gives concrete examples of how to use the various configuration options in micro. However, -it does not give the in-depth documentation that the other topics provide. +* plugins: Explains how micro's plugin system works and how to create your own + plugins +* colors: Explains micro's colorscheme and syntax highlighting engine and how to + create your own colorschemes or add new languages to the engine + +For example, to open the help page on plugins you would press CtrlE and type +`help plugins`. + +I recommend looking at the `tutorial` help file because it is short for each +section and gives concrete examples of how to use the various configuration +options in micro. However, it does not give the in-depth documentation that the +other topics provide. diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index 128a77d9..463632ab 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -2,26 +2,28 @@ Micro has a plethora of hotkeys that make it easy and powerful to use and all hotkeys are fully customizable to your liking. + Custom keybindings are stored internally in micro if changed with the `> bind` -command or you can also be added in the file `~/.config/micro/bindings.json` -as discussed below. For a list of the default keybindings in the json format -used by micro, please see the end of this file. For a more user-friendly list -with explanations of what the default hotkeys are and what they do, please -see `>help defaultkeys` +command or you can also be added in the file `~/.config/micro/bindings.json` as +discussed below. For a list of the default keybindings in the json format used +by micro, please see the end of this file. For a more user-friendly list with +explanations of what the default hotkeys are and what they do, please see +`>help defaultkeys` If `~/.config/micro/bindings.json` does not exist, you can simply create it. Micro will know what to do with it. -You can use the alt keys + arrows to move word by word. -Ctrl left and right move the cursor to the start and end of the line, and -ctrl up and down move the cursor the start and end of the buffer. +You can use the alt keys + arrows to move word by word. Ctrl left and right move +the cursor to the start and end of the line, and ctrl up and down move the +cursor the start and end of the buffer. You can hold shift with all of these movement actions to select while moving. -# Rebinding keys -The bindings may be rebound using the `~/.config/micro/bindings.json` -file. Each key is bound to an action. +## Rebinding keys + +The bindings may be rebound using the `~/.config/micro/bindings.json` file. Each +key is bound to an action. For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the following in the `bindings.json` file. @@ -45,7 +47,8 @@ save and quit you can bind it like so: } ``` -# Binding raw escape sequences + +## Binding raw escape sequences Only read this section if you are interested in binding keys that aren't on the list of supported keys for binding. @@ -55,18 +58,18 @@ get all of its information about key events through the terminal. The terminal sends these events in the form of escape sequences often (but not always) starting with `0x1b`. -For example, if micro reads `\x1b[1;5D`, on most terminals this will mean -the user pressed CtrlLeft. +For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the +user pressed CtrlLeft. -For many key chords though, the terminal won't send any escape code or will -send an escape code already in use. For example for `CtrlBackspace`, my -terminal sends `\u007f` (note this doesn't start with `0x1b`), which it also -sends for `Backspace` meaning micro can't bind `CtrlBackspace`. +For many key chords though, the terminal won't send any escape code or will send +an escape code already in use. For example for `CtrlBackspace`, my terminal +sends `\u007f` (note this doesn't start with `0x1b`), which it also sends for +`Backspace` meaning micro can't bind `CtrlBackspace`. However, some terminals do allow you to bind keys to send specific escape sequences you define. Then from micro you can directly bind those escape -sequences to actions. For example, to bind `CtrlBackspace` you can instruct -your terminal to send `\x1bctrlback` and then bind it in `bindings.json`: +sequences to actions. For example, to bind `CtrlBackspace` you can instruct your +terminal to send `\x1bctrlback` and then bind it in `bindings.json`: ```json { @@ -78,11 +81,10 @@ Here are some instructions for sending raw escapes in different terminals ### iTerm2 -In iTerm2, you can do this in -`Preferences->Profiles->Keys` then click the `+`, input your keybinding, -and for the `Action` select `Send Escape Sequence`. For the above example -your would type `ctrlback` into the box (the `\x1b`) is automatically sent -by iTerm2. +In iTerm2, you can do this in `Preferences->Profiles->Keys` then click the `+`, +input your keybinding, and for the `Action` select `Send Escape Sequence`. For +the above example your would type `ctrlback` into the box (the `\x1b`) is +automatically sent by iTerm2. ### Linux using loadkeys @@ -90,12 +92,14 @@ You can do this in linux using the loadkeys program. Coming soon! -# Unbinding keys + +## Unbinding keys It is also possible to disable any of the default key bindings by use of the `UnbindKey` action in the user's `bindings.json` file. -# Bindable actions and bindable keys + +## Bindable actions and bindable keys The list of default keybindings contains most of the possible actions and keys which you can use, but not all of them. Here is a full list of both. @@ -190,6 +194,7 @@ UnbindKey ``` You can also bind some mouse actions (these must be bound to mouse buttons) + ``` MousePress MouseMultiCursor @@ -436,12 +441,13 @@ MouseWheelRight } ``` -# Final notes -Note: On some old terminal emulators and on Windows machines, `CtrlH` should -be used for backspace. +## Final notes + +Note: On some old terminal emulators and on Windows machines, `CtrlH` should be +used for backspace. -Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` -or `Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and +Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or +`Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and `Ctrl` so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings). This is why in the default keybindings you can see `AltShiftLeft` instead of `Alt-ShiftLeft` (they are equivalent). diff --git a/runtime/help/options.md b/runtime/help/options.md index 0cbceaab..bd7c909e 100644 --- a/runtime/help/options.md +++ b/runtime/help/options.md @@ -1,4 +1,4 @@ -### Options +# Options Micro stores all of the user configuration in its configuration directory. @@ -9,27 +9,28 @@ the config directory. Here are the options that you can set: * `autoindent`: when creating a new line use the same indentation as the - previous line + previous line. default value: `on` -* `autosave`: micro will save the buffer every 8 seconds automatically. - Micro also will automatically save and quit when you exit without asking. - Be careful when using this feature, because you might accidentally save a file, +* `autosave`: micro will save the buffer every 8 seconds automatically. Micro + also will automatically save and quit when you exit without asking. Be + careful when using this feature, because you might accidentally save a file, overwriting what was there before. default value: `off` -* `colorcolumn`: if this is not set to 0, it will display a column at the specified - column. This is useful if you want column 80 to be highlighted special for example. +* `colorcolumn`: if this is not set to 0, it will display a column at the + specified column. This is useful if you want column 80 to be highlighted + special for example. default value: `0` * `colorscheme`: loads the colorscheme stored in - $(configDir)/colorschemes/`option`.micro - This setting is `global only`. + $(configDir)/colorschemes/`option`.micro, This setting is `global only`. default value: `default` + Note that the default colorschemes (default, solarized, and solarized-tc) are not located in configDir, because they are embedded in the micro binary. @@ -37,78 +38,88 @@ Here are the options that you can set: ~/.config/micro/colorschemes/ directory. Micro comes by default with three colorschemes: - You can read more about micro's colorschemes in the `colors` help topic - (`help colors`). + You can read more about micro's colorschemes in the `colors` help topic + (`help colors`). * `cursorline`: highlight the line that the cursor is on in a different color - (the color is defined by the colorscheme you are using) + (the color is defined by the colorscheme you are using). - default value: `on` + default value: `on` * `eofnewline`: micro will automatically add a newline to the file. default value: `false` -* `fastdirty`: this determines what kind of algorithm micro uses to determine if a buffer is modified or - not. When `fastdirty` is on, micro just uses a boolean `modified` that is set to `true` as soon as the user - makes an edit. This is fast, but can be inaccurate. If `fastdirty` is off, then micro will hash the current - buffer against a hash of the original file (created when the buffer was loaded). This is more accurate but - obviously more resource intensive. This option is only for people who really care about having accurate - modified status. +* `fastdirty`: this determines what kind of algorithm micro uses to determine if + a buffer is modified or not. When `fastdirty` is on, micro just uses a + boolean `modified` that is set to `true` as soon as the user makes an edit. + This is fast, but can be inaccurate. If `fastdirty` is off, then micro will + hash the current buffer against a hash of the original file (created when the + buffer was loaded). This is more accurate but obviously more resource + intensive. This option is only for people who really care about having + accurate modified status. - default value: `on` + default value: `on` -* `fileformat`: this determines what kind of line endings micro will use for the file. Unix line endings - are just `\n` (lf) whereas dos line endings are `\r\n` (crlf). The two possible values for this option - are `unix` and `dos`. The fileformat will be automatically detected and displayed on the statusline but - this option is useful if you would like to change the line endings or if you are starting a new file. +* `fileformat`: this determines what kind of line endings micro will use for the + file. UNIX line endings are just `\n` (lf) whereas dos line endings are + `\r\n` (crlf). The two possible values for this option are `unix` and `dos`. + The fileformat will be automatically detected and displayed on the statusline + but this option is useful if you would like to change the line endings or if + you are starting a new file. - default value: `unix` + default value: `unix` -* `filetype`: sets the filetype for the current buffer. This setting is `local only` +* `filetype`: sets the filetype for the current buffer. This setting is + `local only`. - default value: this will be automatically set depending on the file you have open + default value: this will be automatically set depending on the file you have + open -* `ignorecase`: perform case-insensitive searches +* `ignorecase`: perform case-insensitive searches. default value: `off` -* `indentchar`: sets the indentation character +* `indentchar`: sets the indentation character. default value: ` ` -* `infobar`: enables the line at the bottom of the editor where messages are printed. - This option is `global only`. +* `infobar`: enables the line at the bottom of the editor where messages are + printed. This option is `global only`. default value: `on` -* `keepautoindent`: when using autoindent, whitespace is added for you. This option determines if - when you move to the next line without any insertions the whitespace that was added should be deleted. - By default the autoindent whitespace is deleted if the line was left empty. +* `keepautoindent`: when using autoindent, whitespace is added for you. This + option determines if when you move to the next line without any insertions + the whitespace that was added should be deleted. By default the autoindent + whitespace is deleted if the line was left empty. - default value: `off` + default value: `off` -* `keymenu`: display the nano-style key menu at the bottom of the screen. Note that ToggleKeyMenu is bound to - `Alt-g` by default and this is displayed in the statusline. To disable this, simply by `Alt-g` to `UnbindKey`. +* `keymenu`: display the nano-style key menu at the bottom of the screen. Note + that ToggleKeyMenu is bound to `Alt-g` by default and this is displayed in + the statusline. To disable this, simply by `Alt-g` to `UnbindKey`. - default value: `off` + default value: `off` -* `mouse`: whether to enable mouse support. When mouse support is disabled, usually the terminal will be able - to access mouse events which can be useful if you want to copy from the terminal instead of from micro (if - over ssh for example, because the terminal has access to the local clipboard and micro does not). +* `mouse`: whether to enable mouse support. When mouse support is disabled, + usually the terminal will be able to access mouse events which can be useful + if you want to copy from the terminal instead of from micro (if over ssh for + example, because the terminal has access to the local clipboard and micro + does not). - default value: `on` + default value: `on` * `pluginchannels`: contains all the channels micro's plugin manager will search - for plugins in. A channel is simply a list of 'repository' json files which contain - metadata about the given plugin. See the `Plugin Manager` section of the `plugins` help topic - for more information. + for plugins in. A channel is simply a list of 'repository' json files which + contain metadata about the given plugin. See the `Plugin Manager` section of + the `plugins` help topic for more information. default value: `https://github.com/micro-editor/plugin-channel` -* `pluginrepos`: contains all the 'repositories' micro's plugin manager will search for - plugins in. A repository consists of a `repo.json` file which contains metadata for a - single plugin. +* `pluginrepos`: contains all the 'repositories' micro's plugin manager will + search for plugins in. A repository consists of a `repo.json` file which + contains metadata for a single plugin. default value: ` ` @@ -116,59 +127,62 @@ Here are the options that you can set: default value: `false` -* `ruler`: display line numbers +* `ruler`: display line numbers. default value: `on` * `savecursor`: remember where the cursor was last time the file was opened and - put it there when you open the file again + put it there when you open the file again. default value: `off` * `saveundo`: when this option is on, undo is saved even after you close a file - so if you close and reopen a file, you can keep undoing + so if you close and reopen a file, you can keep undoing. default value: `off` -* `scrollmargin`: amount of lines you would like to see above and below the cursor +* `scrollmargin`: amount of lines you would like to see above and below the + cursor. default value: `3` -* `scrollspeed`: amount of lines to scroll for one scroll event +* `scrollspeed`: amount of lines to scroll for one scroll event. default value: `2` -* `softwrap`: should micro wrap lines that are too long to fit on the screen +* `softwrap`: should micro wrap lines that are too long to fit on the screen. default value: `off` -* `splitbottom`: when a horizontal split is created, should it be created below the - current split? +* `splitbottom`: when a horizontal split is created, should it be created below + the current split? default value: `on` -* `splitright`: when a vertical split is created, should it be created to the right of - the current split? +* `splitright`: when a vertical split is created, should it be created to the + right of the current split? default value: `on` -* `statusline`: display the status line at the bottom of the screen +* `statusline`: display the status line at the bottom of the screen. default value: `on` -* `syntax`: turns syntax on or off +* `syntax`: turns syntax on or off. default value: `on` -* `sucmd`: specifies the super user command. On most systems this is "sudo" but on BSD it can be "doas." This - option can be customized and is only used when saving with su. +* `sucmd`: specifies the super user command. On most systems this is "sudo" but + on BSD it can be "doas." This option can be customized and is only used when + saving with su. - default value: `sudo` + default value: `sudo` -* `tabmovement`: navigate spaces at the beginning of lines as if they are tabs (e.g. move over 4 spaces at once). - This option only does anything if `tabstospaces` is on. +* `tabmovement`: navigate spaces at the beginning of lines as if they are tabs + (e.g. move over 4 spaces at once). This option only does anything if + `tabstospaces` is on. - default value: `off` + default value: `off` * `tabsize`: sets the tab size to `option` @@ -178,12 +192,14 @@ Here are the options that you can set: default value: `off` -* `termtitle`: defines whether or not your terminal's title will be set by micro when opened. +* `termtitle`: defines whether or not your terminal's title will be set by micro + when opened. - default value: `off` + default value: `off` -* `useprimary` (only useful on Linux): defines whether or not micro will use the primary clipboard to copy selections - in the background. This does not affect the normal clipboard using Ctrl-C and Ctrl-V. +* `useprimary` (only useful on *nix): defines whether or not micro will use the + primary clipboard to copy selections in the background. This does not affect + the normal clipboard using Ctrl-C and Ctrl-V. default value: `on` @@ -191,17 +207,20 @@ Here are the options that you can set: Default plugin options: -* `autoclose`: Automatically close `{}` `()` `[]` `""` `''`. Provided by the `autoclose` plugin +* `autoclose`: automatically close `{}` `()` `[]` `""` `''`. Provided by the + `autoclose` plugin default value: `on` -* `ftoptions`: by default, micro will set some options based on the filetype. At the moment, micro will - use tabs for makefiles and spaces for python and yaml files regardless of your settings. If you would like to - disable this behavior turn this option off. +* `ftoptions`: by default, micro will set some options based on the filetype. At + the moment, micro will use tabs for makefiles and spaces for python and yaml + files regardless of your settings. If you would like to disable this behavior + turn this option off. default value: `on` -* `linter`: Automatically lint when the file is saved. Provided by the `linter` plugin +* `linter`: Automatically lint when the file is saved. Provided by the `linter` + plugin. default value: `on` @@ -210,31 +229,33 @@ Any option you set in the editor will be saved to the file created for you. If you'd like to take your configuration with you to another machine, simply copy the settings.json to the other machine. -# Global and local settings -You can set these settings either globally or locally. Locally means that the setting -won't be saved to `~/.config/micro/settings.json` and that it will only be set in -the current buffer. Setting an option globally is the default, and will set the option -in all buffers. +## Global and local settings + +You can set these settings either globally or locally. Locally means that the +setting won't be saved to `~/.config/micro/settings.json` and that it will only +be set in the current buffer. Setting an option globally is the default, and +will set the option in all buffers. -The `colorscheme` option is global only, and the `filetype` option is local only. To -set an option locally, use `setlocal` instead of `set`. +The `colorscheme` option is global only, and the `filetype` option is local +only. To set an option locally, use `setlocal` instead of `set`. -In the `settings.json` file you can also put set options locally by specifying a glob. -Here is an example which has `tabstospaces` on for all files except Go files, and -`tabsize` 4 for all files except Ruby files: +In the `settings.json` file you can also put set options locally by specifying a +glob. Here is an example which has `tabstospaces` on for all files except Go +files, and `tabsize` 4 for all files except Ruby files: ```json { - "*.go": { - "tabstospaces": false - }, - "*.rb": { - "tabsize": 2 - }, - "tabstospaces": true, - "tabsize": 4 + "*.go": { + "tabstospaces": false + }, + "*.rb": { + "tabsize": 2 + }, + "tabstospaces": true, + "tabsize": 4 } ``` -As you can see it is quite easy to set options locally using the `settings.json` file. +As you can see it is quite easy to set options locally using the `settings.json` +file. diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index c5caee54..763f015c 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -4,10 +4,9 @@ Micro supports creating plugins with a simple Lua system. Every plugin has a main script which is run at startup which should be placed in `~/.config/micro/plugins/pluginName/pluginName.lua`. -There are a number of callback functions which you can create in your -plugin to run code at times other than startup. The naming scheme is -`onAction(view)`. For example a function which is run every time the user saves -the buffer would be: +There are a number of callback functions which you can create in your plugin to +run code at times other than startup. The naming scheme is `onAction(view)`. For +example a function which is run every time the user saves the buffer would be: ```lua function onSave(view) @@ -17,7 +16,8 @@ end ``` The `view` variable is a reference to the view the action is being executed on. -This is almost always the current view, which you can get with `CurView()` as well. +This is almost always the current view, which you can get with `CurView()` as +well. All available actions are listed in the keybindings section of the help. @@ -31,27 +31,28 @@ function onMousePress(view, event) end ``` -These functions should also return a boolean specifying whether the view -should be relocated to the cursor or not after the action is complete. +These functions should also return a boolean specifying whether the view should +be relocated to the cursor or not after the action is complete. -Note that these callbacks occur after the action has been completed. If you -want a callback before the action is executed, use `preAction()`. In this case -the boolean returned specifies whether or not the action should be executed -after the lua code completes. +Note that these callbacks occur after the action has been completed. If you want +a callback before the action is executed, use `preAction()`. In this case the +boolean returned specifies whether or not the action should be executed after +the lua code completes. Another useful callback to know about which is not an action is `onViewOpen(view)` which is called whenever a new view is opened and the new -view is passed in. This is useful for setting local options based on the filetype, -for example turning off `tabstospaces` only for Go files when they are opened. +view is passed in. This is useful for setting local options based on the +filetype, for example turning off `tabstospaces` only for Go files when they are +opened. --- -There are a number of functions and variables that are available to you in -order to access the inner workings of micro. Here is a list (the type signatures -for functions are given using Go's type system): +There are a number of functions and variables that are available to you in order +to access the inner workings of micro. Here is a list (the type signatures for +functions are given using Go's type system): -* `OS`: variable which gives the OS micro is currently running on (this is the same -as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...) +* `OS`: variable which gives the OS micro is currently running on (this is the + same as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...) * `configDir`: contains the path to the micro configuration files @@ -61,29 +62,35 @@ as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...) * `messenger`: lets you send messages to the user or create prompts -* `NewBuffer(text, path string) *Buffer`: creates a new buffer from a given reader with a given path +* `NewBuffer(text, path string) *Buffer`: creates a new buffer from a given + reader with a given path -* `GetLeadingWhitespace() bool`: returns the leading whitespace of the given string +* `GetLeadingWhitespace() bool`: returns the leading whitespace of the given + string -* `IsWordChar(str string) bool`: returns whether or not the string is a 'word character' +* `IsWordChar(str string) bool`: returns whether or not the string is a 'word + character' * `RuneStr(r rune) string`: returns a string containing the given rune * `Loc(x, y int) Loc`: returns a new `Loc` struct -* `WorkingDirectory() string`: returns a rooted path name to the current working directory +* `WorkingDirectory() string`: returns a rooted path name to the current working + directory -* `JoinPaths(dir... string) string`: combines multiple directories to a full path +* `JoinPaths(dir... string) string`: combines multiple directories to a full + path -* `DirectoryName(path string)`: returns all but the last element of path ,typically the path's directory +* `DirectoryName(path string)`: returns all but the last element of path, + typically the path's directory * `GetOption(name string)`: returns the value of the requested option -* `AddOption(name string, value interface{})`: sets the given option with the given - value (`interface{}` means any type in Go) +* `AddOption(name string, value interface{})`: sets the given option with the + given value (`interface{}` means any type in Go) -* `SetOption(option, value string)`: sets the given option to the value. This will - set the option globally, unless it is a local only option. +* `SetOption(option, value string)`: sets the given option to the value. This + will set the option globally, unless it is a local only option. * `SetLocalOption(option, value string, view *View)`: sets the given option to the value locally in the given buffer @@ -91,8 +98,8 @@ as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...) * `BindKey(key, action string)`: binds `key` to `action` * `MakeCommand(name, function string, completions ...Completion)`: - creates a command with `name` which will call `function` when executed. - Use 0 for completions to get NoCompletion. + creates a command with `name` which will call `function` when executed. Use 0 + for completions to get NoCompletion. * `MakeCompletion(function string)`: creates a `Completion` to use with `MakeCommand` @@ -101,42 +108,49 @@ as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...) * `HandleCommand(cmd string)`: runs the given command -* `HandleShellCommand(shellCmd string, interactive bool, waitToClose bool)`: runs the given shell - command. The `interactive` bool specifies whether the command should run in the background. The - `waitToClose` bool only applies if `interactive` is true and means that it should wait before - returning to the editor. +* `HandleShellCommand(shellCmd string, interactive bool, waitToClose bool)`: + runs the given shell command. The `interactive` bool specifies whether the + command should run in the background. The `waitToClose` bool only applies if + `interactive` is true and means that it should wait before returning to the + editor. -* `ToCharPos(loc Loc, buf *Buffer) int`: returns the character position of a given x, y location +* `ToCharPos(loc Loc, buf *Buffer) int`: returns the character position of a + given x, y location * `Reload`: (Re)load everything -* `ByteOffset(loc Loc, buf *Buffer) int`: exactly like `ToCharPos` except it it counts bytes instead of runes +* `ByteOffset(loc Loc, buf *Buffer) int`: exactly like `ToCharPos` except it it + counts bytes instead of runes * `JobSpawn(cmdName string, cmdArgs []string, onStdout, onStderr, onExit string, userargs ...string)`: - Starts running the given process in the background. `onStdout` `onStderr` and `onExit` - are callbacks to lua functions which will be called when the given actions happen - to the background process. - `userargs` are the arguments which will get passed to the callback functions + Starts running the given process in the background. `onStdout` `onStderr` and + `onExit` are callbacks to lua functions which will be called when the given + actions happen to the background process. `userargs` are the arguments which + will get passed to the callback functions * `JobStart(cmd string, onStdout, onStderr, onExit string, userargs ...string)`: - Starts running the given shell command in the background. Note that the command execute - is first parsed by a shell when using this command. It is executed with `sh -c`. + Starts running the given shell command in the background. Note that the + command execute is first parsed by a shell when using this command. It is + executed with `sh -c`. -* `JobSend(cmd *exec.Cmd, data string)`: send a string into the stdin of the job process +* `JobSend(cmd *exec.Cmd, data string)`: send a string into the stdin of the job + process * `JobStop(cmd *exec.Cmd)`: kill a job This may seem like a small list of available functions but some of the objects returned by the functions have many methods. `CurView()` returns a view object -which has all the actions which you can call. For example `CurView():Save(false)`. -You can see the full list of possible actions in the keybindings help topic. -The boolean on all the actions indicates whether or not the lua callbacks should -be run. I would recommend generally sticking to false when making a plugin to -avoid recursive problems, for example if you call `CurView():Save(true)` in `onSave()`. -Just use `CurView():Save(false)` so that it won't call `onSave()` again. +which has all the actions which you can call. For example +`CurView():Save(false)`. You can see the full list of possible actions in the +keybindings help topic. The boolean on all the actions indicates whether or not +the lua callbacks should be run. I would recommend generally sticking to false +when making a plugin to avoid recursive problems, for example if you call +`CurView():Save(true)` in `onSave()`. Just use `CurView():Save(false)` so that +it won't call `onSave()` again. Using the view object, you can also access the buffer associated with that view -by using `CurView().Buf`, which lets you access the `FileType`, `Path`, `Name`... +by using `CurView().Buf`, which lets you access the `FileType`, `Path`, +`Name`... The possible methods which you can call using the `messenger` variable are: @@ -146,7 +160,8 @@ The possible methods which you can call using the `messenger` variable are: * `messenger.Prompt(prompt, historyType string, completionType Completion) (string, bool)` * `messenger.AddLog(msg ...interface{})` -## Note +#### Note + Go function signatures use `.` and lua uses `:` so ```go @@ -160,21 +175,26 @@ messenger:Message() ``` If you want a standard prompt, just use + ```lua messenger:Prompt(prompt, "", 0) ``` Debug or logging your plugin can be done with below lua example code. + ```lua messenger:AddLog("Message goes here ",pluginVariableToPrintHere) ``` -In Micro to see your plugin logging output press `CtrlE` then type `log` -A logging window will open and any logging sent from your plugin will be displayed here. +In Micro to see your plugin logging output press `CtrlE` then type `log`, a +logging window will open and any logging sent from your plugin will be displayed +here. + -# Accessing the Go standard library +## Accessing the Go standard library -It is possible for your lua code to access many of the functions in the Go standard library. +It is possible for your lua code to access many of the functions in the Go +standard library. Simply import the package you'd like and then you can use it. For example: @@ -196,26 +216,29 @@ else end ``` -For a full list of which packages and functions from the standard library -you can access, look at `lua.go` in the source code (it shouldn't be -too hard to look through). +For a full list of which packages and functions from the standard library you +can access, look at `lua.go` in the source code (it shouldn't be too hard to +look through). -# Adding help files, syntax files, or colorschemes in your plugin -You can use the `AddRuntimeFile(name, type, path string)` function to add various kinds of -files to your plugin. For example, if you'd like to add a help topic to your plugin -called `test`, you would create a `test.md` file, and call the function: +## Adding help files, syntax files, or colorschemes in your plugin + +You can use the `AddRuntimeFile(name, type, path string)` function to add +various kinds of files to your plugin. For example, if you'd like to add a help +topic to your plugin called `test`, you would create a `test.md` file, and call +the function: ```lua AddRuntimeFile("test", "help", "test.md") ``` -Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of files -to the runtime. -To read the content of a runtime file use `ReadRuntimeFile(fileType, name string)` -or `ListRuntimeFiles(fileType string)` for all runtime files. +Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of +files to the runtime. To read the content of a runtime file use +`ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)` +for all runtime files. + -# Autocomplete command arguments +## Autocomplete command arguments See this example to learn how to use `MakeCompletion` and `MakeCommand` @@ -245,27 +268,32 @@ end MakeCommand("foo", "example.foo", MakeCompletion("example.complete")) ``` -# Default plugins + +## Default plugins For examples of plugins, see the default `autoclose` and `linter` plugins -(stored in the normal micro core repo under `runtime/plugins`) as well as -any plugins that are stored in the official channel [here](https://github.com/micro-editor/plugin-channel). +(stored in the normal micro core repo under `runtime/plugins`) as well as any +plugins that are stored in the official channel +[here](https://github.com/micro-editor/plugin-channel). + -# Plugin Manager +## Plugin Manager -Micro also has a built in plugin manager which you can invoke with the `> plugin ...` command. +Micro also has a built in plugin manager which you can invoke with the +`> plugin ...` command. For the valid commands you can use, see the `command` help topic. -The manager fetches plugins from the channels (which is simply a list of plugin metadata) -which it knows about. By default, micro only knows about the official channel which is located -at github.com/micro-editor/plugin-channel but you can add your own third-party channels using -the `pluginchannels` option and you can directly link third-party plugins to allow installation -through the plugin manager with the `pluginrepos` option. +The manager fetches plugins from the channels (which is simply a list of plugin +metadata) which it knows about. By default, micro only knows about the official +channel which is located at github.com/micro-editor/plugin-channel but you can +add your own third-party channels using the `pluginchannels` option and you can +directly link third-party plugins to allow installation through the plugin +manager with the `pluginrepos` option. -If you'd like to publish a plugin you've made as an official plugin, you should upload your -plugin online (to Github preferably) and add a `repo.json` file. This file will contain the -metadata for your plugin. Here is an example: +If you'd like to publish a plugin you've made as an official plugin, you should +upload your plugin online (to Github preferably) and add a `repo.json` file. +This file will contain the metadata for your plugin. Here is an example: ```json [{ @@ -284,7 +312,8 @@ metadata for your plugin. Here is an example: }] ``` -Then open a pull request at github.com/micro-editor/plugin-channel adding a link to the -raw `repo.json` that is in your plugin repository. -To make updating the plugin work, the first line of your plugins lua code should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`) -Please make sure to use [semver](http://semver.org/) for versioning. +Then open a pull request at github.com/micro-editor/plugin-channel adding a link +to the raw `repo.json` that is in your plugin repository. To make updating the +plugin work, the first line of your plugins lua code should contain the version +of the plugin. (Like this: `VERSION = "1.0.0"`) Please make sure to use +[semver](http://semver.org/) for versioning. diff --git a/runtime/help/tutorial.md b/runtime/help/tutorial.md index f720a4c9..28032d3c 100644 --- a/runtime/help/tutorial.md +++ b/runtime/help/tutorial.md @@ -1,15 +1,15 @@ # Tutorial -This is a brief intro to micro's configuration system that will give some -simple examples showing how to configure settings, rebind keys, -and use `init.lua` to configure micro to your liking. +This is a brief intro to micro's configuration system that will give some simple +examples showing how to configure settings, rebind keys, and use `init.lua` to +configure micro to your liking. Hopefully you'll find this useful. ### Plugins -Micro has a plugin manager which can automatically download plugins for you. -To see the plugins 'official' plugins, go to github.com/micro-editor/plugin-channel. +Micro has a plugin manager which can automatically download plugins for you. To +see the plugins 'official' plugins, go to github.com/micro-editor/plugin-channel. For example, if you'd like to install the snippets plugin (listed in that repo), just press `CtrlE` to execute a command, and type `plugin install snippets`. @@ -20,23 +20,23 @@ topic. ### Settings In micro, your settings are stored in `~/.config/micro/settings.json`, a file -that is created the first time you run micro. It is a json file which holds -all 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. +that is created the first time you run micro. It is a json file which holds all +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 -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. - -You can also set options locally which means that the setting will only have -the value you give it in the buffer you set it in. For example, if you have -two splits open, and you type `> setlocal tabsize 2`, the tabsize will only -be 2 in the current buffer. Also micro will not save this local change to 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. + +You can also set options locally which means that the setting will only have the +value you give it in the buffer you set it in. For example, if you have two +splits open, and you type `> setlocal tabsize 2`, the tabsize will only be 2 in +the current buffer. Also micro will not save this local change to the `settings.json` file. However, you can still set options locally in the -`settings.json` file. For example, if you want the `tabsize` to be 2 only -in Ruby files, and 4 otherwise, you could put the following in `settings.json`: +`settings.json` file. For example, if you want the `tabsize` to be 2 only in +Ruby files, and 4 otherwise, you could put the following in `settings.json`: ```json { @@ -54,8 +54,8 @@ If you would like to know more about all the available options, see the ### Keybindings -Keybindings work in much the same way as options. You configure them using -the `~/.config/micro/bindings.json` file. +Keybindings work in much the same way as options. You configure them using the +`~/.config/micro/bindings.json` file. For example if you would like to bind `CtrlR` to redo you could put the following in `bindings.json`: @@ -78,8 +78,8 @@ what actions are available, see the `keybindings` help topic (`> help keybinding ### Configuration with Lua If you need more power than the json files provide, you can use the `init.lua` -file. Create it in `~/.config/micro`. This file is a lua file that is run -when micro starts and is essentially a one-file plugin. +file. Create it in `~/.config/micro`. This file is a lua file that is run when +micro starts and is essentially a one-file plugin. I'll show you how to use the `init.lua` file by giving an example of how to create a binding to `CtrlR` which will execute `go run` on the current file, @@ -98,8 +98,8 @@ end BindKey("CtrlR", "init.gorun") ``` -Alternatively, you could get rid of the `BindKey` line, and put this line in -the `bindings.json` file: +Alternatively, you could get rid of the `BindKey` line, and put this line in the +`bindings.json` file: ```json { @@ -107,5 +107,5 @@ the `bindings.json` file: } ``` -For more information about plugins and the lua system that micro uses, see -the `plugins` help topic (`> help plugins`). +For more information about plugins and the lua system that micro uses, see the +`plugins` help topic (`> help plugins`). -- 2.44.0