man: first steps towards a proper manual page

1 files changed, 808 insertions, 480 deletions

diff --git a/vis.1 b/vis.1
index 3a91973..7391cae 100644
--- a/vis.1
+++ b/vis.1
@@ -1,21 +1,29 @@
-.Dd $Mdocdate: September 10 2016 $
+.Dd November 29, 2016
 .Dt VIS 1
 .Os
-.Sh NAME
 .
+.Sh NAME
 .Nm vis
-.Nd a vim like text editor
+.Nd a highly efficient text editor
 .
 .Sh SYNOPSIS
-.
 .Nm vis
 .Op Ic +command
-.Op Ar files Fl
+.Op Ar files ...
 .
 .Sh DESCRIPTION
+.Nm
+is a highly efficient screen-oriented text editor combining the strengths of both
+.Nm vi(m)
+and
+.Nm sam .
 .
-.Nm vis
-is a highly efficient vim like text editor.
+This manual page is intended for users already familiar with
+.Nm vi Ns / Ns Nm sam .
+Anyone else should almost certainly read a good tutorial on
+either editor before this manual page.
+.
+The following options are available:
 .Bl -tag
 .It Fl v
 Print version information and exit.
@@ -23,138 +31,553 @@ Print version information and exit.
 .It Fl -
 Denotes  the  end  of the options. Arguments after this will be handled as a
 file name.
+.\" TODO mention +command
 .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.
+The special file
+.Sy -
+instructs
+.Nm
+to read from standard input in which case
+.Cm :wq
+will write to stdandard output, thereby enabling usage as an interactive filter.
 .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.
+If standard input is redirected and all input is consumed,
+.Nm
+will open /dev/tty to gather further commands. Failure to do so results in
+program termination.
 .
-.Ss Undo/Redo and Repeat
-.
-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).
+.Ss Modes
+.Nm
+employs the same
+.Em modal
+editing approach as
+.Nm vi .
+It supports a normal, operator pending, insert, replace and visual
+(in both line and character wise variants) mode.
+.\" TODO: add short per-mode descripton?
 .Pp
-Besides the regular undo functionality, the key bindings 
-.Ql g+
+The visual block and ex modes are deliberately not implemented,
+instead vis has built in support for multiple cursors/selections and an
+.Em interactive
+variant of the structural regular expression based command language of
+.Nm sam .
+.
+.Ss Undo/Redo
+.Nm
+uses an undo tree to keep track of text revisions. The
+.Cm u
+(undo) and
+.Aq Cm C-r
+(redo) commands can be used to traverse the tree along the main branch.
+Addionally
+.Cm g+
 and
-.Ql g-
-traverse the history in chronological order. Further more the
-.Iq :earlier
+.Cm g-
+traverse the history in chronological order. Furthermore the
+.Cm :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
-.
-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).
+.Cm :later
+commands provide means to restore the text to an arbitrary state.
 .
-.Ss Jump list and change list
+.Ss Marks
+A mark associates a given file position to a symbolic name.
+A mark becomes invalid once the underlying file content changes (e.g. it
+being deleted or replaced). If said changes are later undone the mark becomes
+valid again.
+.Bl -tag
+.It a-z
+general purpose marks
+.It <
+start of the last selected visual area in current file
+.It >
+end of the last selected visual area in current file
+.El
+.Pp
+No marks across files are supported. Marks are not preserved over editing sessions.
 .
-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 Registers
+Registers can hold arbitrary data which can later be re-inserted into
+the file or executed as a macro. Supported registers include:
+.Bl -tag
+.It \(dqa-\(dqz
+general purpose registers
+.It \(dqA-\(dqZ
+append to corresponding general purpose register
+.It \(dq*, \(dq+
+system clipboard integration via shell script
+.Xr vis-clipboard 1
+.It \(dq0
+yank register, least recently yanked range
+.It \(dq/
+search register, least recently used search pattern
+.It \(dq:
+command register, least recently executed command
+.It \(dq_
+black hole (/dev/null) register, ignore content is always empty
+.El
+.Pp
+If no explicit register is specified a default register is used.
 .
 .Ss Macros
 .
 The general purpose registers
-.Ql [a-z]
+.Cm \(dqa-\(dqz
 can be used to record macros. Use
 one of
-.Ql [A-Z]
+.Cm \(dqA-\(dqZ
 to append to an existing macro.
-.Ql q
+.Cm q
 starts a recording,
-.Ql @
+.Cm @
 plays it back.
-.Ql @@
+.Cm @@
 refers to the least recently recorded macro.
-.Ql @:
+.Cm @:
 repeats the last :-command.
-.Ql @/
+.Cm @/
 is equivalent to
-.Ql n
+.Cm n
 in normal mode.
 .
-.Ss Structural Regular Expression based Command Language
+.Ss Tab, Space and Newline handling
+.\" TODO properly escape \\n vs \\r \\n
 .
-.Nm vis
-supports
+.Aq Tab
+can optionally be expanded to a configurable number of spaces.
+The first line ending in the file determines what will be inserted when pressing
+.Aq Enter
+(defaults to \\n).
+.
+.Ss Jump list and Change list
+.
+A per window, fixed sized file local jump list (navigate with
+.Aq Cm C-O
+and
+.Aq Cm C-I )
+and change list (navigate with
+.Cm g;
+and
+.Cm g, )
+is supported.
+.
+.Ss Mouse support
+The mouse is currently not used at all.
+.
+.Sh SAM COMMANDS
+.
+.Nm
+supports an interactive variant of
 .Xr sam 1
 structural regular expression based command language.
 .
-.Ss Mouse support
+.Ss Regular expressions
+.Nm
+currently defers regular expression matching to the underlying C library.
+It uses what POSIX refers to as
+.Dq Extended Regular Expressions
+as described in
+.Xr regex 7 "."
+.
+Additonally \[rs]n and \[rs]t may be used to refer to newlines and tabs, respectively.
+The
+.Sy .
+atom matches any character except newline.
+.
+The empty regular expression stands for the last complete expression encountered.
+.
+.Ss Addresses
+An address identifies a substring (or range) in a file. In the following
+.Do
+character
+.Sy n
+.Dc
+means the null string after the
+.Sy n\fR-th
+character in the file, with 1 the first character in the file.
+.Do
+Line
+.Sy n
+.Dc
+means the
+.Sy n\fR-th
+match, starting at the beginning of the file, of the regular expression
+.Li ".*\[rs]n?" "."
+.Po
+The peculiar properties of a last line without a newline are temporarily undefined.
+.Pc
+All windows always have at least one current substring, called
+.Sy dot ","
+that is the default address.
+.Ss Simple addresses
+.Bl -tag -width Ds
+.It Sy #n
+The empty string after character
+.Sy n ";"
+.Li #0
+is the beginning of the file.
+.It Sy n
+Line
+.Sy n "."
+.It Li / Sy regexp Li /
+.It Li ? Sy regexp Li ?
+The substring that matches the regular expression, found by looking toward the end
+.Pq Li /
+or beginning
+.Pq Li \&?
+of the file. The search does not wrap around when hitting the end
+.Pq start
+of the file.
+.It Li 0
+The string before the first full line.
+This is not necessarily the null string; see
+.Li +
+and
+.Li -
+below.
+.It Li $
+The null string at the end of the file.
+.It Li "."
+Dot.
+.It Li "'m"
+The mark
+.Sy m
+in the file.
+.El
 .
+.Ss Compound addresses
+In the following,
+.Sy a1
+and
+.Sy a2
+are addresses.
+.Bl -tag -width Ds
+.It Sy a1+a2
+The address
+.Sy a2
+evaluated starting at the end of
+.Sy a1 "."
+.It Sy a1-a2
+The address
+.Sy a2
+evaluated looking the reverse direction starting at the beginning of
+.Sy a1 "."
+.It Sy "a1,a2"
+The substring from the beginning of
+.Sy a1
+to the end of
+.Sy a2 "."
+If
+.Sy a1
+is missing,
+.Li 0
+is substituted.
+If
+.Sy a2
+is missing,
+.Li $
+is substituted.
+.It Sy a1;a2
+Like
+.Dq Sy a1,a2
+but with
+.Sy a2
+evaluated at the end of, and dot set to,
+.Sy a1 "."
+.El
+.Pp
+The operators
+.Li +
+and
+.Li -
+are high precedence, while
+.Li ,
+and
+.Li ;
+are low precedence.
+.Pp
+In both
+.Li +
+and
+.Li -
+forms, if
+.Sy a2
+is a line or character address with a missing number, the number defaults to 1.
+If
+.Sy a1
+is missing,
+.Li "."
+is subtituted.
+If both
+.Sy a1
+and
+.Sy a2
+are present and distinguishable,
+.Li +
+may be elided.
+.Sy a2
+may be a regular expression; if it is delimited by
+.Dq Li \&?
+characters, the effect of the
+.Li +
+or
+.Li -
+is reversed.
+.
+The
+.Sy %
+sign is an alias for
+.Sy ","
+and hence
+.Sy 0,$ "."
+.
+It is an error for a compound address to represent a malformed substring.
+.
+.Ss Commands
+In the following, text demarcated by slashes represents text delimited by any printable ASCII character except alphanumerics.
+Any number of trailing delimiters may be elided, with multiple elisions then representing null strings, but the first delimiter must always be present.
+In any delimited text, newline may not appear literally;
+.Li \[rs]n
+and
+.Li \[rs]t
+may be typed for newline and tab;
+.Li \[rs]/
+quotes the delimiter, here
+.Li / "."
+Backslash is otherwise interpreted literally.
+.Pp
+Most commands may be prefixed with an address to indicate their range of operation.
+If a command takes an address and none is supplied, dot is used.
+The sole exception is the
+.Sy w
+command, which defaults to
+.Li "0,$" "."
+In the description,
+.Dq range
+is used to represent whatever address is supplied.
+Many commands set the value of dot as a side effect.
+If so, it is always to the
+.Dq result
+of the change: the empty string for a deletion, the new text for an insertion, etc.
+.Po
+but see the
+.Sy s
+and
+.Sy e
+commands
+.Pc "."
+.Ss Text commands
+.Bl -tag -width Ds
+.It Sy a/text/
+Insert the text into the file after the range.
+Set dot.
+.Pp
+May also be written as
+.Bd -literal -offset indent
+ a
+ lines
+ of
+ text
+ .
+.Ed
+.It Sy c \fR or Sy i
+Same as
+.Sy a ","
+but
+.Sy c
+replaces the text, while
+.Sy i
+inserts
+.Em before
+the range.
+.It Sy d
+Delete the text in range.
+Set dot.
+.It Sy s/regexp/text/
+Substitute
+.Sy text
+for the first match of the regular expression in the range.
+Currently implemented in terms of
+.Xr sed 1 "."
+.El
 .
-.Sh KEY BINDINGS
+.Ss I/O commands
+.Bl -tag -width Ds
+.It Sy "e[!] filename"
+Replace the file by the contents of the named external file.
+If no file name is given, reload file from disk.
+.It Sy "r filename"
+Replace the text in the range by the contents of the named external file.
+Set dot.
+.It Sy "w[!] filename"
+Write the range
+.Po
+default
+.Li 0,$
+.Pc
+to the named external file.
+.It Sy "wq[!] filename"
+Same as
+.Cm w ","
+but close file afterwards.
+.El
+.Pp
+If the file name argument is absent from any of these, the current file name is used.
+.Cm e
+always sets the file name,
+.Cm w
+will do so if the file has no name.
+Forcing the
+.Cm e
+command with
+.Sy !
+will discard any unsaved changes. Forcing
+.Cm w
+will overwrite the file on disk even if it has been externally modified since loading it.
+.Bl -tag -width Ds
+.It Sy "< shell-command"
+Replace the range by the standard output of the shell command.
+.It Sy "> shell-command"
+Sends the range to the standard input of the shell command.
+.It Sy "| shell-command"
+Send the range to the standard input, and replace it by the standard output, of the shell command.
+.It Sy "! shell-command"
+Run interactive shell command, redirect keyboard input to it.
+.It Sy "cd directory"
+Change working directory.
+If no directory is specified,
+.Ev "$HOME"
+is used.
+.El
+.Pp
+In any of
+.Sy "<" ","
+.Sy ">" ","
+.Sy "|" ","
+or
+.Sy "!" ","
+if the shell command is omitted, the last shell command
+.Pq "of any type"
+is substituted.
+.Ss Loops and conditionals
+.Bl -tag -width Ds
+.It Sy "x/regexp/ command"
+For each match of the regular expression in the range, run the command with dot set to the match.
+Set dot to the last match.
+If the regular expression and its slashes are omitted,
+.Li "/.*\[rs]n/"
+is assumed.
+Null string matches potentially occur before every character of the range and at the end of the range.
+.It Sy "y/regexp/ command"
+Like
+.Sy x ","
+but run the command for each substring that lies before, between, or after the matches that would be generated by
+.Sy x "."
+There is no default behavior.
+Null substrings potentially occur before every character in the range.
+.It Sy "X/regexp/ command"
+For each file whose file name matches the regular expression, make that the current file and run the command.
+If the expression is omitted, the command is run in every file.
+.It Sy "Y/regexp/ command"
+Same as
+.Sy X ","
+but for files that do not match the regular expression, and the expression is required.
+.It Sy "g/regexp/ command"
+.It Sy "v/regexp/ command"
+If the range contains
+.Po
+.Sy g
+.Pc
+or does not contain
+.Po
+.Sy v
+.Pc
+a match for the expression, set dot to the range and run the command.
+.El
+.Pp
+These may be nested arbitrarily deeply.
+An empty command in an
+.Sy x
+or
+.Sy y
+defaults to
+.Sy p "."
+.Cm X ","
+.Cm Y ","
+.Cm g
+and
+.Cm v
+do not have defaults.
+.
+.Ss Grouping and multiple changes
+Commands may be grouped by enclosing them in curly braces.
+Semantically, the opening brance is like a command: it takes an
+.Pq optional
+address and sets dot for each sub-command.
+Commands within the braces are executed sequentially, and changes made by one command are visible to other commands
+Braces may be nested arbitrarily.
+.
+.Sh VI(M) KEY BINDINGS
+.
+In the following sections angle brackets are used to denote special keys.
+The prefixes
+.Cm C- ,
+.Cm S- ,
+and
+.Cm M-
+are used to refer to the
+.Aq Ctrl ,
+.Aq Shift
+and
+.Aq Alt
+modifiers, respectively.
+.Pp
+All active key bindings can be listed at runtime using the
+.Cm :help
+command.
 .
 .Ss Operators
 .
+Operators perform a certain operation an a text range indicated by either a
+motion, a text object or an existing selection.
+.
 .Bl -tag
 .It c
-change
-.
+change, delete range and enter insert mode
 .It d
-delete
-.
+delete range
 .It !
-filter
-.
+filter range through external shell command
 .It =
 indent, currently an alias for gq
-.
 .It gq
-format using fmt(1)
-.
+format, filter range through
+.Xr fmt 1
 .It gu
 make lowercase
-.
 .It gU
 make uppercase
-.
 .It J
-join
-.
+join lines, insert spaces in between
+.It gJ
+join lines remove any delimiting white spaces
 .It p
-put
-.
+put, insert register content
 .It <
-shift-left
-.
+shift-left, decrease indent
 .It >
-shift-right
-.
+shift-right, increase indent
 .It ~
 swap case
-.
 .It y
-yank
+yank, copy range to register
 .El
 .
-.Ss Movements
+.Ss Motions
+.
+.\" TODO? more formal definition: pos -> [min(pos, f(pos)), max(pos, f(pos))]
+Motions take an initial file position and transform it to a destination file position,
+thereby defining a range.
 .
 .Bl -tag
 .It 0
@@ -175,10 +598,10 @@ next end of a word
 .It E
 next end of a WORD
 .
-.It F char
+.It F Aq char
 to next occurrence of char to the left
 .
-.It f char
+.It f Aq char
 to next occurrence of char to the right
 .
 .It ^
@@ -235,10 +658,10 @@ char right
 .It L
 goto bottom/last line of window
 .
-.It ` mark
+.It ` Aq mark
 go to mark
 .
-.It ' mark
+.It ' Aq mark
 go to start of line containing mark
 .
 .It %
@@ -301,17 +724,17 @@ search word under cursor backwards
 .It *
 search word under cursor forwards
 .
-.It T char
+.It T Aq char
 till before next occurrence of char to the left
 .
-.It t char
+.It t Aq char
 till before next occurrence of char to the right
 .
-.It ? text
-to next match of text in backward direction
+.It ? pattern
+to next match of pattern in backward direction
 .
-.It / text
-to next match of text in forward direction
+.It / pattern
+to next match of pattern in forward direction
 .
 .It w
 next start of a word
@@ -319,23 +742,19 @@ 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
+.\" TODO? more formal definition: text-object: pos -> [a, b]
+Text objects take an initial file position and transform it to a range
+where the former does not necessarily have to be contained in the latter.
 .
 All of the following text objects are implemented in an inner variant
 (prefixed with
-.Ql i`) and a normal variant (prefixed with
-.Ql a`):
+.Cm i ")"
+where the surrounding whitespace or delimiting characters are not part
+of the resulting range and a normal variant (prefixed with
+.Cm a ")"
+where they are.
 .Bl -tag
 .
 .It w
@@ -350,12 +769,11 @@ sentence
 .It p
 paragraph
 .
-.It [,], (,), {,}, <,>, ", ', `
+.It [,], (,), {,}, <,>, \&", ', `
 block enclosed by these symbols
 .El
 .Pp
-For sentence and paragraph there is no difference between the inner and
-normal variants.
+Further available text objects include:
 .Bl -tag
 .
 .It gn
@@ -363,11 +781,6 @@ 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
@@ -388,443 +801,322 @@ current line
 current line without leading and trailing white spaces
 .El
 .
-.Ss Multiple Cursors / Selections
+.Ss Multiple Cursors and 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).
+.Nm
+supports multiple cursors with immediate visual feedback. There always
+exists one primary cursor located within the current view port. Additional
+cursors can be created as needed. If more than one cursor exists,
+the primary one is styled differently.
 .Pp
 To manipulate multiple cursors use in normal mode:
 .Bl -tag
-.
-.It Ctrl-K
+.It Aq Cm C-k
 create count new cursors on the lines above
-.
-.It Ctrl-Meta-K
+.It Aq Cm C-M-k
 create count new cursors on the lines above the first cursor
-.
-.It Ctrl-J
+.It Aq Cm C-j
 create count new cursors on the lines below
-.
-.It Ctrl-Meta-J
+.It Aq Cm C-M-j
 create count new cursors on the lines below the last cursor
-.
-.It Ctrl-P
+.It Aq Cm C-p
 remove primary cursor
-.
-.It Ctrl-N
+.It Aq Cm C-n
 select word the cursor is currently over, switch to visual mode
-.
-.It Ctrl-U
+.It Aq Cm C-u
 make the count previous cursor primary
-.
-.It Ctrl-D
+.It Aq Cm C-d
 make the count next cursor primary
-.
-.It Ctrl-C
+.It Aq Cm C-c
 remove the count cursor column
-.
-.It Ctrl-L
+.It Aq Cm C-l
 remove all but the count cursor column
-.
-.It Tab
+.It Aq Cm Tab
 try to align all cursor on the same column
-.
-.It Esc
+.It Aq Cm Escape
 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
+.It Aq Cm Tab
 left align selections by inserting spaces
-.
-.It Shift-Tab
+.It Aq Cm S-Tab
 right align selections by inserting spaces
-.
-.It Ctrl-N
+.It Aq Cm C-n
 create new cursor and select next word matching current selection
-.
-.It Ctrl-X
+.It Aq Cm C-x
 clear (skip) current selection, but select next matching word
-.
-.It Ctrl-P
+.It Aq Cm C-p
 remove primary cursor
-.
-.It Ctrl-U/K
+.It Aq Cm C-u
+.It Aq Cm C-k
 make the count previous cursor primary
-.
-.It Ctrl-D/J
+.It Aq Cm C-d
+.It Aq Cm C-j
 make the count next cursor primary
-.
-.It Ctrl-C
+.It Aq Cm C-c
 remove the count cursor column
-.
-.It Ctrl-L
+.It Aq Cm C-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
+.It Aq Cm Escape
 clear all selections, switch to normal mode
 .El
 .Pp
-In insert/replace mode:
+In insert and replace mode:
 .Bl -tag
 .
-.It Shift-Tab
+.It Aq Cm S-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
+.Sh VI(M) COMMANDS
 .
-.It >
-end of the last selected visual area in current buffer
-.El
+.Pp
+Any unique prefix can be used to abbreviate a command.
 .
-.Ss Registers
+.Ss File and Window management
 .
-Supported registers include:
+A file must be opened in at least one window. If the last window displaying a
+certain file is closed all unsaved changes are discareded. Windows are equally
+sized and can be displayed in either horizontal or vertical fahsion.
 .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
+.It Cm :new
+open an empty window, arrange horizontally
+.It Cm :vnew
+open an empty window, arrange vertically
+.It Cm :open[!] Bq file name
+open a new window, displaying file name if given
+.It Cm :split Bq file name
+split window horizontally
+.It Cm :vsplit Bq file name
+split window vertically
+.It Cm :bdelete[!]
+close all windows which display the same file as the current one
+.It Cm :q[!]
+close currently focused window
+.It Cm :qall[!]
+close all windows, exit editor
 .El
 .Pp
-If no explicit register is specified a default register is used.
+Commands taking a file name will invoke the
+.Xr vis-open 1
+utility, if given a file pattern or directory.
 .
-.Sh COMMANDS
+.Ss Runtime key mappings
+.Nm
+supports global as well as window local run time key mappings which are
+always evaluated recursively.
 .
-.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
+.It Cm :map[!] <mode> <lhs> <rhs>
 add a global key mapping
-.Iq :map-window
+.It Cm :map-window[!] <mode> <lhs> <rhs>
 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
+.It Cm :unmap <mode> <lhs>
 remove a global key mapping
-.
-.It :unmap-window
+.It Cm :unmap-window <mode> <lhs>
 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
-.
-.Ss Runtime Configurable Key Bindings
-.
-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
-,
+In the above
+.Sy <mode>
+refers to 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.
+.Ql operator-pending ;
+.Sy <lhs>
+refers to the key to map and
+.Sy <rhs>
+is a key action or alias. An existing mapping may be overridden by forcing
+the map command by specifying
+.Sy ! .
+.Pp
+Because key mappings are always recursive, doing something like:
 .Pp
-Key mappings are always recursive, this means doing something like
+.\" TODO indent example
 .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
+.Pp
+will not work because it would enter an endless loop. Instead,
+.Nm
+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>
+for a list) editor functions.
 .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
+.Ss Keyboard Layout Specific Mappings
 .
-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.
+In order to facilate usage of non-latin keyboard layouts,
+.Nm
+allows to map locale specific keys to their latin equivalents by means of the
 .Pp
-For example, the following maps the movement keys in Russian layout:
-.Ic :langmap ролд hjkl
+.\" TODO indent example
+.Ic :langmap <locale-keys> <latin->keys>
 .Pp
-More generally the syntax of the `:langmap` command is:
-.Ic :langmap <keys in your layout> <equivalent keys in latin layout>
+command.
 .Pp
 If the key sequences have not the same length, the rest of the longer
 sequence will be discarded.
-.
-.Ss Runtime Configurable Key Bindings
-.
-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
-.
-Vis allows to set key equivalents for non-latin keyboard layouts. This
-facilitates editing non-latin texts. The defined mappings take effect
+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
 .
+.Ss Undo/Redo
 .Bl -tag
-.Ev VIS_PATH
-Override path to look for Lua support files as used for  syntax  highlighting.
-Defaults (in this order) to:
-.Bl -bullet
+.It Cm :earlier Bq count
+revert to older text state
+.It Cm :later Bq count
+revert to newer text state
+.El
 .
-.It
-The location of the vis binary
+If count is suffixed by either of
+.Sy d
+.Pq days ,
+.Sy h
+.Pq hours ,
+.Sy m
+.Pq minutes
+or
+.Sy s
+.Pq seconds
+it is interpreted as an offset from the current system time and the closest
+available text state is restored.
+.
+.Sh SET OPTIONS
+There are a small number of options that may be set
+.Pq or unset
+to change the editor's behavior using the
+.Cm :set
+command.
+This section describes the options, their abbreviations and their
+default values.
+.Pp
+In each entry below, the first part of the tag line is the full name
+of the option, followed by any equivalent abbreviations.
+The part in square brackets is the default value of the option.
+.Bl -tag -width Ds
+.It Cm shell Bq \&"/bin/sh\&"
+User shell to use for external commands, overrides
+.Cm $SHELL
+and shell field of password database
+.Cm /etc/passwd
+.It Cm escdelay Bq 50
+Milliseconds to wait before deciding whether an escape sequence should
+be treated as an
+.Aq Cm Escape
+key.
+.It Cm tabwidth , tw Bq 8
+Display width of a tab and number of spaces to use if
+.Cm expandtab
+is enabled.
+.It Cm autoindent , ai Bq off
+Automatically indent new lines by copying whitespace from previous line.
+.It Cm expandtab , et Bq off
+Whether
+.Aq Cm Tab
+should be expanded to
+.Cm tabwidth
+spaces.
+.It Cm number , nu Bq off
+Display absolute line numbers.
+.It Cm relativenumbers , rnu Bq off
+Display relative line numbers.
+.It Cm cursorline , cul Bq off
+Highlight line primary cursor resides on.
+.It Cm colorcolumn , cc Bq 0
+Highlight a fixed column.
+.It Cm horizon Bq 32768
+How many bytes back the lexer will look to synchronize parsing.
+.It Cm theme Bq \&"default-16\&" or \&"default-256\&"
+Color theme to use, name without file extension.
+.It Cm syntax Bq off
+Syntax highlighting lexer to use, name without file extension.
+.It Cm show-tabs Bq off
+Whether to display replacement symbol instead of tabs.
+.It Cm show-newlines Bq off
+Whether to display replacement symbol instead of newlines.
+.It Cm show-tabs Bq off
+Whether to display replacement symbol instead of newlines.
+.It Cm show-spaces Bq off
+Whether to display replacement symbol instead of blank cells.
+.El
 .
-.It
-.Pa $XDG_CONFIG_HOME/vis
-where
-.Ev $XDG_CONFIG_HOME
-refers to
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev VIS_PATH
+The default path to use to load Lua support files.
+.It Ev HOME
+The home directory used for the
+.Ic cd
+command if no argument is given.
+.It Ev TERM
+The terminal type to use to initialize the curses interface, defaults to
+.Sy xterm
+if unset.
+.It Ev SHELL
+The command shell to use for I/O related commands like
+.Cm ! ,
+.Cm > ,
+.Cm <
+and
+.Cm | .
+.It Ev XDG_CONFIG_HOME
+The configuration directory to use, defaults to
 .Pa $HOME/.config
-if unset
-.
-.It
-.Pa /usr/local/share/vis
-.
-.It
-.Pa /usr/share/vis
+if unset.
 .El
-.Ev VIS_THEME
-Override syntax highlighting theme to use.
+.
+.Sh ASYNCHRONOUS EVENTS
+.Bl -tag -width "SIGWINCH" -compact
+.It Dv SIGSTOP
+Suspend editor.
+.It Dv SIGCONT
+Resume editor.
+.It Dv SIGBUS
+An
+.Xr mmap 2
+ed file got truncated, unsaved file contents will be lost.
+.It Dv SIGHUP
+.It Dv SIGTERM
+Restore initial terminal state. Unsaved file contents will be lost.
+.Pp
+.It Dv SIGINT
+When an interrupt occurs while an external command is being run it is terminated.
+.Pp
+.It Dv SIGWINCH
+The screen is resized.
 .El
 .
 .Sh FILES
-.
 .Pp
-Settings and keymaps can be specified in a
+Upon startup
+.Nm
+will source the first
 .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:
+configuration file found from these locations:
 .Bl -bullet
-.
+.It
+.Pa $VIS_PATH
 .It
 The location of the
-.Nm vis
-binary
-.
+.Nm
+binary (on systems where
+.Pa /proc/self/exe
+is available).
 .It
 .Pa $XDG_CONFIG_HOME/vis
 where
@@ -835,30 +1127,66 @@ if unset.
 .
 .It
 .Pa /usr/local/share/vis
-.
-.It
+or
 .Pa /usr/share/vis
+depending on the build configuration.
 .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
 .
-.Sh SEE ALSO
+.Sh EXIT STATUS
+.Ex -std
 .
-.Xr vis-menu 1
+.Sh EXAMPLES
+Use
+.Nm
+as an interactive filter as used by
+.Xr dvtm 1 :
+.Pp
+.Ic $ { echo Pick your number; seq 1 10; } | vis - > choice
+.Pp
+Use the
 .Xr vis-open 1
-.Xr vis-clipboard 1
-.Xr vis-complete 1
+based file browser to list all C language source files:
+.Pp
+.Ic :e *.c
+.Pp
+.\" TODO add plumber example to start background process
+.\" :> { plumber <&3 3<&- & } 3<&0 1>&- 2>&-
+.Sh SEE ALSO
+.Xr vis-menu 1 ,
+.Xr vis-open 1 ,
+.Xr vis-clipboard 1 ,
+.Xr vis-complete 1 ,
+.Xr vi 1
+and
+.Xr sam 1
+.Pp
+.Dq The Text Editor sam
+by Rob Pike
+.Pp
+.Dq A Tutorial for the Sam Command Language
+by Rob Pike
+.Pp
+.Dq vi - screen-oriented (visual) display editor
+.St -p1003.1-2013
 .
-.Sh AUTHORS
+.Sh STANDARDS
+.Nm
+does not strive to be
+.St -p1003.1-2013
+compatible, but shares obvious similarities with the
+.Nm vi
+utility.
 .
-.Nm vis
+.\" .Sh HISTORY
+.\" TODO something about vi(m) and sam history
+.
+.Sh AUTHORS
+.Nm
 is written by
 .An Marc André Tanner Aq mat at brain-dump.org
+.
+.Sh BUGS
+On some systems there already exists a
+.Nm
+binary, thus causing a name conflict.