Add docs about embedding in the kitty statusline

See #35 for more info.

Author: vimpostor

doc/tags

@@ -23,5 +23,9 @@ tpipeline-api	tpipeline.txt	/*tpipeline-api*
 tpipeline-configure	tpipeline.txt	/*tpipeline-configure*
 tpipeline-contents	tpipeline.txt	/*tpipeline-contents*
 tpipeline-introduction	tpipeline.txt	/*tpipeline-introduction*
+tpipeline-kitty	tpipeline-kitty.txt	/*tpipeline-kitty*
+tpipeline-kitty-configure	tpipeline-kitty.txt	/*tpipeline-kitty-configure*
+tpipeline-kitty-introduction	tpipeline-kitty.txt	/*tpipeline-kitty-introduction*
+tpipeline-kitty.txt	tpipeline-kitty.txt	/*tpipeline-kitty.txt*
 tpipeline-tmux	tpipeline.txt	/*tpipeline-tmux*
 tpipeline.txt	tpipeline.txt	/*tpipeline.txt*

doc/tpipeline-kitty.txt

@@ -0,0 +1,124 @@
+*tpipeline-kitty.txt*	Kitty integration
+*tpipeline-kitty*
+
+
+Introduction					|tpipeline-kitty-introduction|
+Configuration					|tpipeline-kitty-configure|
+
+==============================================================================
+INTRODUCTION						*tpipeline-kitty-introduction*
+
+It is possible to embed the vim statusline in the statusline of the kitty
+terminal emulator, instead of embedding it in the tmux statusline.
+This can be achieved by utilizing the |g:tpipeline_refreshcmd| command and by
+adapting the kitty config.
+
+------------------------------------------------------------------------------
+CONFIGURATION						*tpipeline-kitty-configure*
+
+From this plugin side you need to setup |g:tpipeline_refreshcmd| such that it
+notifies kitty everytime the vim statusline changes. Hence you may put
+something like the following in your vim config:
+
+>
+	let g:tpipeline_refreshcmd = "kitty @ set-tab-title Master test"
+<
+
+Then to actually receive the interrupts on every update at kitty's side, make
+sure your `kitty.conf` contains the following lines:
+
+>
+	allow_remote_control yes
+	listen_on unix:@mykitty
+	tab_bar_style custom
+	tab_bar_min_tabs 1
+	tab_separator ""
+<
+
+Then the final thing left to do is to write a short Python wrapper script that
+handles the statusline updates. The following python script should be copied
+to `~/.config/kitty/tab_bar.py`:
+
+>
+import os
+from kitty.boss import get_boss
+from kitty.fast_data_types import Screen, add_timer
+from kitty.tab_bar import DrawData, ExtraData, TabBarData, draw_title, as_rgb
+from kitty.utils import color_as_int
+
+timer_id = None
+
+def parse_stl(screen: Screen, draw_data: DrawData, stl: str, draw: bool):
+	pos = 0
+	length = 0
+	while pos < len(stl):
+		next = stl.find("#[", pos)
+		if next == -1:
+			length += len(stl[pos:])
+			if draw:
+				screen.draw(stl[pos:])
+			return length
+
+		length += len(stl[pos:next])
+		if draw:
+			screen.draw(stl[pos:next])
+		pos = next + 1
+		next = stl.find("]", pos)
+		if next == -1:
+			length += len(stl[pos:])
+			if draw:
+				screen.draw(stl[pos:])
+			return length
+
+		fmt = stl[pos+1:next].split(",")
+		for f in fmt:
+			if f.startswith("fg="):
+				if f == "fg=default":
+					screen.cursor.fg = as_rgb(int(draw_data.default_fg))
+				else:
+					screen.cursor.fg = as_rgb(int(f[4:10], 16))
+			elif f.startswith("bg="):
+				if f == "bg=default":
+					screen.cursor.bg = as_rgb(int(draw_data.default_bg))
+				else:
+					screen.cursor.bg = as_rgb(int(f[4:10], 16))
+
+		pos = next + 1
+
+	return length
+
+def draw_tpipeline(screen: Screen, draw_data: DrawData):
+	stl = open('/tmp/tmux-' + str(os.getuid()) + '/default-$0-vimbridge').readline()
+	parse_stl(screen, draw_data, stl, True)
+	stl = open('/tmp/tmux-' + str(os.getuid()) + '/default-$0-vimbridge-R').readline()
+	length = parse_stl(screen, draw_data, stl, False)
+	screen.draw(" " * (screen.columns - screen.cursor.x - length))
+	length = parse_stl(screen, draw_data, stl, True)
+
+def redraw_tab_bar(timer_id):
+	tm = get_boss().active_tab_manager
+	if tm is not None:
+		tm.mark_tab_bar_dirty()
+
+def draw_tab(
+		draw_data: DrawData, screen: Screen, tab: TabBarData,
+		before: int, max_title_length: int, index: int, is_last: bool,
+		extra_data: ExtraData
+		) -> int:
+
+	global timer_id
+	if timer_id is None:
+		timer_id = add_timer(redraw_tab_bar, 0.3, True)
+
+	if index == 1:
+		draw_tpipeline(screen, draw_data)
+
+	return screen.cursor.x
+<
+
+That's it! Make sure to restart kitty after these changes. Now the vim
+statusline should be embedded in the kitty statusline instead of the tmux
+statusline.
+
+==============================================================================
+	vim:tw=78:sw=4:ts=8:ft=help:norl:noet: