From 11d22b1ed9140542f95f4a05d3f412bfc0163565 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Tue, 21 Jun 2016 10:08:32 +1000
Subject: vis-open: Add a manpage.

---
 Makefile   |   2 ++
 vis-open.1 | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)
 create mode 100644 vis-open.1

diff --git a/Makefile b/Makefile
index df95781..9b241c8 100644
--- a/Makefile
+++ b/Makefile
@@ -97,9 +97,11 @@ install: vis vis-menu
 	@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
 	@sed -e "s/VERSION/${VERSION}/g" -e "s/MONTH DAY, YEAR/$(date +'%B %m, %Y')/g" < vis-clipboard.1 > ${DESTDIR}${MANPREFIX}/man1/vis-clipboard.1
+	@sed -e "s/VERSION/${VERSION}/g" -e "s/MONTH DAY, YEAR/$(date +'%B %m, %Y')/g" < vis-open.1 > ${DESTDIR}${MANPREFIX}/man1/vis-open.1
 	@chmod 644 ${DESTDIR}${MANPREFIX}/man1/vis.1
 	@chmod 644 ${DESTDIR}${MANPREFIX}/man1/vis-menu.1
 	@chmod 644 ${DESTDIR}${MANPREFIX}/man1/vis-clipboard.1
+	@chmod 644 ${DESTDIR}${MANPREFIX}/man1/vis-open.1
 
 uninstall:
 	@echo removing executable file from ${DESTDIR}${PREFIX}/bin
diff --git a/vis-open.1 b/vis-open.1
new file mode 100644
index 0000000..749ab8f
--- /dev/null
+++ b/vis-open.1
@@ -0,0 +1,108 @@
+.Dd MONTH DAY, YEAR
+.Os Vis VERSION
+.Dt VIS-OPEN 1
+
+.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.
+.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-menu 1 ,
+.Xr vis 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.
-- 
cgit v1.2.3