From 1393942de38fa6ece726fd861cc15e2a5a369fbd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Ekl=C3=B6f?= <daniel@ekloef.se>
Date: Thu, 8 Dec 2022 12:17:55 +0100
Subject: [PATCH] readme, doc/foot.1: document shell-integration:command-output
 tracking

---
 README.md      | 36 ++++++++++++++++++++++++++++++++++++
 doc/foot.1.scd | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/README.md b/README.md
index b1cfb37d..c1be7476 100644
--- a/README.md
+++ b/README.md
@@ -359,6 +359,42 @@ See the
 [wiki](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts)
 for details, and examples for other shells.
 
+### Piping last command’s output
+
+The key binding `pipe-command-output` can pipe the last command’s
+output to an application of your choice (similar to the other `pipe-*`
+key bindings):
+
+```ini
+[key-bindings]
+pipe-command-output=[sh -c "f=$(mktemp); cat - > $f; footclient emacsclient -nw $f; rm $f"] Control+Shift+g
+```
+
+When pressing <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>g</kbd>, the last
+command’s output is written to a temporary file, then an emacsclient
+is started in a new footclient instance. The temporary file is removed
+after the footclient instance has closed.
+
+For this to work, the shell must emit an OSC-133;C (`\E]133;C\E\\`)
+sequence before command output starts, and an OSC-133;D
+(`\E]133;D\E\\`) when the command output ends.
+
+In fish, one way to do this is to add `preexec` and `postexec` hooks:
+
+```fish
+function foot_cmd_start --on-event fish_preexec
+  echo -en "\e]133;C\e\\"
+end
+
+function foot_cmd_end --on-event fish_postexec
+  echo -en "\e]133;D\e\\"
+end
+```
+
+See the
+[wiki](https://codeberg.org/dnkl/foot/wiki#user-content-piping-last-commands-output)
+for details, and examples for other shells
+
 
 ## Alt/meta
 
diff --git a/doc/foot.1.scd b/doc/foot.1.scd
index 385f9721..8e2fb313 100644
--- a/doc/foot.1.scd
+++ b/doc/foot.1.scd
@@ -424,6 +424,38 @@ See the wiki
 (https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts)
 for details, and examples for other shells.
 
+## Piping last command’s output
+
+The key binding *pipe-command-output* can pipe the last command’s
+output to an application of your choice (similar to the other
+*pipe-\** key bindings):
+
+	*\[key-bindings\]++
+pipe-command-output=[sh -c "f=$(mktemp); cat - > $f; footclient emacsclient -nw $f; rm $f"] Control+Shift+g*
+
+When pressing *ctrl*+*shift*+*g*, the last command’s output is written
+to a temporary file, then an emacsclient is started in a new
+footclient instance. The temporary file is removed after the
+footclient instance has closed.
+
+For this to work, the shell must emit an OSC-133;C (*\\E]133;C\\E\\\\*)
+sequence before command output starts, and an OSC-133;D
+(*\\E]133;D\\E\\\\*) when the command output ends.
+
+In fish, one way to do this is to add _preexec_ and _postexec_ hooks:
+
+	*function foot_cmd_start --on-event fish_preexec
+		echo -en "\\e]133;C\\e\\\\"
+	end*
+
+	*function foot_cmd_end --on-event fish_postexec
+		echo -en "\\e]133;D\\e\\\\"
+	end*
+
+See the wiki
+(https://codeberg.org/dnkl/foot/wiki#user-content-piping-last-commands-output)
+for details, and examples for other shells
+
 # TERMINFO
 
 Client applications use the terminfo identifier specified by the