Formalise plugin: functions, autoload, tests

3 files changed, 170 insertions, 14 deletions

diff --git a/doc/novim-mode.txt b/doc/novim-mode.txt
deleted file mode 100644
index ffff024..0000000
--- a/doc/novim-mode.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-novim-mode.txt
-
-==============================================================================
-CONTENTS                                                     |novim-contents|
-
-    Introduction ....................................... |novim-introduction|
-
-==============================================================================
-Introduction                                    *novim* *novim-introduction*
-
-Novim-mode provides defaults to Insert Mode whenever appropriate and provides
-a set of keybindings to make Vim behave more like a 'normal' editor.
diff --git a/doc/novim_mode.txt b/doc/novim_mode.txt
new file mode 100644
index 0000000..3758f49
--- /dev/null
+++ b/doc/novim_mode.txt
@@ -0,0 +1,170 @@
+*novim_mode.txt* Vim keybindings for 'conventional' editor behaviour
+
+                        NOVIM MODE DOCUMENTATION
+
+==============================================================================
+CONTENTS                                                 |novim-mode-contents|
+
+    Introduction ................................... |novim-mode-introduction|
+    Installation ................................... |novim-mode-installation|
+    Usage ................................................. |novim-mode-usage|
+    Keybindings ..................................... |novim-mode-keybindings|
+    Interoperability ........................... |novim-mode-interoperability|
+    Known Issues ................................... |novim-mode-known-issues|
+    References ................................. |novim-mode-known-references|
+
+==============================================================================
+1. Introduction                        *novim-mode* *novim-mode-introduction*
+
+Novim-mode makes Vim behave like a 'conventional', non-modal editor. Where key
+presses default to inserting text, `CTRL+S` saves the file and so on. In the
+same way that 'vim-mode' plugins are available for other editors to enable
+Vim-style keybindings, so too is 'novim-mode' available in Vim to enable
+'traditional'-style keybindings.
+
+Vim is one of the most battle-tested, ubiquitous and extensible editors
+available. If your muscle memory is already fluent with non-vim keybindings
+then you will be able to instantly benefit from all that is valuable about
+Vim without the learning curve of Normal Mode.
+
+==============================================================================
+2. Installation                                     *novim-mode-installation*
+
+Use your favourite plugin manager, eg, for vim-plug; >
+
+  Plug 'tombh/novim-mode'`
+<
+
+==============================================================================
+3. Usage                                                   *novim-mode-usage*
+
+Most keybindings should work as you might expect from, say Atom or Sublime
+Text; `SHIFT+ARROW` to select and `CTRL+C/V` to copy/paste. But don't expect
+Vim to completely bend to your will, it is still useful to familiarise yourself
+with some of Vim's basic concepts. For instance you may on occasion find
+yourself stuck in a particular Vim mode, like when pasting text without 'Paste
+Mode' then inserted text can trigger random mappings. In such case `CTRL+Q`
+may not kill Vim and you'll need to find a way of getting to Normal Mode and
+typing `:q` then `<RETURN>`. Such is life with Vim, this plugin is highly
+unlikely to ever change that. (BTW conventional pasting is on by default,
+but to exit an errant 'Paste Mode' use `:set nopaste`.)
+
+If you are new to Vim, then perhaps the only remaining confusion after installing
+this plugin will be about where files go when you open new ones. This question
+will be answered by Vim's concept of 'buffers'. You may wish to install something
+like [vim-buftabline](https://github.com/ap/vim-buftabline) to give a familiar
+list of open files along the top of the editor.
+
+==============================================================================
+4. Keybindings                                       *novim-mode-keybindings*
+
+Many terminals default to intercepting `CTRL+S` to suspend output, if so you
+will need to disable this behaviour. Most terminals will also bind `CTRL+Q`
+to undo the suspend, useful, but you will also need to unmap that, or change
+the mapping in this plugin for quitting Vim.
+
+`CTRL`-based shortcuts are paired with uppercase letters here because Vim
+does not recognise the difference between cases when using `CTRL` combinations
+and documenting in uppercase implies something of this distinction.
+
+General editor shortcuts
+  * `CTRL+N`: Open a new file.
+  * `CTRL+O`: Open an existing file.
+  * `CTRL+S`: Saves the current file.
+  * `CTRL+G`: Goto line.
+  * `ALT+;`: Vim command prompt.
+  * `ALT+o`: Replaces native `CTRL+O` to give one-off Normal Mode commands.
+
+Pane controls
+  * `ALT+ARROW`: Change pane/buffer focus.
+  * `CTRL+W`: Closes current pane-like thing. Also closes associated
+     quickfix and location panes.
+
+Selecting, copy and paste
+  * `SHIFT+ARROW`: Select text
+  * `CTRL+C`: Copy selection or copy line if no selection.
+  * `CTRL+X`: Cut selection or cut line if no selection.
+  * `CTRL+V`: Paste current selection.
+  * `CTRL+A`: Select all.
+  * `CTRL+D`: Select word under cursor. Use something like vim-multicursors
+    [1] for multi cursor support.
+  * `CTRL+L`: Select line under cursor, repetition selects more lines.
+
+Indenting
+  * `TAB` or `ALT+]`: Indent current line or selected text.
+     _[`TAB` currently broken]_
+  * `SHIFT+TAB` or `ALT+[`: Unindent current line or selected text.
+
+Finding, replacing
+  * `CTRL+F`: Find text. When text is selected that selection is searched
+    for.
+  * `F3` and `SHIFT+F3`: Find next and previous occurences.
+  * `CTRL+H`: Find and replace. `[FIND]` and `[REPLACE]` are prepopulated.
+
+Undoing
+  * `CTRL+Z` or `CTRL+U`: Undo.
+  * `CTRL+Y`: Redo.
+
+Other text manipulation tricks
+  * `CTRL+LEFT/RIGHT`: Move cursor per word (works in selection as well).
+  * `CTRL+ALT+k`: Delete current line.
+  * `CTRL+ALT+k`: Duplicate current line.
+  * `CTRL+UP/DOWN`: Move current line or selected text up/down.
+
+==============================================================================
+5. Interoperability                             *novim-mode-interoperability*
+
+When adding a new binding of your own that needs Normal mode, you should use
+`<C-O>` before the targeted command, for example; >
+
+  " Ensure CtrlP doesn't get overridden by autocomplete in insertmode
+  inoremap <C-P> <C-O>:CtrlP<CR>
+<
+
+Overriding or disabling shortcuts in this plugin can be done in several
+ways. The simplest way is to use: >
+
+  let g:novim_mode_use_shortcuts = 0
+  inoremap ... custom mapping ...
+  call novim_mode#StartNoVimMode()
+<
+
+Alternatively you can unmap a mapping using commands such as `nunmap`,
+`iunmap`, `sunmap`, etc.
+
+Lastly shorcuts are also grouped roughly under the headings described above,
+so you may be able to disable one of the
+following: >
+
+  let g:novim_mode_use_general_app_shortcuts = 1
+  let g:novim_mode_use_pane_controls = 1
+  let g:novim_mode_use_copypasting = 1
+  let g:novim_mode_use_indenting = 1
+  let g:novim_mode_use_finding = 1
+  let g:novim_mode_use_undoing = 1
+  let g:novim_mode_use_text_tricks = 1
+
+  " Small fixes to HOME and PAGEUP behaviour
+  let g:novim_mode_use_editor_fixes = 1
+  " Allows scrolling through wrapped lines one visual line at a time
+  let g:novim_mode_use_better_wrap_navigation = 1
+<
+==============================================================================
+6. Known Issues                                     *novim-mode-known-issues*
+
+  * There seems to be a bug where only `SHIFT+TAB` and not `TAB` works for
+    indenting during selection mode. Again this may be fixed by simulating
+    selection mode with Visual mode in the future.
+  * When using `novim_mode_use_better_wrap_navigation`, then END key does not
+    go the end of a visual line, but to the end of the physically represented
+    line.
+  * Mapping `<CTRL+m>` internally means mapping `<RETURN>`. This is a
+    throwback to Vim's days as a pure terminal application.
+  * `CTRL+BACKSPACE` internally represents <CTRL+H>, which can be annoying.
+    Again this is a throwback to Vim's days as a pure terminal application.
+
+==============================================================================
+7. References                                         *novim-mode-references*
+
+[1] https://github.com/terryma/vim-multiple-cursors
+
diff --git a/doc/tags b/doc/tags
deleted file mode 100644
index 64a1b6a..0000000
--- a/doc/tags
+++ /dev/null
@@ -1,2 +0,0 @@
-novim	novim-mode.txt	/*novim*
-novim-introduction	novim-mode.txt	/*novim-introduction*