Pulled content from the README into the man page

1 files changed, 704 insertions, 41 deletions

diff --git a/vis.1 b/vis.1
index b655921..db8a312 100644
--- a/vis.1
+++ b/vis.1
@@ -1,49 +1,712 @@
-.TH VIS 1 vis\-VERSION
-.nh
-.SH NAME
-vis - a vim like text editor
-.SH SYNOPSIS
-.B vis
-.RI [ +command ...]
-.RI [ files ...|-]
-.br
-.SH DESCRIPTION
-.B vis
+.Dd $Mdocdate: September 10 2016 $
+.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.
-.SH OPTIONS
-.B \-v
+.\"
+.Bl -tag
+.It Fl v
 Print version information and exit.
-
-.B \-\-
-Denotes the end of the options. Arguments after this will be handled as a file name.
-.SH ENVIRONMENT VARIABLES
-.TP
-.B VIS_PATH
-Override path to look for Lua support files as used for syntax highlighting.
+.It Fl -
+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
+Visual block mode is not implemented and there exists no immediate plan
+to do so. Instead vis has built in support for multiple cursors.
+.Pp
+Command mode is implemented as a regular file. Use the full power of
+the editor to edit your commands / search terms.
+.Pp
+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+
+and
+.Ql g-
+traverse the history in chronological order. Further more the
+.Iq :earlier
+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
+one of
+.Ql [A-Z]
+to append to an existing macro.
+.Ql q
+starts a recording,
+.Ql @
+plays it back.
+.Ql @@
+refers to the least recently recorded macro.
+.Ql @:
+repeats the last :-command.
+.Ql @/
+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.
+.\"
+.\"
+.Ss Operators
+.\"
+.Bl -tag
+.It c
+change
+.It d
+delete
+.It !
+filter
+.It =
+indent, currently an alias for gq
+.It gq
+format using fmt(1)
+.It gu
+make lowercase
+.It gU
+make uppercase
+.It J
+join
+.It p
+put
+.It <
+shift-left
+.It >
+shift-right
+.It ~
+swap case
+.It y
+yank
+.El
+.\"
+.\"
+.Ss Movements
+.\"
+.Bl -tag
+.It 0
+start of line
+.It b
+previous start of a word
+.It B
+previous start of a WORD
+.It $
+end of line
+.It e
+next end of a word
+.It E
+next end of a WORD
+.It F char
+to next occurrence of char to the left
+.It f char
+to next occurrence of char to the right
+.It ^
+first non-blank of line
+.It g0
+begin of display line
+.It g$
+end of display line
+.It ge
+previous end of a word
+.It gE
+previous end of a WORD
+.It gg
+begin of file
+.It G
+goto line or end of file
+.It gj
+display line down
+.It gk
+display line up
+.It g_
+last non-blank of line
+.It gm
+middle of display line
+.It |
+goto column
+.It h
+char left
+.It H
+goto top/home line of window
+.It j
+line down
+.It k
+line up
+.It l
+char right
+.It L
+goto bottom/last line of window
+.It ` mark
+go to mark
+.It ' mark
+go to start of line containing mark
+.It %
+match bracket
+.It M
+goto middle line of window
+.It ]]
+next end of C-like function
+.It }
+next paragraph
+.It )
+next sentence
+.It ][
+next start of C-like function
+.It N
+repeat last search backwards
+.It n
+repeat last search forward
+.It []
+previous end of C-like function
+.It [{
+previous start of block
+.It ]}
+next start of block
+.It [(
+previous start of parenthese pair
+.It ])
+next start of parenthese pair
+.It {
+previous paragraph
+.It (
+previous sentence
+.It [[
+previous start of C-like function
+.It ;
+repeat last to/till movement
+.It ,
+repeat last to/till movement but in opposite direction
+.It #
+search word under cursor backwards
+.It *
+search word under cursor forwards
+.It T char
+till before next occurrence of char to the left
+.It t char
+till before next occurrence of char to the right
+.It ? text
+to next match of text in backward direction
+.It / text
+to next match of text in forward direction
+.It w
+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
+Some of these commands do not work as in vim when prefixed with a
+digit i.e. a multiplier. As an example in vim
+.Ql 3$
+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
+.It W
+WORD
+.It s
+sentence
+.It p
+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:
+.Bl -tag
+.It ae
+entire file content
+.It ie
+entire file content except for leading and trailing empty lines
+.It af
+C-like function definition including immediately preceding comments
+.It if
+C-like function definition only function body
+.It al
+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
+upon exit). There always exists one primary cursor located within the
+current view port. Additional cursors ones can be created as needed. If
+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
+.It Ctrl-Meta-K
+create count new cursors on the lines above the first cursor
+.It Ctrl-J
+create count new cursors on the lines below
+.It Ctrl-Meta-J
+create count new cursors on the lines below the last cursor
+.It Ctrl-P
+remove primary cursor
+.It Ctrl-N
+select word the cursor is currently over, switch to visual mode
+.It Ctrl-U
+make the count previous cursor primary
+.It Ctrl-D
+make the count next cursor primary
+.It Ctrl-C
+remove the count cursor column
+.It Ctrl-L
+remove all but the count cursor column
+.It Tab
+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
+.It A
+create a cursor at the end of every selected line
+.It Tab
+left align selections by inserting spaces
+.It Shift-Tab
+right align selections by inserting spaces
+.It Ctrl-N
+create new cursor and select next word matching current selection
+.It Ctrl-X
+clear (skip) current selection, but select next matching word
+.It Ctrl-P
+remove primary cursor
+.It Ctrl-U/K
+make the count previous cursor primary
+.It Ctrl-D/J
+make the count next cursor primary
+.It Ctrl-C
+remove the count cursor column
+.It Ctrl-L
+remove all but the count cursor column
+.It +
+rotates selections rightwards count times
+.It -
+rotates selections leftwards count times
+.It \e
+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
+.It <
+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
+.It "A-"Z
+append to corresponding general purpose register
+.It "*,
+"+  system clipboard integration via shell script vis-clipboard
+.It "0
+yank register
+.It "/
+search register
+.It ":
+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.
+.\"
+.Bl -tag
+.Iq :bdelete
+close all windows which display the same file as the current one
+.Iq :earlier
+revert to older text state
+.Iq :e
+replace current file with a new one or reload it from disk
+.Iq :langmap
+set key equivalents for layout specific key mappings
+.Iq :later
+revert to newer text state
+.Iq :!
+launch external command, redirect keyboard input to it
+.Iq :map
+add a global key mapping
+.Iq :map-window
+add a window local key mapping
+.Iq :new
+open an empty window, arrange horizontally
+.Iq :open
+open a new window
+.Iq :qall
+close all windows, exit editor
+.Iq :q
+close currently focused window
+.It :r
+insert content of another file at current cursor position
+.It :set
+set the options below
+.It :split
+split window horizontally
+.It :s
+search and replace currently implemented in terms of `sed(1)`
+.It :unmap
+remove a global key mapping
+.It :unmap-window
+remove a window local key mapping
+.It :vnew
+open an empty window, arrange vertically
+.It :vsplit
+split window vertically
+.It :wq
+write changes then close window
+.It :w
+write current buffer content to file
+.It  tabwidth  [1-8]           default 8
+set display width of a tab and number of spaces to use if expandtab is enabled
+.It  expandtab  (yes|no)        default no
+whether typed in tabs should be expanded to tabwidth spaces
+.It  autoindent (yes|no)        default no
+replicate spaces and tabs at the beginning of the line when
+.It  number         (yes|no)    default no
+.It  relativenumber (yes|no)    default no
+whether absolute or relative line numbers are printed alongside
+.It  syntax      name           default yes
+use syntax definition given (e.g. "c") or disable syntax
+.It  show
+show/hide special white space replacement symbols
+.Bl -bullet
+.It
+newlines = [0|1]         default 0
+.It
+tabs     = [0|1]         default 0
+.It
+spaces   = [0|1]         default 0
+.El
+.It  cursorline (yes|no)        default no
+highlight the line on which the cursor currently resides
+.It  colorcolumn number         default 0
+highlight the given column
+.It  horizon    number          default 32768 (32K)
+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
+.\"
+.\"
+.Sh ENVIRONMENT
+.\"
+.Bl -tag
+.Ev VIS_PATH
+Override path to look for Lua support files as used for  syntax  highlighting.
 Defaults (in this order) to:
-.RS
-.RS
-.TP
+.Bl -bullet
+.It
 The location of the vis binary
-.TP
-.B $XDG_CONFIG_HOME/vis
+.It
+.Pa $XDG_CONFIG_HOME/vis
 where
-.B $XDG_CONFIG_HOME
+.Ev $XDG_CONFIG_HOME
 refers to
-.B $HOME/.config
+.Pa $HOME/.config
 if unset
-.TP
-.B  /usr/local/share/vis
-.TP
-.B  /usr/share/vis
-.RE
-.RE
-.TP
-.B VIS_THEME
+.It
+.Pa /usr/local/share/vis
+.It
+.Pa /usr/share/vis
+.El
+.Ev VIS_THEME
 Override syntax highlighting theme to use.
-.SH HELP
-Type
-.B :help
-to get a list of currently active key bindings and their respective meaning.
-.SH AUTHOR
-vis is written by Marc André Tanner <mat at brain-dump.org>
+.El
+.\"
+.\"
+.Sh FILES
+.\"
+.Pp
+Settings and keymaps can be specified in a
+.Pa visrc.lua
+file, which will
+be read by
+.Pa vis
+at runtime. An example
+.Pa visrc.lua
+file is installed in
+.Pa /usr/local/share/vis
+by default. This file can be copied to
+.Pa $XDG_CONFIG_HOME/vis
+(which defaults to
+.Pa $HOME/.config/vis
+) for further configuration.
+.Pp
+The environment variable
+.Pa VIS_PATH
+can be set to override the path that
+.Pa vis
+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
+refers to
+`$HOME/.config
+if unset
+.It
+.Pa /usr/local/share/vis`
+.It
+.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