7 files changed, 68 insertions, 10 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.
diff --git a/bridge/share/doc/bridge/README.md b/bridge/share/doc/bridge/README.md
index 07f5eb6d..77c62374 100644
--- a/bridge/share/doc/bridge/README.md
+++ b/bridge/share/doc/bridge/README.md
@@ -1,5 +1,3 @@
-# //bridge
-
 Bridge is a tool to connect your favourite editor and interpreter (or
 similar) for maximum profit.
 
@@ -20,6 +18,13 @@ similar) for maximum profit.
     # mark that stuff
     # press return
 
+    # paste some stuff into the session
+    bridge paste my_fancy_interpreter '1 + 2 + 4^M'
+    # (note that ^M is carriage return obtained by pressing ^V^M AKA C-V C-M)
+
+    # or use bridge as a sink in your pipeline
+    echo 2^20 | bridge paste my_fancy_interpreter
+
     # you can use tab-completion everywhere (if installed)
 
 
@@ -49,5 +54,6 @@ Hint #3: you could also use ~/.profile or similar
 
 ## install bridge into some usr-like hierarchy [advanced]
 
-  tar -C //bridge -c . | tar --exclude=./README.md -C ~/opt -v -x
+    tar -C //bridge -c . |
+        tar --exclude=./README.md -C ~/opt -v --keep-newer-files -x