Manual: Cleanup, and real "KEY BINDINGS" section

1 files changed, 119 insertions, 155 deletions

diff --git a/vis.1 b/vis.1
index db8a312..3ec5eef 100644
--- a/vis.1
+++ b/vis.1
@@ -2,23 +2,15 @@
 .Dt VIS 1
 .Os
 .Sh NAME
-.\"
 .Nm vis
 .Nd a vim like text editor
-.\"
-.\"
 .Sh SYNOPSIS
-.\"
 .Nm vis
 .Op Ic +command
 .Op Ar files Fl
-.\"
-.\"
 .Sh DESCRIPTION
-.\"
 .Nm vis
 is a highly efficient vim like text editor.
-.\"
 .Bl -tag
 .It Fl v
 Print version information and exit.
@@ -26,10 +18,7 @@ Print version information and exit.
 Denotes  the  end  of the options. Arguments after this will be handled as a
 file name.
 .El
-.\"
-.\"
 .Ss Modes
-.\"
 Vis implements more or less functional normal, operator-pending, insert,
 replace and visual (in both line and character wise variants) modes.
 .Pp
@@ -42,20 +31,15 @@ the editor to edit your commands / search terms.
 Ex mode is deliberately not implemented, instead a variant of the
 structural regular expression based command language of `sam(1)`
 is supported.
-.\"
-.\"
 .Ss Undo/Redo and Repeat
-.\"
 .Pp
 The text is currently snapshotted whenever an operator is completed as
 well as when insert or replace mode is left. Additionally a snapshot is
 also taken if in insert or replace mode a certain idle time elapses.
-.\"
 .Pp
 Another idea is to snapshot based on the distance between two consecutive
 editing operations (as they are likely unrelated and thus should be
 individually reversible).
-.\"
 .Pp
 Besides the regular undo functionality, the key bindings 
 .Ql g+
@@ -67,32 +51,22 @@ and
 .Iq :later
 commands provide means to restore the text to an arbitrary
 state.
-.\"
 .Pp
 The repeat command
 .Ql \&.
 works for all operators and is able to repeat
 the last insertion or replacement.
-.\"
-.\"
 .Ss Tab <-> Space conversion and Line endings \n vs \r\n
-.\"
 .Pp
 Tabs can optionally be expanded to a configurable number of spaces.
 The first line ending in the file determines what will be inserted upon
 a line break (defaults to \n).
-.\"
-.\"
 .Ss Jump list and change list
-.\"
 .Pp
 A per window, file local jump list (navigate with `CTRL+O` and `CTRL+I`)
 and change list (navigate with `g;` and `g,`) is supported. The jump
 list is implemented as a fixed sized ring buffer.
-.\"
-.\"
 .Ss Macros
-.\"
 The general purpose registers
 .Ql [a-z]
 can be used to record macros. Use
@@ -111,24 +85,16 @@ repeats the last :-command.
 is equivalent to
 .Ql n
 in normal mode.
-.\"
-.\"
 .Ss Structural Regular Expression based Command Language
-.\"
 .Nm vis
 supports
 .Xr sam 1
 structural regular expression based command language.
-.\"
-.\"
 .Ss Mouse support
-.\"
 .Pp
 The mouse is currently not used at all.
-.\"
-.\"
+.Sh KEY BINDINGS
 .Ss Operators
-.\"
 .Bl -tag
 .It c
 change
@@ -157,10 +123,7 @@ swap case
 .It y
 yank
 .El
-.\"
-.\"
 .Ss Movements
-.\"
 .Bl -tag
 .It 0
 start of line
@@ -271,7 +234,6 @@ next start of a word
 .It W
 next start of a WORD
 .El
-.\"
 .Pp
 An empty line is currently neither a word nor a WORD.
 .Pp
@@ -282,16 +244,12 @@ moves to the end
 of the 3rd line down. However vis treats it as a move to the end of
 current line which is repeated 3 times where the last two have no
 effect.
-.\"
-.\"
 .Ss Text objects
-.\"
 .Pp
 All of the following text objects are implemented in an inner variant
 (prefixed with
 .Ql i`) and a normal variant (prefixed with
 .Ql a`):
-.\"
 .Bl -tag
 .It w
 word
@@ -304,18 +262,15 @@ paragraph
 .It [,], (,), {,}, <,>, ", ', `
 block enclosed by these symbols
 .El
-.\"
 .Pp
 For sentence and paragraph there is no difference between the inner and
 normal variants.
-.\"
 .Bl -tag
 .It gn
 matches the last used search term in forward direction
 .It gN
 matches the last used search term in backward direction
 .El
-.\"
 .Pp
 Additionally the following text objects, which are not part of stock
 vim are also supported:
@@ -333,10 +288,7 @@ current line
 .It il
 current line without leading and trailing white spaces
 .El
-.\"
-.\"
 .Ss Multiple Cursors / Selections
-.\"
 .Nm vis
 supports multiple cursors with immediate visual feedback (unlike in the
 visual block mode of vim where for example inserts only become visible
@@ -346,7 +298,6 @@ more than one cursor exists, the primary one is styled differently
 (yellow by default).
 .Pp
 To manipulate multiple cursors use in normal mode:
-.\"
 .Bl -tag
 .It Ctrl-K
 create count new cursors on the lines above
@@ -373,10 +324,8 @@ try to align all cursor on the same column
 .It Esc
 dispose all but the primary cursor
 .El
-.\"
 .Pp
 Visual mode was enhanced to recognize:
-.\"
 .Bl -tag
 .It I
 create a cursor at the start of every selected line
@@ -409,18 +358,13 @@ trim selections, remove leading and trailing white space
 .It Esc
 clear all selections, switch to normal mode
 .El
-.\"
 .Pp
 In insert/replace mode:
-.\"
 .Bl -tag
 .It Shift-Tab
 align all cursors by inserting spaces
 .El
-.\"
-.\"
 .Ss Marks
-.\"
 .Bl -tag
 .It [a-z]
 general purpose marks
@@ -429,13 +373,9 @@ start of the last selected visual area in current buffer
 .It >
 end of the last selected visual area in current buffer
 .El
-.\"
-.\"
 .Ss Registers
-.\"
 .Pp
 Supported registers include:
-.\"
 .Bl -tag
 .It "a-"z
 general purpose registers
@@ -452,16 +392,12 @@ command register
 .It "_
 black hole (/dev/null) register
 .El
-.\"
 .Pp
 If no explicit register is specified a default register is used.
-.\"
-.\"
 .Sh COMMANDS
-.\"
 .Pp
-Besides the sam command language the following commands are also recognized at the `:`-command prompt. Any unique prefix can be used.
-.\"
+Besides the sam command language the following commands are also recognized at
+the `:`-command prompt. Any unique prefix can be used.
 .Bl -tag
 .Iq :bdelete
 close all windows which display the same file as the current one
@@ -537,20 +473,125 @@ how far back the lexer will look to synchronize parsing
 .It  theme      name            default dark-16.lua | solarized.lua (16 | 256 color)
 use the given theme / color scheme for syntax highlighting
 .El
-.\"
 .Pp
 Commands taking a file name will use a simple file open dialog based on
 the included `vis-open` shell script and `vis-menu` utility, if given
 a file pattern or directory.
-.\"
 .Ic :e *.c
 opens a menu with all C files
 .Ic :e \&.
 opens a menu with all files of the current directory
-.\"
-.\"
+.Ss Runtime Configurable Key Bindings
+.Pp
+Vis supports run time key bindings via the
+.Ic :{un,}map{,-window}
+set of commands. The basic syntax is
+.Ic :map <mode> <lhs> <rhs>
+where mode is one of 
+.Ql normal
+,
+.Ql insert
+,
+.Ql replace
+,
+.Ql visual
+,
+.Ql visual-line
+or
+.Ql operator-pending
+.
+.Ql lhs
+refers to the key to map,
+.Ql rhs
+is a key action or alias. An existing mapping can be overridden by appending
+.Ql !
+to the map command.
+.Pp
+Key mappings are always recursive, this means doing something like
+.Ic :map! normal j 2j
+will not work because it will enter an endless loop. Instead vis uses
+pseudo keys referred to as key actions which can be used to invoke a set
+of available (see
+.Ic :help
+or
+.Ic F1
+for a list) editor functions. Hence the correct thing to do would be
+.Ic :map! normal j 2<cursor-line-down>
+.Pp
+Unmapping works as follows:
+.Ic :unmap <mode> <lhs>
+.Pp
+The commands suffixed with `-window` only affect the currently active window.
+.Ss Layout Specific Key Bindings
+.Pp
+Vis allows to set key equivalents for non-latin keyboard layouts. This
+facilitates editing non-latin texts. The defined mappings take effect
+in all non-input modes, i.e. everywhere except in insert and replace mode.
+.Pp
+For example, the following maps the movement keys in Russian layout:
+.Ic :langmap ролд hjkl
+.Pp
+More generally the syntax of the `:langmap` command is:
+.Ic :langmap <keys in your layout> <equivalent keys in latin layout>
+.Pp
+If the key sequences have not the same length, the rest of the longer
+sequence will be discarded.
+.Ss Runtime Configurable Key Bindings
+.Pp
+Vis supports run time key bindings via the
+.Ic :{un,}map{,-window}
+set of commands. The basic syntax is
+.Ic :map <mode> <lhs> <rhs>
+where mode is one of 
+.Ql normal
+,
+.Ql insert
+,
+.Ql replace
+,
+.Ql visual
+,
+.Ql visual-line
+or
+.Ql operator-pending
+.
+.Ql lhs
+refers to the key to map,
+.Ql rhs
+is a key action or alias. An existing mapping can be overridden by appending
+.Ql !
+to the map command.
+.Pp
+Key mappings are always recursive, this means doing something like
+.Ic :map! normal j 2j
+will not work because it will enter an endless loop. Instead vis uses
+pseudo keys referred to as key actions which can be used to invoke a set
+of available (see
+.Ic :help
+or
+.Ic F1
+for a list) editor functions. Hence the correct thing to do would be
+.Ic :map! normal j 2<cursor-line-down>
+.Pp
+Unmapping works as follows:
+.Ic :unmap <mode> <lhs>
+.Pp
+The commands suffixed with `-window` only affect the currently active window.
+.Ss Layout Specific Key Bindings
+.Pp
+Vis allows to set key equivalents for non-latin keyboard layouts. This
+facilitates editing non-latin texts. The defined mappings take effect
+in all non-input modes, i.e. everywhere except in insert and replace mode.
+.Pp
+For example, the following maps the movement keys in Russian layout:
+.Ic :langmap ролд hjkl
+.Pp
+More generally the syntax of the `:langmap` command is:
+.Ic :langmap <keys in your layout> <equivalent keys in latin layout>
+.Pp
+If the key sequences have not the same length, the rest of the longer
+sequence will be discarded.
 .Sh ENVIRONMENT
-.\"
 .Bl -tag
 .Ev VIS_PATH
 Override path to look for Lua support files as used for  syntax  highlighting.
@@ -573,10 +614,7 @@ if unset
 .Ev VIS_THEME
 Override syntax highlighting theme to use.
 .El
-.\"
-.\"
 .Sh FILES
-.\"
 .Pp
 Settings and keymaps can be specified in a
 .Pa visrc.lua
@@ -600,113 +638,39 @@ can be set to override the path that
 will look for Lua support files as used for syntax highlighting.
 .Pa VIS_PATH
 defaults (in this order) to:
-.\"
 .Bl -bullet
 .It
 The location of the
 .Nm vis
 binary
 .It
-.Pa $XDG_CONFIG_HOME/vis`, where
+.Pa $XDG_CONFIG_HOME/vis
+where
 .Pa $XDG_CONFIG_HOME
 refers to
-`$HOME/.config
-if unset
+.Pa $HOME/.config
+if unset.
 .It
-.Pa /usr/local/share/vis`
+.Pa /usr/local/share/vis
 .It
-.Pa /usr/share/vis`
+.Pa /usr/share/vis
 .El
-.\"
 .Pp
 The environment variable
 .Ev VIS_THEME
 can be set to specify the theme used by
 .Nm vis
 :
-.\"
 .Bd -literal
 VIS_THEME=/path/to/your/theme.lua
 export VIS_THEME
 .Ed
-.\"
-.\"
-.Ss Runtime Configurable Key Bindings
-.\"
-.Pp
-Vis supports run time key bindings via the
-.Ic :{un,}map{,-window}
-set of commands. The basic syntax is
-.Ic :map <mode> <lhs> <rhs>
-where mode is one of 
-.Ql normal
-,
-.Ql insert
-,
-.Ql replace
-,
-.Ql visual
-,
-.Ql visual-line
-or
-.Ql operator-pending
-.
-.Ql lhs
-refers to the key to map,
-.Ql rhs
-is a key action or alias. An existing mapping can be overridden by appending
-.Ql !
-to the map command.
-.\"
-.Pp
-Key mappings are always recursive, this means doing something like
-.Ic :map! normal j 2j
-will not work because it will enter an endless loop. Instead vis uses
-pseudo keys referred to as key actions which can be used to invoke a set
-of available (see
-.Ic :help
-or
-.Ql F1
-for a list) editor functions. Hence the correct thing to do would be
-.Ic :map! normal j 2<cursor-line-down>
-.\"
-.Pp
-Unmapping works as follows:
-.Pp :unmap <mode> <lhs>
-.Pp
-The commands suffixed with `-window` only affect the currently active window.
-.\"
-.\"
-.Ss Layout Specific Key Bindings
-.\"
-.Pp
-Vis allows to set key equivalents for non-latin keyboard layouts. This
-facilitates editing non-latin texts. The defined mappings take effect
-in all non-input modes, i.e. everywhere except in insert and replace mode.
-.\"
-.Pp
-For example, the following maps the movement keys in Russian layout:
-.Ic :langmap ролд hjkl
-.\"
-.Pp
-More generally the syntax of the `:langmap` command is:
-.Ic :langmap <keys in your layout> <equivalent keys in latin layout>
-.\"
-.Pp
-If the key sequences have not the same length, the rest of the longer
-sequence will be discarded.
-.\"
-.\"
 .Sh SEE ALSO
-.\"
 .Xr vis-menu 1
 .Xr vis-open 1
 .Xr vis-clipboard 1
 .Xr vis-complete 1
-.\"
-.\"
 .Sh AUTHORS
-.\"
 .Nm vis
 is written by
 .An Marc André Tanner Aq mat at brain-dump.org