aboutsummaryrefslogtreecommitdiff
path: root/vis-menu.1
diff options
context:
space:
mode:
authorMarc André Tanner <mat@brain-dump.org>2016-12-08 10:42:09 +0100
committerMarc André Tanner <mat@brain-dump.org>2016-12-08 10:42:09 +0100
commitbcca9c762ee1d27d43303a8af0c027eb85ffed4e (patch)
treebd15e96d78f46351d2b8786af68c2ac639e62bd4 /vis-menu.1
parent348adec643820a7b8380dcb66ce6cfc5420469f9 (diff)
downloadvis-bcca9c762ee1d27d43303a8af0c027eb85ffed4e.tar.gz
vis-bcca9c762ee1d27d43303a8af0c027eb85ffed4e.tar.xz
Move manual pages to man/ subfolder
Diffstat (limited to 'vis-menu.1')
-rw-r--r--vis-menu.1255
1 files changed, 0 insertions, 255 deletions
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.