Update options docs and new docs on copy-paste

runtime/help/copypaste.md

@@ -0,0 +1,109 @@
+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.
+
+# Pasting
+
+## 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.
+
+## Recommendations
+
+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.
+
+# Copying
+
+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 (turn off the `ruler` option), otherwise
+they might be part of your selection and copied.
+
+## Recommendations
+
+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 (`ruler` option) 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).

runtime/help/options.md

@@ -2,11 +2,14 @@
 
 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.
+Micro uses `$MICRO_CONFIG_HOME` as the configuration directory. If this environment
+variable is not set, it uses `$XDG_CONFIG_HOME/micro` instead. If that
+environment variable is not set, it uses `~/.config/micro` as the configuration
+directory. In the documentation, we use `~/.config/micro` to refer to the
+configuration directory (even if it may in fact be somewhere else if you have
+set either of the above environment variables).
 
-Here are the options that you can set:
+Here are the available options:
 
 * `autoindent`: when creating a new line, use the same indentation as the 
    previous line.
@@ -85,11 +88,11 @@ Here are the options that you can set:
 
 	default value: `unix`
 
-* `filetype`: sets the filetype for the current buffer. This setting is
-   `local only`.
+* `filetype`: sets the filetype for the current buffer. Set this option to `off`
+   to completely disable filetype detection.
 
-	default value: this will be automatically set depending on the file you have
-	open
+	default value: `unknown`. This will be automatically overridden depending
+    on the file you open.
 
 * `ignorecase`: perform case-insensitive searches.
 
@@ -136,7 +139,8 @@ Here are the options that you can set:
 
 	default value: `true`
 
-* `rmtrailingws`: micro will automatically trim trailing whitespaces at eol.
+* `rmtrailingws`: micro will automatically trim trailing whitespaces at ends of
+   lines.
 
 	default value: `false`
 
@@ -145,17 +149,19 @@ Here are the options that you can set:
 	default value: `true`
 
 * `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. Information is saved to
+   `~/.config/micro/buffers/`
 
 	default value: `false`
 
 * `savehistory`: remember command history between closing and re-opening
-   micro.
+   micro. Information is saved to `~/.config/micro/buffers/history`.
 
     default value: `true`
 
 * `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. Information is
+   saved to `~/.config/micro/buffers/`.
 
 	default value: `false`
 
@@ -163,8 +169,8 @@ Here are the options that you can set:
 
     default value: `false`
 
-* `scrollmargin`: amount of lines you would like to see above and below the
-   cursor.
+* `scrollmargin`: margin at which the view starts scrolling when the cursor
+   approaches the edge of the view.
 
 	default value: `3`
 
@@ -172,23 +178,23 @@ Here are the options that you can set:
 
 	default value: `2`
 
-* `smartpaste`: should micro add leading whitespace when pasting multiple lines?
+* `smartpaste`: add leading whitespace when pasting multiple lines.
    This will attempt to preserve the current indentation level when pasting an
    unindented block.
 
 	default value: `true`
 
-* `softwrap`: should micro wrap lines that are too long to fit on the screen.
+* `softwrap`: wrap lines that are too long to fit on the screen.
 
 	default value: `false`
 
-* `splitbottom`: when a horizontal split is created, should it be created below
-   the current split?
+* `splitbottom`: when a horizontal split is created, create it below the
+   current split.
 
 	default value: `true`
 
-* `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, create it to the right of the
+   current split.
 
 	default value: `true`
 
@@ -217,7 +223,7 @@ Here are the options that you can set:
 
 	default value: `sudo`
 
-* `syntax`: turns syntax on or off.
+* `syntax`: enables syntax highlighting.
 
 	default value: `true`
 
@@ -227,31 +233,26 @@ Here are the options that you can set:
 
 	default value: `false`
 
-* `tabsize`: sets the tab size to `option`
+* `tabsize`: the size in spaces that a tab character should be displayed with.
 
 	default value: `4`
 
-* `tabstospaces`: use spaces instead of tabs
+* `tabstospaces`: use spaces instead of tabs.
 
 	default value: `false`
 
-* `termtitle`: defines whether or not your terminal's title will be set by micro
-   when opened.
-
-	default value: `false`
-
-* `useprimary` (only useful on *nix): defines whether or not micro will use the
+* `useprimary` (only useful on unix): 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.
+   the normal clipboard using Ctrl-c and Ctrl-v.
 
 	default value: `true`
 
 ---
 
-Plugin options: all plugins come with a special option to enable or disable them. THe option
+Plugin options: all plugins come with a special option to enable or disable them. The option
 is a boolean with the same name as the plugin itself.
 
-Any option you set in the editor will be saved to the file 
+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.