From 481ccff4d20b539d5d2ae80e527fd54233e83991 Mon Sep 17 00:00:00 2001 From: josuah Date: Thu, 6 Oct 2016 03:12:26 -0400 Subject: Pulled content from the README into the man page --- vis.1 | 745 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 704 insertions(+), 41 deletions(-) diff --git a/vis.1 b/vis.1 index b655921..db8a312 100644 --- a/vis.1 +++ b/vis.1 @@ -1,49 +1,712 @@ -.TH VIS 1 vis\-VERSION -.nh -.SH NAME -vis - a vim like text editor -.SH SYNOPSIS -.B vis -.RI [ +command ...] -.RI [ files ...|-] -.br -.SH DESCRIPTION -.B vis +.Dd $Mdocdate: September 10 2016 $ +.Dt VIS 1 +.Os +.Sh NAME +.\" +.Nm vis +.Nd a vim like text editor +.\" +.\" +.Sh SYNOPSIS +.\" +.Nm vis +.Op Ic +command +.Op Ar files Fl +.\" +.\" +.Sh DESCRIPTION +.\" +.Nm vis is a highly efficient vim like text editor. -.SH OPTIONS -.B \-v +.\" +.Bl -tag +.It Fl v Print version information and exit. - -.B \-\- -Denotes the end of the options. Arguments after this will be handled as a file name. -.SH ENVIRONMENT VARIABLES -.TP -.B VIS_PATH -Override path to look for Lua support files as used for syntax highlighting. +.It Fl - +Denotes the end of the options. Arguments after this will be handled as a +file name. +.El +.\" +.\" +.Ss Modes +.\" +Vis implements more or less functional normal, operator-pending, insert, +replace and visual (in both line and character wise variants) modes. +.Pp +Visual block mode is not implemented and there exists no immediate plan +to do so. Instead vis has built in support for multiple cursors. +.Pp +Command mode is implemented as a regular file. Use the full power of +the editor to edit your commands / search terms. +.Pp +Ex mode is deliberately not implemented, instead a variant of the +structural regular expression based command language of `sam(1)` +is supported. +.\" +.\" +.Ss Undo/Redo and Repeat +.\" +.Pp +The text is currently snapshotted whenever an operator is completed as +well as when insert or replace mode is left. Additionally a snapshot is +also taken if in insert or replace mode a certain idle time elapses. +.\" +.Pp +Another idea is to snapshot based on the distance between two consecutive +editing operations (as they are likely unrelated and thus should be +individually reversible). +.\" +.Pp +Besides the regular undo functionality, the key bindings +.Ql g+ +and +.Ql g- +traverse the history in chronological order. Further more the +.Iq :earlier +and +.Iq :later +commands provide means to restore the text to an arbitrary +state. +.\" +.Pp +The repeat command +.Ql \&. +works for all operators and is able to repeat +the last insertion or replacement. +.\" +.\" +.Ss Tab <-> Space conversion and Line endings \n vs \r\n +.\" +.Pp +Tabs can optionally be expanded to a configurable number of spaces. +The first line ending in the file determines what will be inserted upon +a line break (defaults to \n). +.\" +.\" +.Ss Jump list and change list +.\" +.Pp +A per window, file local jump list (navigate with `CTRL+O` and `CTRL+I`) +and change list (navigate with `g;` and `g,`) is supported. The jump +list is implemented as a fixed sized ring buffer. +.\" +.\" +.Ss Macros +.\" +The general purpose registers +.Ql [a-z] +can be used to record macros. Use +one of +.Ql [A-Z] +to append to an existing macro. +.Ql q +starts a recording, +.Ql @ +plays it back. +.Ql @@ +refers to the least recently recorded macro. +.Ql @: +repeats the last :-command. +.Ql @/ +is equivalent to +.Ql n +in normal mode. +.\" +.\" +.Ss Structural Regular Expression based Command Language +.\" +.Nm vis +supports +.Xr sam 1 +structural regular expression based command language. +.\" +.\" +.Ss Mouse support +.\" +.Pp +The mouse is currently not used at all. +.\" +.\" +.Ss Operators +.\" +.Bl -tag +.It c +change +.It d +delete +.It ! +filter +.It = +indent, currently an alias for gq +.It gq +format using fmt(1) +.It gu +make lowercase +.It gU +make uppercase +.It J +join +.It p +put +.It < +shift-left +.It > +shift-right +.It ~ +swap case +.It y +yank +.El +.\" +.\" +.Ss Movements +.\" +.Bl -tag +.It 0 +start of line +.It b +previous start of a word +.It B +previous start of a WORD +.It $ +end of line +.It e +next end of a word +.It E +next end of a WORD +.It F char +to next occurrence of char to the left +.It f char +to next occurrence of char to the right +.It ^ +first non-blank of line +.It g0 +begin of display line +.It g$ +end of display line +.It ge +previous end of a word +.It gE +previous end of a WORD +.It gg +begin of file +.It G +goto line or end of file +.It gj +display line down +.It gk +display line up +.It g_ +last non-blank of line +.It gm +middle of display line +.It | +goto column +.It h +char left +.It H +goto top/home line of window +.It j +line down +.It k +line up +.It l +char right +.It L +goto bottom/last line of window +.It ` mark +go to mark +.It ' mark +go to start of line containing mark +.It % +match bracket +.It M +goto middle line of window +.It ]] +next end of C-like function +.It } +next paragraph +.It ) +next sentence +.It ][ +next start of C-like function +.It N +repeat last search backwards +.It n +repeat last search forward +.It [] +previous end of C-like function +.It [{ +previous start of block +.It ]} +next start of block +.It [( +previous start of parenthese pair +.It ]) +next start of parenthese pair +.It { +previous paragraph +.It ( +previous sentence +.It [[ +previous start of C-like function +.It ; +repeat last to/till movement +.It , +repeat last to/till movement but in opposite direction +.It # +search word under cursor backwards +.It * +search word under cursor forwards +.It T char +till before next occurrence of char to the left +.It t char +till before next occurrence of char to the right +.It ? text +to next match of text in backward direction +.It / text +to next match of text in forward direction +.It w +next start of a word +.It W +next start of a WORD +.El +.\" +.Pp +An empty line is currently neither a word nor a WORD. +.Pp +Some of these commands do not work as in vim when prefixed with a +digit i.e. a multiplier. As an example in vim +.Ql 3$ +moves to the end +of the 3rd line down. However vis treats it as a move to the end of +current line which is repeated 3 times where the last two have no +effect. +.\" +.\" +.Ss Text objects +.\" +.Pp +All of the following text objects are implemented in an inner variant +(prefixed with +.Ql i`) and a normal variant (prefixed with +.Ql a`): +.\" +.Bl -tag +.It w +word +.It W +WORD +.It s +sentence +.It p +paragraph +.It [,], (,), {,}, <,>, ", ', ` +block enclosed by these symbols +.El +.\" +.Pp +For sentence and paragraph there is no difference between the inner and +normal variants. +.\" +.Bl -tag +.It gn +matches the last used search term in forward direction +.It gN +matches the last used search term in backward direction +.El +.\" +.Pp +Additionally the following text objects, which are not part of stock +vim are also supported: +.Bl -tag +.It ae +entire file content +.It ie +entire file content except for leading and trailing empty lines +.It af +C-like function definition including immediately preceding comments +.It if +C-like function definition only function body +.It al +current line +.It il +current line without leading and trailing white spaces +.El +.\" +.\" +.Ss Multiple Cursors / Selections +.\" +.Nm vis +supports multiple cursors with immediate visual feedback (unlike in the +visual block mode of vim where for example inserts only become visible +upon exit). There always exists one primary cursor located within the +current view port. Additional cursors ones can be created as needed. If +more than one cursor exists, the primary one is styled differently +(yellow by default). +.Pp +To manipulate multiple cursors use in normal mode: +.\" +.Bl -tag +.It Ctrl-K +create count new cursors on the lines above +.It Ctrl-Meta-K +create count new cursors on the lines above the first cursor +.It Ctrl-J +create count new cursors on the lines below +.It Ctrl-Meta-J +create count new cursors on the lines below the last cursor +.It Ctrl-P +remove primary cursor +.It Ctrl-N +select word the cursor is currently over, switch to visual mode +.It Ctrl-U +make the count previous cursor primary +.It Ctrl-D +make the count next cursor primary +.It Ctrl-C +remove the count cursor column +.It Ctrl-L +remove all but the count cursor column +.It Tab +try to align all cursor on the same column +.It Esc +dispose all but the primary cursor +.El +.\" +.Pp +Visual mode was enhanced to recognize: +.\" +.Bl -tag +.It I +create a cursor at the start of every selected line +.It A +create a cursor at the end of every selected line +.It Tab +left align selections by inserting spaces +.It Shift-Tab +right align selections by inserting spaces +.It Ctrl-N +create new cursor and select next word matching current selection +.It Ctrl-X +clear (skip) current selection, but select next matching word +.It Ctrl-P +remove primary cursor +.It Ctrl-U/K +make the count previous cursor primary +.It Ctrl-D/J +make the count next cursor primary +.It Ctrl-C +remove the count cursor column +.It Ctrl-L +remove all but the count cursor column +.It + +rotates selections rightwards count times +.It - +rotates selections leftwards count times +.It \e +trim selections, remove leading and trailing white space +.It Esc +clear all selections, switch to normal mode +.El +.\" +.Pp +In insert/replace mode: +.\" +.Bl -tag +.It Shift-Tab +align all cursors by inserting spaces +.El +.\" +.\" +.Ss Marks +.\" +.Bl -tag +.It [a-z] +general purpose marks +.It < +start of the last selected visual area in current buffer +.It > +end of the last selected visual area in current buffer +.El +.\" +.\" +.Ss Registers +.\" +.Pp +Supported registers include: +.\" +.Bl -tag +.It "a-"z +general purpose registers +.It "A-"Z +append to corresponding general purpose register +.It "*, +"+ system clipboard integration via shell script vis-clipboard +.It "0 +yank register +.It "/ +search register +.It ": +command register +.It "_ +black hole (/dev/null) register +.El +.\" +.Pp +If no explicit register is specified a default register is used. +.\" +.\" +.Sh COMMANDS +.\" +.Pp +Besides the sam command language the following commands are also recognized at the `:`-command prompt. Any unique prefix can be used. +.\" +.Bl -tag +.Iq :bdelete +close all windows which display the same file as the current one +.Iq :earlier +revert to older text state +.Iq :e +replace current file with a new one or reload it from disk +.Iq :langmap +set key equivalents for layout specific key mappings +.Iq :later +revert to newer text state +.Iq :! +launch external command, redirect keyboard input to it +.Iq :map +add a global key mapping +.Iq :map-window +add a window local key mapping +.Iq :new +open an empty window, arrange horizontally +.Iq :open +open a new window +.Iq :qall +close all windows, exit editor +.Iq :q +close currently focused window +.It :r +insert content of another file at current cursor position +.It :set +set the options below +.It :split +split window horizontally +.It :s +search and replace currently implemented in terms of `sed(1)` +.It :unmap +remove a global key mapping +.It :unmap-window +remove a window local key mapping +.It :vnew +open an empty window, arrange vertically +.It :vsplit +split window vertically +.It :wq +write changes then close window +.It :w +write current buffer content to file +.It tabwidth [1-8] default 8 +set display width of a tab and number of spaces to use if expandtab is enabled +.It expandtab (yes|no) default no +whether typed in tabs should be expanded to tabwidth spaces +.It autoindent (yes|no) default no +replicate spaces and tabs at the beginning of the line when +.It number (yes|no) default no +.It relativenumber (yes|no) default no +whether absolute or relative line numbers are printed alongside +.It syntax name default yes +use syntax definition given (e.g. "c") or disable syntax +.It show +show/hide special white space replacement symbols +.Bl -bullet +.It +newlines = [0|1] default 0 +.It +tabs = [0|1] default 0 +.It +spaces = [0|1] default 0 +.El +.It cursorline (yes|no) default no +highlight the line on which the cursor currently resides +.It colorcolumn number default 0 +highlight the given column +.It horizon number default 32768 (32K) +how far back the lexer will look to synchronize parsing +.It theme name default dark-16.lua | solarized.lua (16 | 256 color) +use the given theme / color scheme for syntax highlighting +.El +.\" +.Pp +Commands taking a file name will use a simple file open dialog based on +the included `vis-open` shell script and `vis-menu` utility, if given +a file pattern or directory. +.\" +.Ic :e *.c +opens a menu with all C files +.Ic :e \&. +opens a menu with all files of the current directory +.\" +.\" +.Sh ENVIRONMENT +.\" +.Bl -tag +.Ev VIS_PATH +Override path to look for Lua support files as used for syntax highlighting. Defaults (in this order) to: -.RS -.RS -.TP +.Bl -bullet +.It The location of the vis binary -.TP -.B $XDG_CONFIG_HOME/vis +.It +.Pa $XDG_CONFIG_HOME/vis where -.B $XDG_CONFIG_HOME +.Ev $XDG_CONFIG_HOME refers to -.B $HOME/.config +.Pa $HOME/.config if unset -.TP -.B /usr/local/share/vis -.TP -.B /usr/share/vis -.RE -.RE -.TP -.B VIS_THEME +.It +.Pa /usr/local/share/vis +.It +.Pa /usr/share/vis +.El +.Ev VIS_THEME Override syntax highlighting theme to use. -.SH HELP -Type -.B :help -to get a list of currently active key bindings and their respective meaning. -.SH AUTHOR -vis is written by Marc André Tanner +.El +.\" +.\" +.Sh FILES +.\" +.Pp +Settings and keymaps can be specified in a +.Pa visrc.lua +file, which will +be read by +.Pa vis +at runtime. An example +.Pa visrc.lua +file is installed in +.Pa /usr/local/share/vis +by default. This file can be copied to +.Pa $XDG_CONFIG_HOME/vis +(which defaults to +.Pa $HOME/.config/vis +) for further configuration. +.Pp +The environment variable +.Pa VIS_PATH +can be set to override the path that +.Pa vis +will look for Lua support files as used for syntax highlighting. +.Pa VIS_PATH +defaults (in this order) to: +.\" +.Bl -bullet +.It +The location of the +.Nm vis +binary +.It +.Pa $XDG_CONFIG_HOME/vis`, where +.Pa $XDG_CONFIG_HOME +refers to +`$HOME/.config +if unset +.It +.Pa /usr/local/share/vis` +.It +.Pa /usr/share/vis` +.El +.\" +.Pp +The environment variable +.Ev VIS_THEME +can be set to specify the theme used by +.Nm vis +: +.\" +.Bd -literal +VIS_THEME=/path/to/your/theme.lua +export VIS_THEME +.Ed +.\" +.\" +.Ss Runtime Configurable Key Bindings +.\" +.Pp +Vis supports run time key bindings via the +.Ic :{un,}map{,-window} +set of commands. The basic syntax is +.Ic :map +where mode is one of +.Ql normal +, +.Ql insert +, +.Ql replace +, +.Ql visual +, +.Ql visual-line +or +.Ql operator-pending +. +.Ql lhs +refers to the key to map, +.Ql rhs +is a key action or alias. An existing mapping can be overridden by appending +.Ql ! +to the map command. +.\" +.Pp +Key mappings are always recursive, this means doing something like +.Ic :map! normal j 2j +will not work because it will enter an endless loop. Instead vis uses +pseudo keys referred to as key actions which can be used to invoke a set +of available (see +.Ic :help +or +.Ql F1 +for a list) editor functions. Hence the correct thing to do would be +.Ic :map! normal j 2 +.\" +.Pp +Unmapping works as follows: +.Pp :unmap +.Pp +The commands suffixed with `-window` only affect the currently active window. +.\" +.\" +.Ss Layout Specific Key Bindings +.\" +.Pp +Vis allows to set key equivalents for non-latin keyboard layouts. This +facilitates editing non-latin texts. The defined mappings take effect +in all non-input modes, i.e. everywhere except in insert and replace mode. +.\" +.Pp +For example, the following maps the movement keys in Russian layout: +.Ic :langmap ролд hjkl +.\" +.Pp +More generally the syntax of the `:langmap` command is: +.Ic :langmap +.\" +.Pp +If the key sequences have not the same length, the rest of the longer +sequence will be discarded. +.\" +.\" +.Sh SEE ALSO +.\" +.Xr vis-menu 1 +.Xr vis-open 1 +.Xr vis-clipboard 1 +.Xr vis-complete 1 +.\" +.\" +.Sh AUTHORS +.\" +.Nm vis +is written by +.An Marc André Tanner Aq mat at brain-dump.org -- cgit v1.2.3 From 46e6e731716a7917f109b1d2d0b2cd44c3cc5e20 Mon Sep 17 00:00:00 2001 From: josuah Date: Sat, 15 Oct 2016 19:15:16 -0400 Subject: Manual: Cleanup, and real "KEY BINDINGS" section --- vis.1 | 274 +++++++++++++++++++++++++++++------------------------------------- 1 file changed, 119 insertions(+), 155 deletions(-) diff --git a/vis.1 b/vis.1 index db8a312..3ec5eef 100644 --- a/vis.1 +++ b/vis.1 @@ -2,23 +2,15 @@ .Dt VIS 1 .Os .Sh NAME -.\" .Nm vis .Nd a vim like text editor -.\" -.\" .Sh SYNOPSIS -.\" .Nm vis .Op Ic +command .Op Ar files Fl -.\" -.\" .Sh DESCRIPTION -.\" .Nm vis is a highly efficient vim like text editor. -.\" .Bl -tag .It Fl v Print version information and exit. @@ -26,10 +18,7 @@ Print version information and exit. Denotes the end of the options. Arguments after this will be handled as a file name. .El -.\" -.\" .Ss Modes -.\" Vis implements more or less functional normal, operator-pending, insert, replace and visual (in both line and character wise variants) modes. .Pp @@ -42,20 +31,15 @@ the editor to edit your commands / search terms. Ex mode is deliberately not implemented, instead a variant of the structural regular expression based command language of `sam(1)` is supported. -.\" -.\" .Ss Undo/Redo and Repeat -.\" .Pp The text is currently snapshotted whenever an operator is completed as well as when insert or replace mode is left. Additionally a snapshot is also taken if in insert or replace mode a certain idle time elapses. -.\" .Pp Another idea is to snapshot based on the distance between two consecutive editing operations (as they are likely unrelated and thus should be individually reversible). -.\" .Pp Besides the regular undo functionality, the key bindings .Ql g+ @@ -67,32 +51,22 @@ and .Iq :later commands provide means to restore the text to an arbitrary state. -.\" .Pp The repeat command .Ql \&. works for all operators and is able to repeat the last insertion or replacement. -.\" -.\" .Ss Tab <-> Space conversion and Line endings \n vs \r\n -.\" .Pp Tabs can optionally be expanded to a configurable number of spaces. The first line ending in the file determines what will be inserted upon a line break (defaults to \n). -.\" -.\" .Ss Jump list and change list -.\" .Pp A per window, file local jump list (navigate with `CTRL+O` and `CTRL+I`) and change list (navigate with `g;` and `g,`) is supported. The jump list is implemented as a fixed sized ring buffer. -.\" -.\" .Ss Macros -.\" The general purpose registers .Ql [a-z] can be used to record macros. Use @@ -111,24 +85,16 @@ repeats the last :-command. is equivalent to .Ql n in normal mode. -.\" -.\" .Ss Structural Regular Expression based Command Language -.\" .Nm vis supports .Xr sam 1 structural regular expression based command language. -.\" -.\" .Ss Mouse support -.\" .Pp The mouse is currently not used at all. -.\" -.\" +.Sh KEY BINDINGS .Ss Operators -.\" .Bl -tag .It c change @@ -157,10 +123,7 @@ swap case .It y yank .El -.\" -.\" .Ss Movements -.\" .Bl -tag .It 0 start of line @@ -271,7 +234,6 @@ next start of a word .It W next start of a WORD .El -.\" .Pp An empty line is currently neither a word nor a WORD. .Pp @@ -282,16 +244,12 @@ moves to the end of the 3rd line down. However vis treats it as a move to the end of current line which is repeated 3 times where the last two have no effect. -.\" -.\" .Ss Text objects -.\" .Pp All of the following text objects are implemented in an inner variant (prefixed with .Ql i`) and a normal variant (prefixed with .Ql a`): -.\" .Bl -tag .It w word @@ -304,18 +262,15 @@ paragraph .It [,], (,), {,}, <,>, ", ', ` block enclosed by these symbols .El -.\" .Pp For sentence and paragraph there is no difference between the inner and normal variants. -.\" .Bl -tag .It gn matches the last used search term in forward direction .It gN matches the last used search term in backward direction .El -.\" .Pp Additionally the following text objects, which are not part of stock vim are also supported: @@ -333,10 +288,7 @@ current line .It il current line without leading and trailing white spaces .El -.\" -.\" .Ss Multiple Cursors / Selections -.\" .Nm vis supports multiple cursors with immediate visual feedback (unlike in the visual block mode of vim where for example inserts only become visible @@ -346,7 +298,6 @@ more than one cursor exists, the primary one is styled differently (yellow by default). .Pp To manipulate multiple cursors use in normal mode: -.\" .Bl -tag .It Ctrl-K create count new cursors on the lines above @@ -373,10 +324,8 @@ try to align all cursor on the same column .It Esc dispose all but the primary cursor .El -.\" .Pp Visual mode was enhanced to recognize: -.\" .Bl -tag .It I create a cursor at the start of every selected line @@ -409,18 +358,13 @@ trim selections, remove leading and trailing white space .It Esc clear all selections, switch to normal mode .El -.\" .Pp In insert/replace mode: -.\" .Bl -tag .It Shift-Tab align all cursors by inserting spaces .El -.\" -.\" .Ss Marks -.\" .Bl -tag .It [a-z] general purpose marks @@ -429,13 +373,9 @@ start of the last selected visual area in current buffer .It > end of the last selected visual area in current buffer .El -.\" -.\" .Ss Registers -.\" .Pp Supported registers include: -.\" .Bl -tag .It "a-"z general purpose registers @@ -452,16 +392,12 @@ command register .It "_ black hole (/dev/null) register .El -.\" .Pp If no explicit register is specified a default register is used. -.\" -.\" .Sh COMMANDS -.\" .Pp -Besides the sam command language the following commands are also recognized at the `:`-command prompt. Any unique prefix can be used. -.\" +Besides the sam command language the following commands are also recognized at +the `:`-command prompt. Any unique prefix can be used. .Bl -tag .Iq :bdelete close all windows which display the same file as the current one @@ -537,20 +473,125 @@ how far back the lexer will look to synchronize parsing .It theme name default dark-16.lua | solarized.lua (16 | 256 color) use the given theme / color scheme for syntax highlighting .El -.\" .Pp Commands taking a file name will use a simple file open dialog based on the included `vis-open` shell script and `vis-menu` utility, if given a file pattern or directory. -.\" .Ic :e *.c opens a menu with all C files .Ic :e \&. opens a menu with all files of the current directory -.\" -.\" +.Ss Runtime Configurable Key Bindings +.Pp +Vis supports run time key bindings via the +.Ic :{un,}map{,-window} +set of commands. The basic syntax is +.Ic :map +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 +.Pp +Unmapping works as follows: +.Ic :unmap +.Pp +The commands suffixed with `-window` only affect the currently active window. +.Ss Layout Specific Key Bindings +.Pp +Vis allows to set key equivalents for non-latin keyboard layouts. This +facilitates editing non-latin texts. The defined mappings take effect +in all non-input modes, i.e. everywhere except in insert and replace mode. +.Pp +For example, the following maps the movement keys in Russian layout: +.Ic :langmap ролд hjkl +.Pp +More generally the syntax of the `:langmap` command is: +.Ic :langmap +.Pp +If the key sequences have not the same length, the rest of the longer +sequence will be discarded. +.Ss Runtime Configurable Key Bindings +.Pp +Vis supports run time key bindings via the +.Ic :{un,}map{,-window} +set of commands. The basic syntax is +.Ic :map +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 +.Pp +Unmapping works as follows: +.Ic :unmap +.Pp +The commands suffixed with `-window` only affect the currently active window. +.Ss Layout Specific Key Bindings +.Pp +Vis allows to set key equivalents for non-latin keyboard layouts. This +facilitates editing non-latin texts. The defined mappings take effect +in all non-input modes, i.e. everywhere except in insert and replace mode. +.Pp +For example, the following maps the movement keys in Russian layout: +.Ic :langmap ролд hjkl +.Pp +More generally the syntax of the `:langmap` command is: +.Ic :langmap +.Pp +If the key sequences have not the same length, the rest of the longer +sequence will be discarded. .Sh ENVIRONMENT -.\" .Bl -tag .Ev VIS_PATH Override path to look for Lua support files as used for syntax highlighting. @@ -573,10 +614,7 @@ if unset .Ev VIS_THEME Override syntax highlighting theme to use. .El -.\" -.\" .Sh FILES -.\" .Pp Settings and keymaps can be specified in a .Pa visrc.lua @@ -600,113 +638,39 @@ can be set to override the path that will look for Lua support files as used for syntax highlighting. .Pa VIS_PATH defaults (in this order) to: -.\" .Bl -bullet .It The location of the .Nm vis binary .It -.Pa $XDG_CONFIG_HOME/vis`, where +.Pa $XDG_CONFIG_HOME/vis +where .Pa $XDG_CONFIG_HOME refers to -`$HOME/.config -if unset +.Pa $HOME/.config +if unset. .It -.Pa /usr/local/share/vis` +.Pa /usr/local/share/vis .It -.Pa /usr/share/vis` +.Pa /usr/share/vis .El -.\" .Pp The environment variable .Ev VIS_THEME can be set to specify the theme used by .Nm vis : -.\" .Bd -literal VIS_THEME=/path/to/your/theme.lua export VIS_THEME .Ed -.\" -.\" -.Ss Runtime Configurable Key Bindings -.\" -.Pp -Vis supports run time key bindings via the -.Ic :{un,}map{,-window} -set of commands. The basic syntax is -.Ic :map -where mode is one of -.Ql normal -, -.Ql insert -, -.Ql replace -, -.Ql visual -, -.Ql visual-line -or -.Ql operator-pending -. -.Ql lhs -refers to the key to map, -.Ql rhs -is a key action or alias. An existing mapping can be overridden by appending -.Ql ! -to the map command. -.\" -.Pp -Key mappings are always recursive, this means doing something like -.Ic :map! normal j 2j -will not work because it will enter an endless loop. Instead vis uses -pseudo keys referred to as key actions which can be used to invoke a set -of available (see -.Ic :help -or -.Ql F1 -for a list) editor functions. Hence the correct thing to do would be -.Ic :map! normal j 2 -.\" -.Pp -Unmapping works as follows: -.Pp :unmap -.Pp -The commands suffixed with `-window` only affect the currently active window. -.\" -.\" -.Ss Layout Specific Key Bindings -.\" -.Pp -Vis allows to set key equivalents for non-latin keyboard layouts. This -facilitates editing non-latin texts. The defined mappings take effect -in all non-input modes, i.e. everywhere except in insert and replace mode. -.\" -.Pp -For example, the following maps the movement keys in Russian layout: -.Ic :langmap ролд hjkl -.\" -.Pp -More generally the syntax of the `:langmap` command is: -.Ic :langmap -.\" -.Pp -If the key sequences have not the same length, the rest of the longer -sequence will be discarded. -.\" -.\" .Sh SEE ALSO -.\" .Xr vis-menu 1 .Xr vis-open 1 .Xr vis-clipboard 1 .Xr vis-complete 1 -.\" -.\" .Sh AUTHORS -.\" .Nm vis is written by .An Marc André Tanner Aq mat at brain-dump.org -- cgit v1.2.3 From 8c7949a2c725970978b7980f40be1d1716bd5849 Mon Sep 17 00:00:00 2001 From: josuah Date: Sat, 15 Oct 2016 23:35:48 -0400 Subject: vis.1: Added spacing as in manpages.bsd.lv --- vis.1 | 210 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 199 insertions(+), 11 deletions(-) diff --git a/vis.1 b/vis.1 index 3ec5eef..3a91973 100644 --- a/vis.1 +++ b/vis.1 @@ -2,23 +2,31 @@ .Dt VIS 1 .Os .Sh NAME +. .Nm vis .Nd a vim like text editor +. .Sh SYNOPSIS +. .Nm vis .Op Ic +command .Op Ar files Fl +. .Sh DESCRIPTION +. .Nm vis is a highly efficient vim like text editor. .Bl -tag .It Fl v Print version information and exit. +. .It Fl - Denotes the end of the options. Arguments after this will be handled as a file name. .El +. .Ss Modes +. Vis implements more or less functional normal, operator-pending, insert, replace and visual (in both line and character wise variants) modes. .Pp @@ -31,8 +39,9 @@ the editor to edit your commands / search terms. Ex mode is deliberately not implemented, instead a variant of the structural regular expression based command language of `sam(1)` is supported. +. .Ss Undo/Redo and Repeat -.Pp +. The text is currently snapshotted whenever an operator is completed as well as when insert or replace mode is left. Additionally a snapshot is also taken if in insert or replace mode a certain idle time elapses. @@ -56,17 +65,21 @@ The repeat command .Ql \&. works for all operators and is able to repeat the last insertion or replacement. +. .Ss Tab <-> Space conversion and Line endings \n vs \r\n -.Pp +. Tabs can optionally be expanded to a configurable number of spaces. The first line ending in the file determines what will be inserted upon a line break (defaults to \n). +. .Ss Jump list and change list -.Pp +. A per window, file local jump list (navigate with `CTRL+O` and `CTRL+I`) and change list (navigate with `g;` and `g,`) is supported. The jump list is implemented as a fixed sized ring buffer. +. .Ss Macros +. The general purpose registers .Ql [a-z] can be used to record macros. Use @@ -85,152 +98,224 @@ repeats the last :-command. is equivalent to .Ql n in normal mode. +. .Ss Structural Regular Expression based Command Language +. .Nm vis supports .Xr sam 1 structural regular expression based command language. +. .Ss Mouse support -.Pp -The mouse is currently not used at all. +. +. .Sh KEY BINDINGS +. .Ss Operators +. .Bl -tag .It c change +. .It d delete +. .It ! filter +. .It = indent, currently an alias for gq +. .It gq format using fmt(1) +. .It gu make lowercase +. .It gU make uppercase +. .It J join +. .It p put +. .It < shift-left +. .It > shift-right +. .It ~ swap case +. .It y yank .El +. .Ss Movements +. .Bl -tag .It 0 start of line +. .It b previous start of a word +. .It B previous start of a WORD +. .It $ end of line +. .It e next end of a word +. .It E next end of a WORD +. .It F char to next occurrence of char to the left +. .It f char to next occurrence of char to the right +. .It ^ first non-blank of line +. .It g0 begin of display line +. .It g$ end of display line +. .It ge previous end of a word +. .It gE previous end of a WORD +. .It gg begin of file +. .It G goto line or end of file +. .It gj display line down +. .It gk display line up +. .It g_ last non-blank of line +. .It gm middle of display line +. .It | goto column +. .It h char left +. .It H goto top/home line of window +. .It j line down +. .It k line up +. .It l char right +. .It L goto bottom/last line of window +. .It ` mark go to mark +. .It ' mark go to start of line containing mark +. .It % match bracket +. .It M goto middle line of window +. .It ]] next end of C-like function +. .It } next paragraph +. .It ) next sentence +. .It ][ next start of C-like function +. .It N repeat last search backwards +. .It n repeat last search forward +. .It [] previous end of C-like function +. .It [{ previous start of block +. .It ]} next start of block +. .It [( previous start of parenthese pair +. .It ]) next start of parenthese pair +. .It { previous paragraph +. .It ( previous sentence +. .It [[ previous start of C-like function +. .It ; repeat last to/till movement +. .It , repeat last to/till movement but in opposite direction +. .It # search word under cursor backwards +. .It * search word under cursor forwards +. .It T char till before next occurrence of char to the left +. .It t char till before next occurrence of char to the right +. .It ? text to next match of text in backward direction +. .It / text to next match of text in forward direction +. .It w next start of a word +. .It W next start of a WORD .El @@ -244,21 +329,27 @@ moves to the end of the 3rd line down. However vis treats it as a move to the end of current line which is repeated 3 times where the last two have no effect. +. .Ss Text objects -.Pp +. All of the following text objects are implemented in an inner variant (prefixed with .Ql i`) and a normal variant (prefixed with .Ql a`): .Bl -tag +. .It w word +. .It W WORD +. .It s sentence +. .It p paragraph +. .It [,], (,), {,}, <,>, ", ', ` block enclosed by these symbols .El @@ -266,8 +357,10 @@ block enclosed by these symbols For sentence and paragraph there is no difference between the inner and normal variants. .Bl -tag +. .It gn matches the last used search term in forward direction +. .It gN matches the last used search term in backward direction .El @@ -275,20 +368,28 @@ matches the last used search term in backward direction Additionally the following text objects, which are not part of stock vim are also supported: .Bl -tag +. .It ae entire file content +. .It ie entire file content except for leading and trailing empty lines +. .It af C-like function definition including immediately preceding comments +. .It if C-like function definition only function body +. .It al current line +. .It il current line without leading and trailing white spaces .El +. .Ss Multiple Cursors / Selections +. .Nm vis supports multiple cursors with immediate visual feedback (unlike in the visual block mode of vim where for example inserts only become visible @@ -299,102 +400,145 @@ 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 create count new cursors on the lines above +. .It Ctrl-Meta-K create count new cursors on the lines above the first cursor +. .It Ctrl-J create count new cursors on the lines below +. .It Ctrl-Meta-J create count new cursors on the lines below the last cursor +. .It Ctrl-P remove primary cursor +. .It Ctrl-N select word the cursor is currently over, switch to visual mode +. .It Ctrl-U make the count previous cursor primary +. .It Ctrl-D make the count next cursor primary +. .It Ctrl-C remove the count cursor column +. .It Ctrl-L remove all but the count cursor column +. .It Tab try to align all cursor on the same column +. .It Esc dispose all but the primary cursor .El .Pp Visual mode was enhanced to recognize: .Bl -tag +. .It I create a cursor at the start of every selected line +. .It A create a cursor at the end of every selected line +. .It Tab left align selections by inserting spaces +. .It Shift-Tab right align selections by inserting spaces +. .It Ctrl-N create new cursor and select next word matching current selection +. .It Ctrl-X clear (skip) current selection, but select next matching word +. .It Ctrl-P remove primary cursor +. .It Ctrl-U/K make the count previous cursor primary +. .It Ctrl-D/J make the count next cursor primary +. .It Ctrl-C remove the count cursor column +. .It Ctrl-L remove all but the count cursor column +. .It + rotates selections rightwards count times +. .It - rotates selections leftwards count times +. .It \e trim selections, remove leading and trailing white space +. .It Esc clear all selections, switch to normal mode .El .Pp In insert/replace mode: .Bl -tag +. .It Shift-Tab align all cursors by inserting spaces .El +. .Ss Marks +. .Bl -tag +. .It [a-z] general purpose marks +. .It < start of the last selected visual area in current buffer +. .It > end of the last selected visual area in current buffer .El +. .Ss Registers -.Pp +. Supported registers include: .Bl -tag +. .It "a-"z general purpose registers +. .It "A-"Z append to corresponding general purpose register +. .It "*, "+ system clipboard integration via shell script vis-clipboard +. .It "0 yank register +. .It "/ search register +. .It ": command register +. .It "_ black hole (/dev/null) register .El .Pp If no explicit register is specified a default register is used. +. .Sh COMMANDS +. .Pp Besides the sam command language the following commands are also recognized at the `:`-command prompt. Any unique prefix can be used. @@ -423,53 +567,77 @@ open a new window close all windows, exit editor .Iq :q close currently focused window +. .It :r insert content of another file at current cursor position +. .It :set set the options below +. .It :split split window horizontally +. .It :s search and replace currently implemented in terms of `sed(1)` +. .It :unmap remove a global key mapping +. .It :unmap-window remove a window local key mapping +. .It :vnew open an empty window, arrange vertically +. .It :vsplit split window vertically +. .It :wq write changes then close window +. .It :w write current buffer content to file +. .It tabwidth [1-8] default 8 set display width of a tab and number of spaces to use if expandtab is enabled +. .It expandtab (yes|no) default no whether typed in tabs should be expanded to tabwidth spaces +. .It autoindent (yes|no) default no replicate spaces and tabs at the beginning of the line when +. .It number (yes|no) default no +. .It relativenumber (yes|no) default no whether absolute or relative line numbers are printed alongside +. .It syntax name default yes use syntax definition given (e.g. "c") or disable syntax +. .It show show/hide special white space replacement symbols .Bl -bullet +. .It newlines = [0|1] default 0 +. .It tabs = [0|1] default 0 +. .It spaces = [0|1] default 0 .El +. .It cursorline (yes|no) default no highlight the line on which the cursor currently resides +. .It colorcolumn number default 0 highlight the given column +. .It horizon number default 32768 (32K) how far back the lexer will look to synchronize parsing +. .It theme name default dark-16.lua | solarized.lua (16 | 256 color) use the given theme / color scheme for syntax highlighting .El @@ -481,8 +649,9 @@ a file pattern or directory. opens a menu with all C files .Ic :e \&. opens a menu with all files of the current directory +. .Ss Runtime Configurable Key Bindings -.Pp +. Vis supports run time key bindings via the .Ic :{un,}map{,-window} set of commands. The basic syntax is @@ -522,8 +691,9 @@ Unmapping works as follows: .Ic :unmap .Pp The commands suffixed with `-window` only affect the currently active window. +. .Ss Layout Specific Key Bindings -.Pp +. Vis allows to set key equivalents for non-latin keyboard layouts. This facilitates editing non-latin texts. The defined mappings take effect in all non-input modes, i.e. everywhere except in insert and replace mode. @@ -536,8 +706,9 @@ More generally the syntax of the `:langmap` command is: .Pp If the key sequences have not the same length, the rest of the longer sequence will be discarded. +. .Ss Runtime Configurable Key Bindings -.Pp +. Vis supports run time key bindings via the .Ic :{un,}map{,-window} set of commands. The basic syntax is @@ -577,8 +748,9 @@ Unmapping works as follows: .Ic :unmap .Pp The commands suffixed with `-window` only affect the currently active window. +. .Ss Layout Specific Key Bindings -.Pp +. Vis allows to set key equivalents for non-latin keyboard layouts. This facilitates editing non-latin texts. The defined mappings take effect in all non-input modes, i.e. everywhere except in insert and replace mode. @@ -591,14 +763,18 @@ More generally the syntax of the `:langmap` command is: .Pp If the key sequences have not the same length, the rest of the longer sequence will be discarded. +. .Sh ENVIRONMENT +. .Bl -tag .Ev VIS_PATH Override path to look for Lua support files as used for syntax highlighting. Defaults (in this order) to: .Bl -bullet +. .It The location of the vis binary +. .It .Pa $XDG_CONFIG_HOME/vis where @@ -606,15 +782,19 @@ where refers to .Pa $HOME/.config if unset +. .It .Pa /usr/local/share/vis +. .It .Pa /usr/share/vis .El .Ev VIS_THEME Override syntax highlighting theme to use. .El +. .Sh FILES +. .Pp Settings and keymaps can be specified in a .Pa visrc.lua @@ -639,10 +819,12 @@ will look for Lua support files as used for syntax highlighting. .Pa VIS_PATH defaults (in this order) to: .Bl -bullet +. .It The location of the .Nm vis binary +. .It .Pa $XDG_CONFIG_HOME/vis where @@ -650,8 +832,10 @@ where refers to .Pa $HOME/.config if unset. +. .It .Pa /usr/local/share/vis +. .It .Pa /usr/share/vis .El @@ -665,12 +849,16 @@ can be set to specify the theme used by VIS_THEME=/path/to/your/theme.lua export VIS_THEME .Ed +. .Sh SEE ALSO +. .Xr vis-menu 1 .Xr vis-open 1 .Xr vis-clipboard 1 .Xr vis-complete 1 +. .Sh AUTHORS +. .Nm vis is written by .An Marc André Tanner Aq mat at brain-dump.org -- cgit v1.2.3