bunmicro 0.8.0

package/runtime/help/copypaste.md

@@ -0,0 +1,149 @@
+Copy and paste are essential features in micro but can be
+confusing to get right especially when running micro over SSH
+because there are multiple methods. This help document will explain
+the various methods for copying and pasting, how they work,
+and the best methods for doing so over SSH.
+
+# OSC 52 (terminal clipboard)
+
+If possible, setting the `clipboard` option to `terminal` will give
+best results because it will work over SSH and locally. However, there
+is limited support among terminal emulators for the terminal clipboard
+(which uses the OSC 52 protocol to communicate clipboard contents).
+Here is a list of terminal emulators and their status:
+
+* `Kitty`: supported, but only writing is enabled by default. To enable
+   reading, add `read-primary` and `read-clipboard` to the
+   `clipboard_control` option.
+
+* `iTerm2`: only copying (writing to clipboard) is supported. Must be enabled in
+   `Preferences->General-> Selection->Applications in terminal may access clipboard`.
+   You can use `Command-v` to paste.
+
+* `st`: supported.
+
+* `rxvt-unicode`: not natively supported, but there is a Perl extension
+   [here](https://anti.teamidiot.de/static/nei/*/Code/urxvt/).
+
+* `xterm`: supported, but disabled by default. It can be enabled by putting
+   the following in `.Xresources` or `.Xdefaults`:
+   `XTerm*disallowedWindowOps: 20,21,SetXprop`.
+
+* `gnome-terminal`: does not support OSC 52.
+
+* `alacritty`: supported. Since 0.13.0, reading has been disabled by default.
+   To reenable it, set the `terminal.osc52` option to `CopyPaste`.
+
+* `foot`: supported.
+
+* `wezterm`: only copying (writing to clipboard) is supported.
+
+
+**Summary:** If you want copy and paste to work over SSH, then you
+should set `clipboard` to `terminal`, and make sure your terminal
+supports OSC 52.
+
+# Pasting
+
+## Recommendations (TL;DR)
+
+The recommended method of pasting is the following:
+
+* If you are not working over SSH, use the micro keybinding (`Ctrl-v`
+  by default) to perform pastes. If on Linux, install `xclip` or
+  `xsel` beforehand.
+
+* If you are working over SSH, use the terminal keybinding
+  (`Ctrl-Shift-v` or `Command-v`) to perform pastes. If your terminal
+  does not support bracketed paste, when performing a paste first
+  enable the `paste` option, and when finished disable the option.
+
+## Micro paste events
+
+Micro is an application that runs within the terminal. This means
+that the terminal sends micro events, such as key events, mouse
+events, resize events, and paste events. Micro's default keybinding
+for paste is `Ctrl-v`. This means that when micro receives the key
+event saying `Ctrl-v` has been pressed from the terminal, it will
+attempt to access the system clipboard and effect a paste. The
+system clipboard will be accessed through `pbpaste` on MacOS
+(installed by default), `xclip` or `xsel` on Linux (these
+applications must be installed by the user) or a system call on
+Windows.
+
+## Terminal paste events
+
+For certain keypresses, the terminal will not send an event to
+micro and will instead do something itself. In this document,
+such keypresses will be called "terminal keybindings." Often
+there will be a terminal keybinding for pasting and copying. On
+MacOS these are Command-v and Command-c and on Linux `Ctrl-Shift-v`
+and `Ctrl-Shift-c`. When the terminal keybinding for paste is
+executed, your terminal will access the system clipboard, and send
+micro either a paste event or a list of key events (one key for each
+character in the paste), depending on whether or not your terminal
+supports sending paste events (called bracketed paste).
+
+If your terminal supports bracketed paste, then it will send a paste
+event and everything will work well. However, if your terminal
+sends a list of key events, this can cause issues because micro
+will think you manually entered each character and may add closing
+brackets or automatic indentation, which will mess up the pasted
+text. To avoid this, you can temporarily enable the `paste` option
+while you perform the paste. When paste option is on, micro will
+aggregate lists of multiple key events into larger paste events.
+It is a good idea to disable the `paste` option during normal use
+as occasionally if you are typing quickly, the terminal will send
+the key events as lists of characters that were in fact manually
+entered.
+
+## Pasting over SSH
+
+When working over SSH, micro is running on the remote machine and
+your terminal is running on your local machine. Therefore if you
+would like to paste, using `Ctrl-v` (micro's keybinding) will not
+work because when micro attempts to access the system clipboard,
+it will access the remote machine's clipboard rather than the local
+machine's clipboard. On the other hand, the terminal keybinding
+for paste will access your local clipboard and send the text over
+the network as a paste event, which is what you want.
+
+# Copying
+
+# Recommendations (TL;DR)
+
+The recommended method of copying is the following:
+
+* If you are not working over SSH, use the micro keybinding (`Ctrl-c` by
+  default) to perform copies. If on Linux, install `xclip` or `xsel`
+  beforehand.
+
+* If you are working over SSH, use the terminal keybinding
+  (`Ctrl-Shift-c` or `Command-c`) to perform copies. You must first disable
+  the `mouse` option to perform a terminal selection, and you may wish
+  to disable line numbers and diff indicators (`ruler` and `diffgutter`
+  options) and close other splits. This method will only be able to copy
+  characters that are displayed on the screen (you will not be able to
+  copy more than one page's worth of characters).
+
+Copying follows a similar discussion to the one above about pasting.
+The primary difference is before performing a copy, the application
+doing the copy must be told what text needs to be copied.
+
+Micro has a keybinding (`Ctrl-c`) for copying and will access the system
+clipboard to perform the copy. The text that micro will copy into is
+the text that is currently selected in micro (usually such text is
+displayed with a white background). When the `mouse` option is enabled,
+the mouse can be used to select text, as well as other keybindings,
+such as ShiftLeft, etc...
+
+The terminal also has a keybinding (`Ctrl-Shift-c` or `Command-c`) to perform
+a copy, and the text that it copies is the text selected by the terminal's
+selection (*not* micro's selection). To select text with the terminal
+selection, micro's mouse support must first be disabled by turning the
+`mouse` option off. The terminal, unlike micro, has no sense of different
+buffers/splits and what the different characters being displayed are. This
+means that for copying multiple lines using the terminal selection, you
+should first disable line numbers and diff indicators (turn off the `ruler`
+and `diffgutter` options), otherwise they might be part of your selection
+and copied.

package/runtime/help/defaultkeys.md

@@ -0,0 +1,141 @@
+# 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`
+
+Please remember that *all* keys here are rebindable! If you don't like it, you
+can change it!
+
+### Power user
+
+| Key       | Description of function                                                                           |
+|---------- |-------------------------------------------------------------------------------------------------- |
+| Ctrl-e    | Open a command prompt for running commands (see `> help commands` for a list of valid commands).  |
+| Tab       | In command prompt, it will autocomplete if possible.                                              |
+| Ctrl-b    | Run a shell command (this will close micro while your command executes).                          |
+
+### Navigation
+
+| Key                         | Description of function                                                                   |
+|---------------------------- |------------------------------------------------------------------------------------------ |
+| Arrows                      | Move the cursor around                                                                    |
+| Shift-arrows                | Move and select text                                                                      |
+| Alt(Ctrl on Mac)-LeftArrow  | Move to the beginning of the current line                                                 |
+| Alt(Ctrl on Mac)-RightArrow | Move to the end of the current line                                                       |
+| Home                        | Move to the beginning of text on the current line                                         |
+| End                         | Move to the end of the current line                                                       |
+| Ctrl(Alt on Mac)-LeftArrow  | Move cursor one word left                                                                 |
+| Ctrl(Alt on Mac)-RightArrow | Move cursor one word right                                                                |
+| Alt-{                       | Move cursor to previous empty line, or beginning of document                              |
+| Alt-}                       | Move cursor to next empty line, or end of document                                        |
+| PageUp                      | Move cursor up one page                                                                   |
+| PageDown                    | Move cursor down one page                                                                 |
+| Ctrl-Home or Ctrl-UpArrow   | Move cursor to start of document                                                          |
+| Ctrl-End or Ctrl-DownArrow  | Move cursor to end of document                                                            |
+| 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
+
+| Key          | Description of function   |
+|------------- |-------------------------- |
+| Ctrl-t       | Open a new tab            |
+| Alt-, Alt-p  | Previous tab              |
+| Alt-. Alt-t  | Next tab                  |
+
+### Find Operations
+
+| Key       | Description of function                   |
+|---------- |------------------------------------------ |
+| Ctrl-f    | Find (opens prompt)                       |
+| Ctrl-n    | Find next instance of current search      |
+| Ctrl-p    | Find previous instance of current search  |
+
+Note: `Ctrl-n` and `Ctrl-p` should be used from the main buffer, not from inside
+the search prompt. After `Ctrl-f`, press enter to complete the search and then
+you can use `Ctrl-n` and `Ctrl-p` to cycle through matches.
+
+### File Operations
+
+| Key           | Description of function                                           |
+|-------------- |------------------------------------------------------------------ |
+| Ctrl-q Alt-q  | Close current file (quits micro if this is the last file open)    |
+| Ctrl-o        | Open a file (prompts for filename)                                |
+| Ctrl-s        | Save current file                                                 |
+
+### Text operations
+
+| Key                                 | Description of function                   |
+|------------------------------------ |------------------------------------------ |
+| Ctrl(Alt on Mac)-Shift-RightArrow   | Select word right                         |
+| Ctrl(Alt on Mac)-Shift-LeftArrow    | Select word left                          |
+| Alt(Ctrl on Mac)-Shift-LeftArrow    | Select to start of current line           |
+| Alt(Ctrl on Mac)-Shift-RightArrow   | Select to end of current line             |
+| Shift-Home                          | Select to start of current line           |
+| Shift-End                           | Select to end of current line             |
+| Ctrl-Shift-UpArrow                  | Select to start of file                   |
+| Ctrl-Shift-DownArrow                | Select to end of file                     |
+| Ctrl-x                              | Cut selected text                         |
+| Ctrl-c                              | Copy selected text                        |
+| Ctrl-v                              | Paste                                     |
+| Ctrl-k                              | Cut current line                          |
+| Ctrl-d                              | Duplicate current line                    |
+| Ctrl-z                              | Undo                                      |
+| Ctrl-y                              | Redo                                      |
+| Alt-UpArrow Alt-k                   | Move current line or selected lines up    |
+| Alt-DownArrow Alt-j                 | Move current line or selected lines down  |
+| Alt-Backspace or Alt-Ctrl-h         | Delete word left                          |
+| Ctrl-a                              | Select all                                |
+| Tab                                 | Indent selected text                      |
+| Shift-Tab                           | Unindent selected text                    |
+
+### Macros(not implemented yet)
+
+| 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(not implemented yet)
+
+| Key               | Description of function                                                                       |
+|------------------ |---------------------------------------------------------------------------------------------- |
+| Alt-n             | Create new multiple cursor from selection (will select current word if no current selection)  |
+| Alt-Shift-Up      | Spawn a new cursor on the line above the current one                                          |
+| Alt-Shift-Down    | Spawn a new cursor on the line below the current one                                          |
+| Alt-p             | Remove latest multiple cursor                                                                 |
+| Alt-c             | Remove all multiple cursors (cancel)                                                          |
+| Alt-x             | Skip multiple cursor selection                                                                |
+| Alt-m             | Spawn a new cursor at the beginning of every line in the current selection                    |
+| Ctrl-MouseLeft    | Place a multiple cursor at any location                                                       |
+
+### Other
+
+| Key       | Description of function                                                               |
+|---------- |-------------------------------------------------------------------------------------- |
+| Ctrl-g    | Open help file                                                                        |
+| 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
+
+| Key       | Description of function   |
+|---------- |-------------------------- |
+| Alt-f     | Next word                 |
+| Alt-b     | Previous word             |
+| Alt-a     | Move to start of line     |
+| Alt-e     | Move to end of line       |
+
+### Function keys.
+
+Warning! The function keys may not work in all terminals!
+
+| Key   | Description of function   |
+|------ |-------------------------- |
+| F1    | Open help                 |
+| F2    | Save                      |
+| F3    | Find                      |
+| F4    | Quit                      |
+| F7    | Find                      |
+| F10   | Quit                      |

package/runtime/help/help.md

@@ -0,0 +1,63 @@
+# Micro help text
+
+Micro is an easy to use, intuitive, text editor that takes advantage of the
+full capabilities of modern terminals.
+
+Micro can be controlled by commands entered on the command bar, or with
+keybindings. To open the command bar, press `Ctrl-e`: the `>` prompt will
+display. From now on, when the documentation shows a command to run (such as
+`> help`), press `Ctrl-e` and type the command followed by enter.
+
+For a list of the default keybindings, run `> help defaultkeys`.
+For more information on keybindings, see `> help keybindings`.
+To toggle a short list of important keybindings, press Alt-g.
+
+## Quick-start
+
+To quit, press `Ctrl-q`. Save by pressing `Ctrl-s`. Press `Ctrl-e`, as previously
+mentioned, to start typing commands. To see which commands are available, at the
+prompt, press tab, or view the help topic with `> help commands`.
+
+Move the cursor around with the mouse or with the arrow keys. Enter text simply
+by pressing character keys.
+
+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 about colorschemes and syntax highlighting with `> help
+colors`.
+
+Press `Ctrl-w` to move between splits, and type `> vsplit filename` or
+`> hsplit filename` to open a new split.
+
+## Accessing more help
+
+Micro has a built-in help system which can be accessed with the `> help` command.
+
+To view help for the various available topics, press `Ctrl-e` to access command
+mode and type in `> help` followed by a topic. Typing just `> help` will open
+this page.
+
+Here are the available help topics:
+
+* `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
+* `copypaste`: Explains micro's copy and paste usage and configuration.
+   It describes how copy and paste is working on different operating systems and
+   setups.
+
+For example, to open the help page on plugins you would run `> 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.