6 files changed, 59 insertions, 7 deletions
diff --git a/bridge/bin/bridge b/bridge/bin/bridge
index 6ae4ab11..33cf4577 100755
--- a/bridge/bin/bridge
+++ b/bridge/bin/bridge
@@ -1,5 +1,12 @@
 #! /bin/sh
+#
+# Interface to the bridge commands.
+#
+# See commands below $bindir
+#
 set -euf
-command="$1"; shift
+
 bindir="$(dirname $(readlink -f "$0"))/../lib/bridge/bin"
-exec "$bindir/$command" "$@"
+cmd="$bindir/$1"; shift
+
+exec "$cmd" "$@"
diff --git a/bridge/lib/bridge/bin/attach b/bridge/lib/bridge/bin/attach
index 2edefbe3..f456f8a6 100755
--- a/bridge/lib/bridge/bin/attach
+++ b/bridge/lib/bridge/bin/attach
@@ -1,3 +1,10 @@
 #! /bin/sh
+#
+# Attach current tty to a session.
+#
+## SYNOPSIS
+#
+#     bridge attach SESSION
+#
 set -euf
 exec tmux -L bridge attach-session -t "$1"
diff --git a/bridge/lib/bridge/bin/create b/bridge/lib/bridge/bin/create
index 31b2f3d8..2df8b214 100755
--- a/bridge/lib/bridge/bin/create
+++ b/bridge/lib/bridge/bin/create
@@ -1,4 +1,13 @@
 #! /bin/sh
+#
+# Create a new session.
+#
+## SYNOPSIS
+#
+#     bridge create SESSION [COMMAND [ARGS ...]]
+#
+# COMMAND defaults to $SHELL (by implication / tmux)
+#
 set -euf
 target="$1"; shift
 tmux -L bridge new-session -d -s "$target" "$@"
diff --git a/bridge/lib/bridge/bin/destroy b/bridge/lib/bridge/bin/destroy
index f625d138..dffdbd8a 100755
--- a/bridge/lib/bridge/bin/destroy
+++ b/bridge/lib/bridge/bin/destroy
@@ -1,3 +1,12 @@
 #! /bin/sh
+#
+# Destroy a session.
+#
+## SYNOPSIS
+#
+#     bridge destroy SESSION
+#
+# Note that this may destroy similar named sessions (by implication / tmux)
+#
 set -euf
 tmux -L bridge kill-session -t "$1"
diff --git a/bridge/lib/bridge/bin/list b/bridge/lib/bridge/bin/list
index 8b164516..0b767a9b 100755
--- a/bridge/lib/bridge/bin/list
+++ b/bridge/lib/bridge/bin/list
@@ -1,3 +1,10 @@
 #! /bin/sh
+#
+# Write a list of all session names to stdout.
+#
+## SYNOPSIS
+#
+#     bridge list
+#
 set -euf
 exec tmux -L bridge list-sessions | cut -d: -f1
diff --git a/bridge/lib/bridge/bin/paste b/bridge/lib/bridge/bin/paste
index d5a768ad..d3ed1fc5 100755
--- a/bridge/lib/bridge/bin/paste
+++ b/bridge/lib/bridge/bin/paste
@@ -1,17 +1,30 @@
 #! /bin/sh
+#
+# Paste some data to a session.
+#
+## SYNOPSIS
+#
+#     bridge paste SESSION DATA...
+#     bridge paste SESSION < DATA
+#
 set -euf
+
 target="$1"; shift
+
+# paste args or stdin
 if test $# -gt 0; then
   tmux -L bridge set-buffer -b 0 "$*"
 else
+  # use aux file instead of direct stdin for Vim and when used from $SHELL
   if test -n "${VIMRUNTIME-}" || tty >/dev/null; then
-    temp=`mktemp`
-    trap "rm -f $temp" EXIT INT TERM
-    cat>$temp
+    path=`mktemp`
+    trap "rm -f $path" EXIT INT TERM
+    cat>$path
   else
-    temp=-
+    path=-
   fi
-  tmux -L bridge load-buffer -b 0 $temp
+  tmux -L bridge load-buffer -b 0 $path
 fi
+
 tmux -L bridge paste-buffer -b 0 -t "$target"
 tmux -L bridge   set-buffer -b 0 READY.