diff --git a/cmd/micro/actions.go b/cmd/micro/actions.go index 6c4e48ad..5d50055e 100644 --- a/cmd/micro/actions.go +++ b/cmd/micro/actions.go @@ -1087,11 +1087,9 @@ func (v *View) ToggleHelp() bool { return false } - if !CurView().Help { - helpBuffer := NewBuffer([]byte(helpTxt), "help.md") - helpBuffer.Name = "Help" - v.HSplit(helpBuffer) - CurView().Help = true + if !v.Help { + // Open the default help + v.openHelp("help") } else { v.Quit() } diff --git a/cmd/micro/command.go b/cmd/micro/command.go index 88bf391f..0a16815b 100644 --- a/cmd/micro/command.go +++ b/cmd/micro/command.go @@ -24,6 +24,7 @@ var commandActions = map[string]func([]string){ "VSplit": VSplit, "HSplit": HSplit, "Tab": NewTab, + "Help": Help, } // InitCommands initializes the default commands @@ -65,6 +66,22 @@ func DefaultCommands() map[string]string { "vsplit": "VSplit", "hsplit": "HSplit", "tab": "Tab", + "help": "Help", + } +} + +// Help tries to open the given help page in a horizontal split +func Help(args []string) { + if len(args) < 1 { + // Open the default help if the user just typed "> help" + CurView().openHelp("help") + } else { + helpPage := args[0] + if _, ok := helpPages[helpPage]; ok { + CurView().openHelp(helpPage) + } else { + messenger.Error("Sorry, no help for ", helpPage) + } } } diff --git a/cmd/micro/help.go b/cmd/micro/help.go index 3f0ac489..ef0d388b 100644 --- a/cmd/micro/help.go +++ b/cmd/micro/help.go @@ -1,13 +1,24 @@ package main -var helpTxt string +var helpPages map[string]string + +var helpFiles = []string{ + "help", + "keybindings", + "plugins", + "colors", + "options", + "commands", +} // LoadHelp loads the help text from inside the binary func LoadHelp() { - data, err := Asset("runtime/help/help.md") - if err != nil { - TermMessage("Unable to load help text") - return + helpPages = make(map[string]string) + for _, file := range helpFiles { + data, err := Asset("runtime/help/" + file + ".md") + if err != nil { + TermMessage("Unable to load help text", file) + } + helpPages[file] = string(data) } - helpTxt = string(data) } diff --git a/cmd/micro/view.go b/cmd/micro/view.go index 2f34ccf0..91117b90 100644 --- a/cmd/micro/view.go +++ b/cmd/micro/view.go @@ -464,6 +464,14 @@ func (v *View) ClearAllGutterMessages() { } } +// Opens the given help page in a new horizontal split +func (v *View) openHelp(helpPage string) { + helpBuffer := NewBuffer([]byte(helpPages[helpPage]), helpPage+".md") + helpBuffer.Name = "Help" + v.HSplit(helpBuffer) + CurView().Help = true +} + func (v *View) drawCell(x, y int, ch rune, combc []rune, style tcell.Style) { if x >= v.x && x < v.x+v.width && y >= v.y && y < v.y+v.height { screen.SetContent(x, y, ch, combc, style) diff --git a/runtime/help/colors.md b/runtime/help/colors.md new file mode 100644 index 00000000..3e20dc26 --- /dev/null +++ b/runtime/help/colors.md @@ -0,0 +1,94 @@ +# Colors + +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: + +* default: this is the simplest colorscheme. It uses 16 colors which are + set by your terminal + +* 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. + +* monokai: this is the monokai colorscheme and is micro's default colorscheme + (as well as sublime text's). It requires true color to + look perfect, but the 256 color approximation looks very good as well. + +* atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme. + It requires true color to look good. + +To enable one of these colorschemes just run the command `set colorscheme solarized`. +(or whichever one you choose). + +--- + +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 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. + +For example, to highlight all comments in green, you would use the command: + +``` +color-link comment "green" +``` + +Background colors can also be specified with a comma: + +``` +color-link comment "green,blue" +``` + +This will give the comments a blue background. + +If you would like no foreground you can just use a comma with nothing in front: + +``` +color-link comment ",blue" +``` + +You can also put bold, or underline in front of the color: + +``` +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...). + +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. + +Generally colorschemes which require true color terminals to look good are marked with a `-tc` suffix. + +--- + +Colorschemes can be placed in the `~/.config/micro/colorschemes` directory to be used. + +### Syntax files + +The syntax files specify how to highlight certain languages. + +In progress... diff --git a/runtime/help/commands.md b/runtime/help/commands.md new file mode 100644 index 00000000..3a7fddd3 --- /dev/null +++ b/runtime/help/commands.md @@ -0,0 +1,34 @@ +# Possible commands + +You can execute an editor command by pressing `Ctrl-e` followed by the command. +Here are the possible commands that you can use. + +* `quit`: Quits micro. + +* `save`: Saves the current buffer. + +* `replace "search" "value" flags`: This will replace `search` with `value`. + The `flags` are optional. + At this point, there is only one flag: `c`, which enables `check` mode + which asks if you'd like to perform the replacement each time + + 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. + +* `set option value`: sets the option to value. Please see the next section for + a list of options you can set. + +* `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 + 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 + +* `tab filename`: opens the given file in a new tab. + diff --git a/runtime/help/help.md b/runtime/help/help.md index 1d63ae64..c2c48537 100644 --- a/runtime/help/help.md +++ b/runtime/help/help.md @@ -3,6 +3,24 @@ 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. +### 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. + +Here are the possible help topics that you can read: + +* keybindings: Gives a full list of the default keybindings as well as how to rebind them +* 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`. + ### Usage Once you have built the editor, simply start it by running @@ -15,250 +33,3 @@ $ ifconfig | micro ``` You can move the cursor around with the arrow keys and mouse. - -### Keybindings - -Here are the default keybindings in json form which is also how -you can rebind them to your liking. - -```json -{ - "Up": "CursorUp", - "Down": "CursorDown", - "Right": "CursorRight", - "Left": "CursorLeft", - "ShiftUp": "SelectUp", - "ShiftDown": "SelectDown", - "ShiftLeft": "SelectLeft", - "ShiftRight": "SelectRight", - "AltLeft": "WordLeft", - "AltRight": "WordRight", - "AltShiftRight": "SelectWordRight", - "AltShiftLeft": "SelectWordLeft", - "CtrlLeft": "StartOfLine", - "CtrlRight": "EndOfLine", - "CtrlShiftLeft": "SelectToStartOfLine", - "CtrlShiftRight": "SelectToEndOfLine", - "CtrlUp": "CursorStart", - "CtrlDown": "CursorEnd", - "CtrlShiftUp": "SelectToStart", - "CtrlShiftDown": "SelectToEnd", - "Enter": "InsertNewline", - "Space": "InsertSpace", - "Backspace": "Backspace", - "Backspace2": "Backspace", - "Alt-Backspace": "DeleteWordLeft", - "Alt-Backspace2": "DeleteWordLeft", - "Tab": "IndentSelection,InsertTab", - "Backtab": "OutdentSelection", - "CtrlO": "OpenFile", - "CtrlS": "Save", - "CtrlF": "Find", - "CtrlN": "FindNext", - "CtrlP": "FindPrevious", - "CtrlZ": "Undo", - "CtrlY": "Redo", - "CtrlC": "Copy", - "CtrlX": "Cut", - "CtrlK": "CutLine", - "CtrlD": "DuplicateLine", - "CtrlV": "Paste", - "CtrlA": "SelectAll", - "CtrlT": "AddTab", - "CtrlRightSq": "PreviousTab", - "CtrlBackslash": "NextTab", - "Home": "StartOfLine", - "End": "EndOfLine", - "PageUp": "CursorPageUp", - "PageDown": "CursorPageDown", - "CtrlG": "ToggleHelp", - "CtrlR": "ToggleRuler", - "CtrlL": "JumpLine", - "Delete": "Delete", - "Esc": "ClearStatus", - "CtrlB": "ShellMode", - "CtrlQ": "Quit", - "CtrlE": "CommandMode", - "CtrlW": "NextSplit", - - // Emacs-style keybindings - "Alt-f": "WordRight", - "Alt-b": "WordLeft", - "Alt-a": "StartOfLine", - "Alt-e": "EndOfLine", - "Alt-p": "CursorUp", - "Alt-n": "CursorDown", -} -``` - -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. - -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. - -```json -{ - "CtrlY": "Undo", - "CtrlZ": "Redo" -} -``` - -### Possible commands - -You can execute an editor command by pressing `Ctrl-e` followed by the command. -Here are the possible commands that you can use. - -* `quit`: Quits micro. - -* `save`: Saves the current buffer. - -* `replace "search" "value" flags`: This will replace `search` with `value`. - The `flags` are optional. - At this point, there is only one flag: `c`, which enables `check` mode - which asks if you'd like to perform the replacement each time - - 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. - -* `set option value`: sets the option to value. Please see the next section for - a list of options you can set. - -* `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 - 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 - -* `tab filename`: opens the given file in a new tab. - -### Options - -Micro stores all of the user configuration in its configuration directory. - -Micro uses the `$XDG_CONFIG_HOME/micro` as the configuration directory. As per -the XDG spec, if `$XDG_CONFIG_HOME` is not set, `~/.config/micro` is used as -the config directory. - -Here are the options that you can set: - -* `colorscheme`: loads the colorscheme stored in - $(configDir)/colorschemes/`option`.micro - - 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 - - The colorscheme can be selected from all the files in the - ~/.config/micro/colorschemes/ directory. Micro comes by default with three - colorschemes: - - * default: this is the default colorscheme. - - * solarized: this is the solarized colorscheme (used in the screenshot). - 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. - - * monokai-tc: this is the monokai colorscheme. It requires true color to - look perfect, but the 256 color approximation looks good as well. - - * atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme. - It requires true color to look good. - - -* `tabsize`: sets the tab size to `option` - - default value: `4` - -* `indentchar`: sets the indentation character - - default value: ` ` - -* `ignorecase`: perform case-insensitive searches - - default value: `off` - -* `syntax`: turns syntax on or off - - default value: `on` - -* `tabstospaces`: use spaces instead of tabs - - default value: `off` - -* `autoindent`: when creating a new line use the same indentation as the - previous line - - default value: `on` - -* `cursorline`: highlight the line that the cursor is on in a different color - (the color is defined by the colorscheme you are using) - - default value: `off` - -* `ruler`: display line numbers - - default value: `on` - -* `statusline`: display the status line at the bottom of the screen - - 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 - - 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 - - default value: `off` - -* `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 - - default value: `2` - ---- - -Default plugin options: - -* `linter`: lint languages on save (supported languages are C, D, Go, Java, - Javascript, Lua). Provided by the `linter` plugin. - - default value: `on` - -* `autoclose`: Automatically close `{}` `()` `[]` `""` `''`. Provided by the autoclose plugin - - default value: `on` - -* `goimports`: Run goimports on save. Provided by the `go` plugin. - - default value: `off` - -* `gofmt`: Run gofmt on save. Provided by the `go` plugin. - - default value: `on` - -Any option you set in the editor will be saved to the file -~/.config/micro/settings.json so, in effect, your configuration file will be -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. diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md new file mode 100644 index 00000000..4eadd508 --- /dev/null +++ b/runtime/help/keybindings.md @@ -0,0 +1,92 @@ +### Keybindings + +Here are the default keybindings in json form which is also how +you can rebind them to your liking. + +```json +{ + "Up": "CursorUp", + "Down": "CursorDown", + "Right": "CursorRight", + "Left": "CursorLeft", + "ShiftUp": "SelectUp", + "ShiftDown": "SelectDown", + "ShiftLeft": "SelectLeft", + "ShiftRight": "SelectRight", + "AltLeft": "WordLeft", + "AltRight": "WordRight", + "AltShiftRight": "SelectWordRight", + "AltShiftLeft": "SelectWordLeft", + "CtrlLeft": "StartOfLine", + "CtrlRight": "EndOfLine", + "CtrlShiftLeft": "SelectToStartOfLine", + "CtrlShiftRight": "SelectToEndOfLine", + "CtrlUp": "CursorStart", + "CtrlDown": "CursorEnd", + "CtrlShiftUp": "SelectToStart", + "CtrlShiftDown": "SelectToEnd", + "Enter": "InsertEnter", + "Space": "InsertSpace", + "Backspace": "Backspace", + "Backspace2": "Backspace", + "Alt-Backspace": "DeleteWordLeft", + "Alt-Backspace2": "DeleteWordLeft", + "Tab": "InsertTab", + "CtrlO": "OpenFile", + "CtrlS": "Save", + "CtrlF": "Find", + "CtrlN": "FindNext", + "CtrlP": "FindPrevious", + "CtrlZ": "Undo", + "CtrlY": "Redo", + "CtrlC": "Copy", + "CtrlX": "Cut", + "CtrlK": "CutLine", + "CtrlD": "DuplicateLine", + "CtrlV": "Paste", + "CtrlA": "SelectAll", + "CtrlT": "AddTab" + "CtrlRightSq": "PreviousTab", + "CtrlBackslash": "NextTab", + "Home": "Start", + "End": "End", + "PageUp": "CursorPageUp", + "PageDown": "CursorPageDown", + "CtrlG": "ToggleHelp", + "CtrlR": "ToggleRuler", + "CtrlL": "JumpLine", + "Delete": "Delete", + "Esc": "ClearStatus", + "CtrlB": "ShellMode", + "CtrlQ": "Quit", + "CtrlE": "CommandMode", + "CtrlW": "NextSplit", + + // Emacs-style keybindings + "Alt-f": "WordRight", + "Alt-b": "WordLeft", + "Alt-a": "StartOfLine", + "Alt-e": "EndOfLine", + "Alt-p": "CursorUp", + "Alt-n": "CursorDown" +} +``` + +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. + +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. + +```json +{ + "CtrlY": "Undo", + "CtrlZ": "Redo" +} +``` diff --git a/runtime/help/options.md b/runtime/help/options.md new file mode 100644 index 00000000..4c61bdbf --- /dev/null +++ b/runtime/help/options.md @@ -0,0 +1,118 @@ +### Options + +Micro stores all of the user configuration in its configuration directory. + +Micro uses the `$XDG_CONFIG_HOME/micro` as the configuration directory. As per +the XDG spec, if `$XDG_CONFIG_HOME` is not set, `~/.config/micro` is used as +the config directory. + +Here are the options that you can set: + +* `colorscheme`: loads the colorscheme stored in + $(configDir)/colorschemes/`option`.micro + + 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 + + The colorscheme can be selected from all the files in the + ~/.config/micro/colorschemes/ directory. Micro comes by default with three + colorschemes: + + * default: this is the default colorscheme. + + * solarized: this is the solarized colorscheme (used in the screenshot). + 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. + + * monokai-tc: this is the monokai colorscheme. It requires true color to + look perfect, but the 256 color approximation looks good as well. + + * atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme. + It requires true color to look good. + + +* `tabsize`: sets the tab size to `option` + + default value: `4` + +* `indentchar`: sets the indentation character + + default value: ` ` + +* `ignorecase`: perform case-insensitive searches + + default value: `off` + +* `syntax`: turns syntax on or off + + default value: `on` + +* `tabstospaces`: use spaces instead of tabs + + default value: `off` + +* `autoindent`: when creating a new line use the same indentation as the + previous line + + default value: `on` + +* `cursorline`: highlight the line that the cursor is on in a different color + (the color is defined by the colorscheme you are using) + + default value: `off` + +* `ruler`: display line numbers + + default value: `on` + +* `statusline`: display the status line at the bottom of the screen + + 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 + + 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 + + default value: `off` + +* `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 + + default value: `2` + +--- + +Default plugin options: + +* `linter`: lint languages on save (supported languages are C, D, Go, Java, + Javascript, Lua). Provided by the `linter` plugin. + + default value: `on` + +* `autoclose`: Automatically close `{}` `()` `[]` `""` `''`. Provided by the autoclose plugin + + default value: `on` + +* `goimports`: Run goimports on save. Provided by the `go` plugin. + + default value: `off` + +* `gofmt`: Run gofmt on save. Provided by the `go` plugin. + + default value: `on` + +Any option you set in the editor will be saved to the file +~/.config/micro/settings.json so, in effect, your configuration file will be +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. diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md new file mode 100644 index 00000000..743b3525 --- /dev/null +++ b/runtime/help/plugins.md @@ -0,0 +1,3 @@ +# Plugins + +In progress...