[vis-menu] Add a manpage.

Unlike the existing vis(1) manpage, this uses the `mdoc` macro set
because it's (very slightly) more modern, and OpenBSD only supports
`mdoc` while everybody else supports both.

2 files changed, 255 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index caa88cc..4835456 100644
--- a/Makefile
+++ b/Makefile
@@ -94,8 +94,10 @@ install: vis vis-menu
 	}
 	@echo installing manual page to ${DESTDIR}${MANPREFIX}/man1
 	@mkdir -p ${DESTDIR}${MANPREFIX}/man1
-	@sed "s/VERSION/${VERSION}/g" < vis.1 > ${DESTDIR}${MANPREFIX}/man1/vis.1
+	@sed -e "s/VERSION/${VERSION}/g" < vis.1 > ${DESTDIR}${MANPREFIX}/man1/vis.1
+	@sed -e "s/VERSION/${VERSION}/g" -e "s/MONTH DAY, YEAR/$(date +'%B %m, %Y')/g" < vis-menu.1 > ${DESTDIR}${MANPREFIX}/man1/vis-menu.1
 	@chmod 644 ${DESTDIR}${MANPREFIX}/man1/vis.1
+	@chmod 644 ${DESTDIR}${MANPREFIX}/man1/vis-menu.1
 
 uninstall:
 	@echo removing executable file from ${DESTDIR}${PREFIX}/bin
diff --git a/vis-menu.1 b/vis-menu.1
new file mode 100644
index 0000000..ebc7bee
--- /dev/null
+++ b/vis-menu.1
@@ -0,0 +1,252 @@
+.Dd MONTH DAY, YEAR
+.Os Vis VERSION
+.Dt VIS-MENU 1
+
+.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
+.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 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.
+.Pp
+
+.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.