diff options
Diffstat (limited to 'man/vis.1')
| -rw-r--r-- | man/vis.1 | 1259 |
1 files changed, 1259 insertions, 0 deletions
diff --git a/man/vis.1 b/man/vis.1 new file mode 100644 index 0000000..1b8652c --- /dev/null +++ b/man/vis.1 @@ -0,0 +1,1259 @@ +.Dd December 5, 2016 +.Dt VIS 1 +.Os Vis VERSION +. +.Sh NAME +.Nm vis +.Nd a highly efficient text editor +. +.Sh SYNOPSIS +.Nm +.Op Fl v +.Op Ic +command +.Op 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 . +. +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 -width indent +.It Fl v +Print version information and exit. +. +.It Sy +command +Execute command after loading file. +. +.It Fl - +Denotes the end of the options. Arguments after this will be handled as a +file name. +.\" TODO mention +command +.El +.Pp +The special file +.Cm - +instructs +.Nm +to read from standard input in which case +.Ic :wq +will write to standard output, thereby enabling usage as an interactive filter. +.Pp +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 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 +The visual block and ex modes are deliberately not implemented, +instead +.Nm +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 +.Ic u +(undo) and +.Aq Ic C-r +(redo) commands can be used to traverse the tree along the main branch. +Additionally +.Ic g+ +and +.Ic g- +traverse the history in chronological order. Furthermore the +.Ic :earlier +and +.Ic :later +commands provide means to restore the text to an arbitrary state. +. +.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 -width indent +.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. +. +.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 -width indent +.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 +.Cm \(dqa-\(dqz +can be used to record macros. Use +one of +.Cm \(dqA-\(dqZ +to append to an existing macro. +.Ic q +starts a recording, +.Ic @ +plays it back. +.Ic @@ +refers to the least recently recorded macro. +.Ic @: +repeats the last :-command. +.Ic @/ +is equivalent to +.Ic n +in normal mode. +. +.Ss Jump list and Change list +. +A per window, fixed sized file local jump list (navigate with +.Aq Ic C-O +and +.Aq Ic C-I ) +and change list (navigate with +.Ic g; +and +.Ic g, ) +is supported. +. +.Ss Encoding, Tab and Newline handling +. +.Nm +always assumes the input file to be UTF-8 encoded. If you wish to edit +files with legacy encodings, use +.Xr iconv 1 +to convert them as needed. +.Aq Tab +can optionally be expanded to a configurable number of spaces (see +.Sx "SET OPTIONS" ) . +The first line ending in the file determines what will be inserted when pressing +.Aq Enter +(defaults to \\n). +. +.Ss Mouse support +The mouse is currently not used at all. +. +.Sh SAM COMMANDS +. +.Nm +supports an interactive variant of the structural regular expression based command language introduced by +.Xr sam 1 . +. +.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 +.Cm "." +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?" . +.Pp +All windows always have at least one current substring which +is the default address. In sam this is referred to as +.Sy dot . +In +.Nm +multiple +.Dq dots +can exist at the same time. +In normal mode each cursor induces such a range, representing the +character it is currently over. Similarly, in visual mode each +selection serves as a default address. +.Ss Simple addresses +.Bl -tag -width indent +.It Ic #n +The empty string after character +.Sy n ; +.Li #0 +is the beginning of the file. +.It Ic n +Line +.Sy n . +.It Ic /regexp/ +.It Ic ?regexp? +The substring that matches the regular expression, found by looking +towards 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 Ic 0 +The string before the first full line. +This is not necessarily the null string; see +.Li + +and +.Li - +below. +.It Ic $ +The null string at the end of the file. +.It Ic "." +Dot, the current range. +.It Ic "'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 indent +.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 range 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 substituted. +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 +.Li % +sign is an alias for +.Li "," +and hence +.Li 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, a +default address is used. In normal mode this equates to the character +the cursor is currently over. If only one cursor exists +.Ic x +and +.Ic y +default to the whole file +.Li "0,$" . +In normal mode the write commands +.Ic w +and +.Ic wq +always apply to the whole file. +Commands are executed once for every cursor. +In visual mode the commands are applied to every selection +as if an implicit +.Ic x +command, matching the existing selections, was present. +. +.Pp +In the description, +.Dq range +is used to represent whatever address is supplied. +.Pp +If after a successful command execution no selections remain, +the editor will switch to normal mode, otherwise it remains in +visual mode. This allows +.Em interactive +refinements of ranges. +. +.\" 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 indent +.It Ic 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 Ic c \fR or 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 +. +.Ss Display commands +.Bl -tag -width Ds +.It Ic p +Create a new selection for the range. If empty, create a new cursor. +.El +. +.Ss I/O commands +.Bl -tag -width indent +.It Ic e[!] Bq file name +Replace the file by the contents of the named external file. +If no file name is given, reload file from disk. +.It Ic r file name +Replace the text in the range by the contents of the named external file. +.\" Set dot. +.It Ic w[!] Bq file name +Write the range +.Po +default +.Li 0,$ +.Pc +to the named external file. +.It Ic wq[!] Bq file name +Same as +.Ic w , +but close file afterwards. +.El +.Pp +If the file name argument is absent from any of these, the current file name is used. +.Ic e +always sets the file name, +.Ic w +will do so if the file has no name. +Forcing the +.Ic e +command with +.Cm "!" +will discard any unsaved changes. Forcing +.Ic w +will overwrite the file on disk even if it has been externally modified +since loading it. Write commands with a non-default addresses and no +file name are destructive and need always to be forced. +.Bl -tag -width indent +.It Ic "< shell-command" +Replace the range by the standard output of the shell command. +.It Ic "> shell-command" +Sends the range to the standard input of the shell command. +.It Ic "| shell-command" +Send the range to the standard input, and replace it by the standard output, of the shell command. +.It Ic "! shell-command" +Run interactive shell command, redirect keyboard input to it. +.It Ic "cd directory" +Change working directory. +If no directory is specified, +.Ev "$HOME" +is used. +.El +.Pp +In any of +.Ic "<" , +.Ic ">" , +.Ic "|" , +or +.Ic "!" , +if the shell command is omitted, the last shell command +.Pq "of any type" +is substituted. +.Ss Loops and conditionals +.Bl -tag -width indent +.It Ic x/regexp/ Bq command +For each match of the regular expression in the range, run the command with range set to the 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 Ic y/regexp/ Bq command +Like +.Ic x , +but run the command for each substring that lies before, between, or after the matches that would be generated by +.Ic x . +There is no default behavior. +Null substrings potentially occur before every character in the range. +.It Ic "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 Ic "Y/regexp/ command" +Same as +.Ic X , +but for files that do not match the regular expression, and the expression is required. +.It Ic "g/regexp/ command" +.It Ic "v/regexp/ command" +If the range contains +.Po +.Ic g +.Pc +or does not contain +.Po +.Ic v +.Pc +a match for the expression, run command on the range. +.El +.Pp +These may be nested arbitrarily deeply. +An empty command in an +.Ic x +or +.Ic y +defaults to +.Ic p . +.Ic X , +.Ic Y , +.Ic g +and +.Ic v +do not have defaults. +. +.Ss Grouping and multiple changes +Commands may be grouped by enclosing them in curly braces. +Semantically, the opening brace is like a command: it takes an +.Pq optional +address and runs each sub-command on the range. +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 -width indent +.It c +change, delete range and enter insert mode +.It d +delete range +.It ! +filter range through external shell command +.It = +indent, currently an alias for gq +.It gq +format, filter range through +.Xr fmt 1 +.It gu +make lowercase +.It gU +make uppercase +.It J +join lines, insert spaces in between +.It gJ +join lines remove any delimiting white spaces +.It p +put, insert register content +.It < +shift-left, decrease indent +.It > +shift-right, increase indent +.It ~ +swap case +.It y +yank, copy range to register +.El +.Pp +Operators can be forced to work line wise by specifying +.Cm V . +. +.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. +.\" TODO define word/WORD +. +.Bl -tag -width indent +.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 Aq char +to next occurrence of char to the left +. +.It f Aq 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 ` Aq mark +go to mark +. +.It ' Aq 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 Aq char +till before next occurrence of char to the left +. +.It t Aq char +till before next occurrence of char to the right +. +.It ? pattern +to next match of pattern in backward direction +. +.It / pattern +to next match of pattern in forward direction +. +.It w +next start of a word +. +.It W +next start of a WORD +.El +. +.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 +.Cm i ")" +where the surrounding white space or delimiting characters are not part +of the resulting range and a normal variant (prefixed with +.Cm a ")" +where they are. +.Bl -tag -width indent +. +.It w +word +. +.It W +WORD +. +.It s +sentence +. +.It p +paragraph +. +.It [,], (,), {,}, <,>, \&", ', ` +block enclosed by these symbols +.El +.Pp +Further available text objects include: +.Bl -tag -width indent +. +.It gn +matches the last used search term in forward direction +. +.It gN +matches the last used search term in backward direction +. +.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 and Selections +. +.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 -width indent +.It Aq C-k +create count new cursors on the lines above +.It Aq C-M-k +create count new cursors on the lines above the first cursor +.It Aq C-j +create count new cursors on the lines below +.It Aq C-M-j +create count new cursors on the lines below the last cursor +.It Aq C-p +remove primary cursor +.It Aq C-n +select word the cursor is currently over, switch to visual mode +.It Aq C-u +make the count previous cursor primary +.It Aq C-d +make the count next cursor primary +.It Aq C-c +remove the count cursor column +.It Aq C-l +remove all but the count cursor column +.It Aq Tab +try to align all cursor on the same column +.It Aq Escape +dispose all but the primary cursor +.El +.Pp +The visual modes were enhanced to recognize: +.Bl -tag -width indent +.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 Aq Tab +left align selections by inserting spaces +.It Aq S-Tab +right align selections by inserting spaces +.It Aq C-n +create new cursor and select next word matching current selection +.It Aq C-x +clear (skip) current selection, but select next matching word +.It Aq C-p +remove primary cursor +.It Aq C-u +.It Aq C-k +make the count previous cursor primary +.It Aq C-d +.It Aq C-j +make the count next cursor primary +.It Aq C-c +remove the count cursor column +.It Aq 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 Aq Escape +clear all selections, switch to normal mode +.El +.Pp +In insert and replace mode: +.Bl -tag -width indent +. +.It Aq S-Tab +align all cursors by inserting spaces +.El +. +.Sh VI(M) COMMANDS +. +Any unique prefix can be used to abbreviate a command. +. +.Ss File and Window management +. +A file must be opened in at least one window. If the last window displaying a +certain file is closed all unsaved changes are discarded. Windows are equally +sized and can be displayed in either horizontal or vertical fashion. +.Bl -tag -width indent +.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 +Commands taking a file name will invoke the +.Xr vis-open 1 +utility, if given a file pattern or directory. +. +.Ss Runtime key mappings +.Nm +supports global as well as window local run time key mappings which are +always evaluated recursively. +. +.Bl -tag -width indent +.It Cm :map[!] <mode> <lhs> <rhs> +add a global key mapping +.It Cm :map-window[!] <mode> <lhs> <rhs> +add a window local key mapping +.It Cm :unmap <mode> <lhs> +remove a global key mapping +.It Cm :unmap-window <mode> <lhs> +remove a window local key mapping +.El +In the above +.Cm <mode> +refers to one of +.Ql normal , +.Ql insert , +.Ql replace , +.Ql visual , +.Ql visual-line +or +.Ql operator-pending ; +.Cm <lhs> +refers to the key to map and +.Cm <rhs> +is a key action or alias. An existing mapping may be overridden by forcing +the map command by specifying +.Cm "!" . +.Pp +Because key mappings are always recursive, doing something like: +.Pp +.Dl :map! normal j 2j +.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 editor functions. +.Ic :help +lists all currently active key bindings as well as all available symbolic +keys. +. +.Ss Keyboard Layout Specific Mappings +. +In order to facilitate usage of non-latin keyboard layouts, +.Nm +allows to map locale specific keys to their latin equivalents by means of the +.Pp +.Dl :langmap <locale-keys> <latin->keys> +.Pp +command. As an example, the following maps the movement keys in Russian layout: +.Pp +.Dl :langmap ролд hjkl +.Pp +If the key sequences have not the same length, the remainder of the longer +sequence will be discarded. +.Pp +The defined mappings take effect +in all non-input modes, i.e. everywhere except in insert and replace mode. +. +.Ss Undo/Redo +.Bl -tag -width indent +.It Ic :earlier Bq count +revert to older text state +.It Ic :later Bq count +revert to newer text state +.El +.Pp +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 indent +.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 white space 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 +. +.Sh CONFIGURATION +. +.Nm +uses Lua for configuration and scripting purposes. +During startup +.Pa visrc.lua +(see the +.Sx FILES +section) is sourced which can be used to set personal configuration +options. As an example the following will enable the display of line +numbers: +.Pp +.Dl vis:command('set number') +. +.Sh ENVIRONMENT +.Bl -tag -width indent +.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 +.Ic "!" , +.Ic ">" , +.Ic "<" +and +.Ic "|" . +.It Ev XDG_CONFIG_HOME +The configuration directory to use, defaults to +.Pa $HOME/.config +if unset. +.El +. +.Sh ASYNCHRONOUS EVENTS +.Bl -tag -width indent +.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. +.It Dv SIGINT +When an interrupt occurs while an external command is being run it is terminated. +.It Dv SIGWINCH +The screen is resized. +.El +. +.Sh FILES +Upon startup +.Nm +will source the first +.Pa visrc.lua +configuration file found from these locations: +.Bl -bullet +.It +.Pa $VIS_PATH +.It +The location of the +.Nm +binary (on systems where +.Pa /proc/self/exe +is available). +.It +.Pa $XDG_CONFIG_HOME/vis +where +.Pa $XDG_CONFIG_HOME +refers to +.Pa $HOME/.config +if unset. +. +.It +.Pa /usr/local/share/vis +or +.Pa /usr/share/vis +depending on the build configuration. +.El +. +.Sh EXIT STATUS +.Ex -std +. +.Sh EXAMPLES +Use +.Nm +as an interactive filter as used by +.Xr dvtm 1 : +.Pp +.Dl $ { echo Pick your number; seq 1 10; } | vis - > choice +.Pp +Use the +.Xr vis-open 1 +based file browser to list all C language source files: +.Pp +.Dl :e *.c +.Pp +Spawn background process and pipe range to its standard input: +.Pp +.Dl :> { plumber <&3 3<&- & } 3<&0 1>&- 2>&- +.Sh SEE ALSO +.Xr vis-clipboard 1 , +.Xr vis-complete 1 , +.Xr vis-menu 1 , +.Xr vis-open 1 , +.Xr vi 1 +and +.Xr sam 1 +.Pp +.Lk http://doc.cat-v.org/bell_labs/sam_lang_tutorial/sam_tut.pdf "A Tutorial for the Sam Command Language" +by Rob Pike +.Pp +.Lk http://doc.cat-v.org/plan_9/4th_edition/papers/sam/ "The Text Editor sam" +by Rob Pike +.Pp +.Lk http://man.cat-v.org/plan_9/1/sam "Plan9 manual page for sam(1)" +.Pp +.Lk http://doc.cat-v.org/bell_labs/structural_regexps/se.pdf "Structural Regular Expressions" +by Rob Pike +.Pp +.Lk http://pubs.opengroup.org/onlinepubs/9699919799/utilities/vi.html "vi - screen-oriented (visual) display editor" +.St -p1003.1-2013 +. +.Sh STANDARDS +.Nm +does not strive to be +.St -p1003.1-2013 +compatible, but shares obvious similarities with the +.Nm vi +utility. +. +.\" .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. |