diff options
| -rw-r--r-- | vis.1 | 1288 |
1 files changed, 808 insertions, 480 deletions
@@ -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. |