aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorThomas Buckley-Houston2017-05-30 09:24:00 +0000
committerThomas Buckley-Houston2017-05-30 09:24:00 +0000
commit79bd6b4273325f891d2fcdb2a79ede59e313e414 (patch)
tree48028cfaf00bdd6ef82b83afb638317db4a9a53d /doc
parent37905d1bad1dd19cca13fd36022b0cffb811b699 (diff)
Formalise plugin: functions, autoload, tests
Diffstat (limited to 'doc')
-rw-r--r--doc/novim-mode.txt12
-rw-r--r--doc/novim_mode.txt170
-rw-r--r--doc/tags2
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*