From bcca9c762ee1d27d43303a8af0c027eb85ffed4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Andr=C3=A9=20Tanner?= Date: Thu, 8 Dec 2016 10:42:09 +0100 Subject: Move manual pages to man/ subfolder --- Makefile | 6 +- man/vis-clipboard.1 | 102 +++++ man/vis-menu.1 | 255 +++++++++++ man/vis-open.1 | 112 +++++ man/vis.1 | 1259 +++++++++++++++++++++++++++++++++++++++++++++++++++ vis-clipboard.1 | 102 ----- vis-menu.1 | 255 ----------- vis-open.1 | 112 ----- vis.1 | 1259 --------------------------------------------------- 9 files changed, 1731 insertions(+), 1731 deletions(-) create mode 100644 man/vis-clipboard.1 create mode 100644 man/vis-menu.1 create mode 100644 man/vis-open.1 create mode 100644 man/vis.1 delete mode 100644 vis-clipboard.1 delete mode 100644 vis-menu.1 delete mode 100644 vis-open.1 delete mode 100644 vis.1 diff --git a/Makefile b/Makefile index b7ebd0a..962fb7e 100644 --- a/Makefile +++ b/Makefile @@ -82,7 +82,7 @@ dist: clean man: @for m in ${MANUALS}; do \ echo "Generating $$m"; \ - sed -e "s/VERSION/${VERSION}/" "$$m" | mandoc -W warning -T utf8 -T xhtml -O man=%N.%S.html -O style=mandoc.css 1> "$$m".html || true; \ + sed -e "s/VERSION/${VERSION}/" "man/$$m" | mandoc -W warning -T utf8 -T xhtml -O man=%N.%S.html -O style=mandoc.css 1> "man/$$m.html" || true; \ done luadoc: @@ -114,7 +114,7 @@ install: vis vis-menu @echo installing manual pages to ${DESTDIR}${MANPREFIX}/man1 @mkdir -p ${DESTDIR}${MANPREFIX}/man1 @for m in ${MANUALS}; do \ - sed -e "s/VERSION/${VERSION}/" < "$$m" > "${DESTDIR}${MANPREFIX}/man1/$$m" && \ + sed -e "s/VERSION/${VERSION}/" < "man/$$m" > "${DESTDIR}${MANPREFIX}/man1/$$m" && \ chmod 644 "${DESTDIR}${MANPREFIX}/man1/$$m"; \ done @@ -129,4 +129,4 @@ uninstall: @echo removing support files from ${DESTDIR}${SHAREPREFIX}/vis @rm -rf ${DESTDIR}${SHAREPREFIX}/vis -.PHONY: all clean dist install uninstall debug profile coverage test test-update luadoc luadoc-all +.PHONY: all clean dist install uninstall debug profile coverage test test-update luadoc luadoc-all man diff --git a/man/vis-clipboard.1 b/man/vis-clipboard.1 new file mode 100644 index 0000000..f6638b8 --- /dev/null +++ b/man/vis-clipboard.1 @@ -0,0 +1,102 @@ +.Dd November 29, 2016 +.Dt VIS-CLIPBOARD 1 +.Os Vis VERSION +. +.Sh NAME +.Nm vis-clipboard +.Nd Read from or write to the system clipboard +. +.Sh SYNOPSIS +.Nm vis-clipboard +.Fl -usable +.Pp +.Nm vis-clipboard +.Fl -copy +.Pp +.Nm vis-clipboard +.Fl -paste +. +.Sh DESCRIPTION +.Nm vis-clipboard +wraps various system-specific tools for interacting with a system clipboard, +like +.Xr xsel 1 +for X11, +.Xr pbcopy 1 +for Mac OS X, +and +.Pa /dev/clipboard +on Cygwin. +.Pp +.Nm vis-clipboard +can run in three different ways, +depending on the flag given on the command-line. +.Bl -tag -width flag +.It Fl -usable +In this mode, +.Nm vis-clipboard +looks for a way to interface with the system clipboard. +If it finds one, +it terminates with exit code 0. +If no interface to the system clipboard is available, +it terminates with exit code 1. +.It Fl -copy +In this mode, +.Nm vis-clipboard +reads the content of standard input, +and stores it in the system clipboard. +.It Fl -paste +In this mode, +.Nm vis-clipboard +reads the content of the system clipboard, +and writes it to standard output. +.El +. +.Sh ENVIRONMENT +The following environment variables affect the operation of +.Nm vis-clipboard : +.Bl -tag -width Ev +.It Ev DISPLAY +If non-empty, +.Nm vis-clipboard +will prefer to access the X11 clipboard even if other options are available. +.El +. +.Sh EXIT STATUS +.Ex -std vis-clipboard +. +When run with the +.Fl -usable +flag, +an exit status of 0 means that it found a supported system-specific tool, +while 1 means that clipboard access is not available. +. +.Sh EXAMPLES +Test whether clipboard access is available: +.Bd -literal -offset indent +if vis-clipboard --usable; then + echo "Clipboard access available" +else + echo "No clipboard" +fi +.Ed +.Pp +Copy a friendly greeting to the clipboard: +.Bd -literal -offset indent +echo "Hello, World" | vis-clipboard --copy +.Ed +.Pp +Send the current contents of the system clipboard to be recorded and analyzed: +.Bd -literal -offset indent +vis-clipboard --paste | curl -d - https://www.nsa.gov/ +.Ed +. +.Sh SEE ALSO +.Xr pbcopy 1 , +.Xr pbpaste 1 , +.Xr vis 1 , +.Xr xclip 1 , +.Xr xsel 1 +. +.Sh AUTHORS +.An "Marc Andr\('e Tanner" Aq mat@brain-dump.org diff --git a/man/vis-menu.1 b/man/vis-menu.1 new file mode 100644 index 0000000..509dec9 --- /dev/null +++ b/man/vis-menu.1 @@ -0,0 +1,255 @@ +.Dd November 29, 2016 +.Dt VIS-MENU 1 +.Os Vis VERSION +.Sh NAME +.Nm vis-menu +.Nd Interactively select an item from a list +. +.Sh SYNOPSIS +.Nm vis-menu +.Op Fl i +.Op Fl t | Fl b +.Op Fl p Ar prompt +.Op Fl l Ar lines +.Op Ar initial +.Nm vis-menu +.Op Fl v +. +.Sh DESCRIPTION +.Nm vis-menu +allows a user to interactively select one item from a list of options. +A newline-separated list of items is read from standard input, +then the list of items is drawn directly onto the terminal +so the user may select one. +Finally, +the selected item is printed to standard output. +.Pp +For information on actually navigating the menu, +see +.Sx USAGE +below. +.Bl -tag -width flag +.It Fl i +Use case-insensitive comparison when filtering items. +.It Fl t | Fl b +Normally, +the menu is displayed on the current line of the terminal. +When +.Fl t +is provided, the menu will always be drawn on the top line of the terminal. +When +.Fl b +is provided, the menu will always be drawn on the bottom line. +.It Fl p Ar prompt +Display +.Ar prompt +before the list of items. +.It Fl l Ar lines +Normally, +the list is displayed with all the items side-by-side on a single line, +which is space-efficient +but does not show many items at a time, +especially if some of them are long. +When +.Fl l +is provided, +the list is displayed with each item on its own line, +.Ar lines +lines high. +If there are more than +.Ar lines +items in the list, +the user can scroll through them with the arrow keys, +just like in the regular horizontal mode. +.It Ar initial +The user can type into a text field +to filter the list of items +as well as scrolling through them. +If supplied, +.Ar initial +is used as the initial content of the text field. +.It Fl v +Instead of displaying an interactive menu, +.Nm vis-menu +prints its version number to standard output and exits. +.El +. +.Sh USAGE +.Nm vis-menu +displays the prompt (if any), +a text field, +and a list of items. +Normally these are presented side-by-side in a single line, +but if the +.Fl l +flag is given, +the prompt and typing area will be on the first line, +and list items on the following lines. +.Pp +The following commands are available: +.Bl -tag -width ".Sy Control-A" +.It Sy Enter +selects the currently-highlighted list item and exits. +.It Xo Sy Control-\e +or +.Sy Control-] +.Xc +selects the current contents of the text field +(even if it does not appear in the list) +and exits. +.It Xo Sy "ESC ESC" +or +.Sy Control-C +.Xc +exit without selecting any item. +.It Xo Sy Down +or +.Sy Control-N +.Xc +scroll forward through the available list items. +.It Xo Sy Up +or +.Sy Control-P +.Xc +scroll backward through the available list items. +.It Xo Sy Right +or +.Sy Control-F +.Xc +move the cursor forward through the typed text, +and scroll through the available list items. +.It Xo Sy Left +or +.Sy Control-B +.Xc +move the cursor backward through the typed text, +and scroll through the available list items. +.It Xo Sy PageUp +or +.Sy Control-V +.Xc +scrolls to show the previous page of list items. +.It Xo Sy PageDown +or +.Sy Meta-v +.Xc +scrolls to show the next page of list items. +.It Xo Sy Home +or +.Sy Control-A +.Xc +move the cursor to the beginning of the text field +or scroll to the first item in the list. +.It Xo Sy End +or +.Sy Control-E +.Xc +move the cursor to the end of the text field +or scroll to the last item in the list. +.It Sy Meta-b +moves the cursor to the beginning of the current word in the text field. +.It Sy Meta-f +moves the cursor past the end of the current word in the text field. +.It Sy Tab +copies the content of the selected list item into the text field. +This is almost, but not quite, like tab completion. +.It Xo Sy Delete +or +.Sy Control-D +.Xc +delete the character in the text field under the cursor. +.It Sy Backspace +deletes the character in the text field to the left of the cursor. +.It Sy Meta-d +deletes the characters in the text field +from the character under the cursor +to the next space. +.It Sy Control-K +deletes the characters in the text field +from the character under the cursor to the end. +.It Sy Control-U +deletes the characters in the text field +from the beginning up to +(but not including) +the character under the cursor. +.It Sy Control-W +deletes the characters in the text field +from the previous space up to +(but not including) +the character under the cursor. +.El +.Pp +All other non-control characters will be inserted into the text field +at the current cursor position. +.Pp +When there is text in the text field, +only list items that include the given text will be shown. +If the text contains one or more spaces, +each space-delimited string is a separate filter +and only items matching every filter will be shown. +.Pp +If the user filters out all the items from the list, +then hits Enter to select the +.Dq currently highlighted +item, +the text they typed will be returned instead. +. +.Sh EXAMPLES +Here's a shell-script that allows the user to choose a number from one to 10: +.Bd -literal -offset indent +NUMBER=$(seq 1 10 | vis-menu -p "Choose a number") +if [ $? -eq 0 ]; then + echo "You chose: $NUMBER" +else + echo "You refused to choose a number, or an error occurred." +fi +.Ed +. +.Sh DIAGNOSTICS +The +.Nm vis-menu +utility exits 0 if the user successfully selected an item from the list, +and 1 if the user cancelled. +.Pp +If an internal error occurs, +the +.Nm vis-menu +utility prints a message to standard error and exits 1. +Potential error conditions include +being unable to allocate memory, +being unable to read from standard input, +or being run without a controlling terminal. +. +.Sh SEE ALSO +.Xr dmenu 1 , +.Xr slmenu 1 , +.Xr vis 1 +. +.Sh HISTORY +The original model for a single line menu reading items from standard input was +.Xr dmenu 1 +which implements the idea for X11. +.Nm dmenu +is available from +.Li http://tools.suckless.org/dmenu/ +.Pp +The code was subsequently re-worked for ANSI terminal output as +.Xr slmenu 1 +which is available from +.Li https://bitbucket.org/rafaelgg/slmenu/ +.Pp +Since +.Nm slmenu +did not appear to be maintained, +it was forked to become +.Nm vis-menu +to be distributed with +.Xr vis 1 . +. +.Sh AUTHORS +.An "Marc Andr\('e Tanner" Aq mat@brain-dump.org +plus the +.Nm slmenu +and +.Nm dmenu +authors. diff --git a/man/vis-open.1 b/man/vis-open.1 new file mode 100644 index 0000000..299f0d0 --- /dev/null +++ b/man/vis-open.1 @@ -0,0 +1,112 @@ +.Dd November 29, 2016 +.Dt VIS-OPEN 1 +.Os Vis VERSION +. +.Sh NAME +.Nm vis-open +.Nd Interactively select a file to open +. +.Sh SYNOPSIS +.Nm vis-open +.Op Fl p Ar prompt +.Op Fl f +.Op Ar -- +.Op Ar files +.Pp +.Nm vis-open +.Fl h | +.Fl -help +. +.Sh DESCRIPTION +.Nm vis-open +takes a list of filenames and directories on the command-line +and displays them in a menu for the user to select one. +If the user selects a directory +(including +.Li .. ) , +the directory contents are displayed as a fresh menu. +Once the user has selected a filename, +its absolute path is printed to standard output. +.Pp +.Nm vis-open +uses +.Xr vis-menu 1 +as its user-interface, +so see that page for more details. +. +.Bl -tag -width flag +.It Fl p Ar prompt +Display +.Ar prompt +before the list of items. +This is passed straight through to +.Xr vis-menu 1 . +.It Fl f +Normally, +if +.Nm vis-open +is provided with a single filename or directory argument, +it will automatically select it +(printing the filename to standard output, +or presenting a new menu with the contents of the directory). +If +.Fl f +is provided, +.Nm vis-open +will always present the arguments it's given, +even if there's only one. +.It Fl - +If this token is encountered before the first non-option argument, +all following arguments will be treated as menu-items, +even if they would otherwise be valid command-line options. +.Pp +If encountered after the first non-option argument, +or after a previous instance of +.Li -- +it is treated as a menu-item. +.It Ar files +File and directory names to be presented to the user. +If a name does not exist on the filesystem +and the user selects it, +it is treated as a file. +.It Fl h | Fl -help +If present, +.Nm vis-open +prints a usage summary and exits, +ignoring any other flag and arguments. +.El +. +.Sh EXIT STATUS +.Ex -std vis-open +.Pp +In particular, +like +.Xr vis-menu 1 , +.Nm vis-open +prints nothing and sets its exit status to 1 +if the user refused to select a file. +. +.Sh EXAMPLES +.Bd -literal -offset indent +CHOICE=$(vis-open -p "Select a file to stat") +if [ $? -gt 0 ]; then + echo "No selection was made, or an error occurred" +else + stat "$CHOICE" +fi +.Ed +. +.Sh SEE ALSO +.Xr vis 1 , +.Xr vis-menu 1 +. +.Sh AUTHORS +.An "Marc Andr\('e Tanner" Aq mat@brain-dump.org +. +.Sh BUGS +Because +.Nm vis-open +uses +.Xr ls 1 +to obtain the contents of a directory, +weird things might happen if you have control-characters in your filenames. 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[!] +add a global key mapping +.It Cm :map-window[!] +add a window local key mapping +.It Cm :unmap +remove a global key mapping +.It Cm :unmap-window +remove a window local key mapping +.El +In the above +.Cm +refers to one of +.Ql normal , +.Ql insert , +.Ql replace , +.Ql visual , +.Ql visual-line +or +.Ql operator-pending ; +.Cm +refers to the key to map and +.Cm +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 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. diff --git a/vis-clipboard.1 b/vis-clipboard.1 deleted file mode 100644 index f6638b8..0000000 --- a/vis-clipboard.1 +++ /dev/null @@ -1,102 +0,0 @@ -.Dd November 29, 2016 -.Dt VIS-CLIPBOARD 1 -.Os Vis VERSION -. -.Sh NAME -.Nm vis-clipboard -.Nd Read from or write to the system clipboard -. -.Sh SYNOPSIS -.Nm vis-clipboard -.Fl -usable -.Pp -.Nm vis-clipboard -.Fl -copy -.Pp -.Nm vis-clipboard -.Fl -paste -. -.Sh DESCRIPTION -.Nm vis-clipboard -wraps various system-specific tools for interacting with a system clipboard, -like -.Xr xsel 1 -for X11, -.Xr pbcopy 1 -for Mac OS X, -and -.Pa /dev/clipboard -on Cygwin. -.Pp -.Nm vis-clipboard -can run in three different ways, -depending on the flag given on the command-line. -.Bl -tag -width flag -.It Fl -usable -In this mode, -.Nm vis-clipboard -looks for a way to interface with the system clipboard. -If it finds one, -it terminates with exit code 0. -If no interface to the system clipboard is available, -it terminates with exit code 1. -.It Fl -copy -In this mode, -.Nm vis-clipboard -reads the content of standard input, -and stores it in the system clipboard. -.It Fl -paste -In this mode, -.Nm vis-clipboard -reads the content of the system clipboard, -and writes it to standard output. -.El -. -.Sh ENVIRONMENT -The following environment variables affect the operation of -.Nm vis-clipboard : -.Bl -tag -width Ev -.It Ev DISPLAY -If non-empty, -.Nm vis-clipboard -will prefer to access the X11 clipboard even if other options are available. -.El -. -.Sh EXIT STATUS -.Ex -std vis-clipboard -. -When run with the -.Fl -usable -flag, -an exit status of 0 means that it found a supported system-specific tool, -while 1 means that clipboard access is not available. -. -.Sh EXAMPLES -Test whether clipboard access is available: -.Bd -literal -offset indent -if vis-clipboard --usable; then - echo "Clipboard access available" -else - echo "No clipboard" -fi -.Ed -.Pp -Copy a friendly greeting to the clipboard: -.Bd -literal -offset indent -echo "Hello, World" | vis-clipboard --copy -.Ed -.Pp -Send the current contents of the system clipboard to be recorded and analyzed: -.Bd -literal -offset indent -vis-clipboard --paste | curl -d - https://www.nsa.gov/ -.Ed -. -.Sh SEE ALSO -.Xr pbcopy 1 , -.Xr pbpaste 1 , -.Xr vis 1 , -.Xr xclip 1 , -.Xr xsel 1 -. -.Sh AUTHORS -.An "Marc Andr\('e Tanner" Aq mat@brain-dump.org diff --git a/vis-menu.1 b/vis-menu.1 deleted file mode 100644 index 509dec9..0000000 --- a/vis-menu.1 +++ /dev/null @@ -1,255 +0,0 @@ -.Dd November 29, 2016 -.Dt VIS-MENU 1 -.Os Vis VERSION -.Sh NAME -.Nm vis-menu -.Nd Interactively select an item from a list -. -.Sh SYNOPSIS -.Nm vis-menu -.Op Fl i -.Op Fl t | Fl b -.Op Fl p Ar prompt -.Op Fl l Ar lines -.Op Ar initial -.Nm vis-menu -.Op Fl v -. -.Sh DESCRIPTION -.Nm vis-menu -allows a user to interactively select one item from a list of options. -A newline-separated list of items is read from standard input, -then the list of items is drawn directly onto the terminal -so the user may select one. -Finally, -the selected item is printed to standard output. -.Pp -For information on actually navigating the menu, -see -.Sx USAGE -below. -.Bl -tag -width flag -.It Fl i -Use case-insensitive comparison when filtering items. -.It Fl t | Fl b -Normally, -the menu is displayed on the current line of the terminal. -When -.Fl t -is provided, the menu will always be drawn on the top line of the terminal. -When -.Fl b -is provided, the menu will always be drawn on the bottom line. -.It Fl p Ar prompt -Display -.Ar prompt -before the list of items. -.It Fl l Ar lines -Normally, -the list is displayed with all the items side-by-side on a single line, -which is space-efficient -but does not show many items at a time, -especially if some of them are long. -When -.Fl l -is provided, -the list is displayed with each item on its own line, -.Ar lines -lines high. -If there are more than -.Ar lines -items in the list, -the user can scroll through them with the arrow keys, -just like in the regular horizontal mode. -.It Ar initial -The user can type into a text field -to filter the list of items -as well as scrolling through them. -If supplied, -.Ar initial -is used as the initial content of the text field. -.It Fl v -Instead of displaying an interactive menu, -.Nm vis-menu -prints its version number to standard output and exits. -.El -. -.Sh USAGE -.Nm vis-menu -displays the prompt (if any), -a text field, -and a list of items. -Normally these are presented side-by-side in a single line, -but if the -.Fl l -flag is given, -the prompt and typing area will be on the first line, -and list items on the following lines. -.Pp -The following commands are available: -.Bl -tag -width ".Sy Control-A" -.It Sy Enter -selects the currently-highlighted list item and exits. -.It Xo Sy Control-\e -or -.Sy Control-] -.Xc -selects the current contents of the text field -(even if it does not appear in the list) -and exits. -.It Xo Sy "ESC ESC" -or -.Sy Control-C -.Xc -exit without selecting any item. -.It Xo Sy Down -or -.Sy Control-N -.Xc -scroll forward through the available list items. -.It Xo Sy Up -or -.Sy Control-P -.Xc -scroll backward through the available list items. -.It Xo Sy Right -or -.Sy Control-F -.Xc -move the cursor forward through the typed text, -and scroll through the available list items. -.It Xo Sy Left -or -.Sy Control-B -.Xc -move the cursor backward through the typed text, -and scroll through the available list items. -.It Xo Sy PageUp -or -.Sy Control-V -.Xc -scrolls to show the previous page of list items. -.It Xo Sy PageDown -or -.Sy Meta-v -.Xc -scrolls to show the next page of list items. -.It Xo Sy Home -or -.Sy Control-A -.Xc -move the cursor to the beginning of the text field -or scroll to the first item in the list. -.It Xo Sy End -or -.Sy Control-E -.Xc -move the cursor to the end of the text field -or scroll to the last item in the list. -.It Sy Meta-b -moves the cursor to the beginning of the current word in the text field. -.It Sy Meta-f -moves the cursor past the end of the current word in the text field. -.It Sy Tab -copies the content of the selected list item into the text field. -This is almost, but not quite, like tab completion. -.It Xo Sy Delete -or -.Sy Control-D -.Xc -delete the character in the text field under the cursor. -.It Sy Backspace -deletes the character in the text field to the left of the cursor. -.It Sy Meta-d -deletes the characters in the text field -from the character under the cursor -to the next space. -.It Sy Control-K -deletes the characters in the text field -from the character under the cursor to the end. -.It Sy Control-U -deletes the characters in the text field -from the beginning up to -(but not including) -the character under the cursor. -.It Sy Control-W -deletes the characters in the text field -from the previous space up to -(but not including) -the character under the cursor. -.El -.Pp -All other non-control characters will be inserted into the text field -at the current cursor position. -.Pp -When there is text in the text field, -only list items that include the given text will be shown. -If the text contains one or more spaces, -each space-delimited string is a separate filter -and only items matching every filter will be shown. -.Pp -If the user filters out all the items from the list, -then hits Enter to select the -.Dq currently highlighted -item, -the text they typed will be returned instead. -. -.Sh EXAMPLES -Here's a shell-script that allows the user to choose a number from one to 10: -.Bd -literal -offset indent -NUMBER=$(seq 1 10 | vis-menu -p "Choose a number") -if [ $? -eq 0 ]; then - echo "You chose: $NUMBER" -else - echo "You refused to choose a number, or an error occurred." -fi -.Ed -. -.Sh DIAGNOSTICS -The -.Nm vis-menu -utility exits 0 if the user successfully selected an item from the list, -and 1 if the user cancelled. -.Pp -If an internal error occurs, -the -.Nm vis-menu -utility prints a message to standard error and exits 1. -Potential error conditions include -being unable to allocate memory, -being unable to read from standard input, -or being run without a controlling terminal. -. -.Sh SEE ALSO -.Xr dmenu 1 , -.Xr slmenu 1 , -.Xr vis 1 -. -.Sh HISTORY -The original model for a single line menu reading items from standard input was -.Xr dmenu 1 -which implements the idea for X11. -.Nm dmenu -is available from -.Li http://tools.suckless.org/dmenu/ -.Pp -The code was subsequently re-worked for ANSI terminal output as -.Xr slmenu 1 -which is available from -.Li https://bitbucket.org/rafaelgg/slmenu/ -.Pp -Since -.Nm slmenu -did not appear to be maintained, -it was forked to become -.Nm vis-menu -to be distributed with -.Xr vis 1 . -. -.Sh AUTHORS -.An "Marc Andr\('e Tanner" Aq mat@brain-dump.org -plus the -.Nm slmenu -and -.Nm dmenu -authors. diff --git a/vis-open.1 b/vis-open.1 deleted file mode 100644 index 299f0d0..0000000 --- a/vis-open.1 +++ /dev/null @@ -1,112 +0,0 @@ -.Dd November 29, 2016 -.Dt VIS-OPEN 1 -.Os Vis VERSION -. -.Sh NAME -.Nm vis-open -.Nd Interactively select a file to open -. -.Sh SYNOPSIS -.Nm vis-open -.Op Fl p Ar prompt -.Op Fl f -.Op Ar -- -.Op Ar files -.Pp -.Nm vis-open -.Fl h | -.Fl -help -. -.Sh DESCRIPTION -.Nm vis-open -takes a list of filenames and directories on the command-line -and displays them in a menu for the user to select one. -If the user selects a directory -(including -.Li .. ) , -the directory contents are displayed as a fresh menu. -Once the user has selected a filename, -its absolute path is printed to standard output. -.Pp -.Nm vis-open -uses -.Xr vis-menu 1 -as its user-interface, -so see that page for more details. -. -.Bl -tag -width flag -.It Fl p Ar prompt -Display -.Ar prompt -before the list of items. -This is passed straight through to -.Xr vis-menu 1 . -.It Fl f -Normally, -if -.Nm vis-open -is provided with a single filename or directory argument, -it will automatically select it -(printing the filename to standard output, -or presenting a new menu with the contents of the directory). -If -.Fl f -is provided, -.Nm vis-open -will always present the arguments it's given, -even if there's only one. -.It Fl - -If this token is encountered before the first non-option argument, -all following arguments will be treated as menu-items, -even if they would otherwise be valid command-line options. -.Pp -If encountered after the first non-option argument, -or after a previous instance of -.Li -- -it is treated as a menu-item. -.It Ar files -File and directory names to be presented to the user. -If a name does not exist on the filesystem -and the user selects it, -it is treated as a file. -.It Fl h | Fl -help -If present, -.Nm vis-open -prints a usage summary and exits, -ignoring any other flag and arguments. -.El -. -.Sh EXIT STATUS -.Ex -std vis-open -.Pp -In particular, -like -.Xr vis-menu 1 , -.Nm vis-open -prints nothing and sets its exit status to 1 -if the user refused to select a file. -. -.Sh EXAMPLES -.Bd -literal -offset indent -CHOICE=$(vis-open -p "Select a file to stat") -if [ $? -gt 0 ]; then - echo "No selection was made, or an error occurred" -else - stat "$CHOICE" -fi -.Ed -. -.Sh SEE ALSO -.Xr vis 1 , -.Xr vis-menu 1 -. -.Sh AUTHORS -.An "Marc Andr\('e Tanner" Aq mat@brain-dump.org -. -.Sh BUGS -Because -.Nm vis-open -uses -.Xr ls 1 -to obtain the contents of a directory, -weird things might happen if you have control-characters in your filenames. diff --git a/vis.1 b/vis.1 deleted file mode 100644 index 1b8652c..0000000 --- a/vis.1 +++ /dev/null @@ -1,1259 +0,0 @@ -.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[!] -add a global key mapping -.It Cm :map-window[!] -add a window local key mapping -.It Cm :unmap -remove a global key mapping -.It Cm :unmap-window -remove a window local key mapping -.El -In the above -.Cm -refers to one of -.Ql normal , -.Ql insert , -.Ql replace , -.Ql visual , -.Ql visual-line -or -.Ql operator-pending ; -.Cm -refers to the key to map and -.Cm -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 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. -- cgit v1.2.3