From 2a9a64ac28073f22dfb830f65d921938b1f778ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Haoran=20S=2E=20Diao=20=28=E5=88=81=E6=B5=A9=E7=84=B6=29?=
 <0@hairydiode.xyz>
Date: Sat, 6 Sep 2025 14:28:22 -0700
Subject: Added readme

---
 README | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 103 insertions(+), 21 deletions(-)

(limited to 'README')

diff --git a/README b/README
index f6923a5..517a42a 100644
--- a/README
+++ b/README
@@ -1,30 +1,112 @@
-termios sets the stdin terminal to raw
+ptyim, routes terminal input through an input method via pseudottys
 
-make sure to use read/write syscalls, these are non blocking, and will not mess
-up the output of things.
+Usage:
+	$ ptyim
+	$ ptyim /bin/bash
 
-now all line discipline is handled by the pty
+Shell:
+	To find the path to the shell, ptyim first looks for
+		- argument 1
+		- $SHELL
+	then it defaults to /bin/sh
+Controls:
+	'^K' 		(0x0B Vertical Tab)	to toggle input method
+	'`'		(0x80 Backtick)		cancel input
+	Backspace 	(0x7F DEL)		delete last input char
+	Enter		(0x0D Carriage Retrun)	pass the im buffer through 
 
+Configuration:
+	All special keys listed above can be configured in "im.h"
 
--------------------------------=[Controlling TTY]=------------------------------
-Forked bash process makes itself a session leader, then sets the pty as the
-controlling tty
+	IM_PREVIEW and IM_PREVIEW_ENTRIES in "im.h" sets the number of preview
+	entries displayed and or disables previews entirely
 
-It now acts as a bash
-----------------------------------=[Resizeing]=---------------------------------
-SIGWINCH hook, very simple
+	im_key_ranges in "im.h" determines which characters are put into the im
+	buffer
 
------------------------------------=[Testing]=----------------------------------
-fg/bg ctrl-c ctrl-z all works
+	#include boshiamy.h in "im.h" can be replaced with any other im file you
+	would like to use. Refer to imtable.h for format questions.
 
-cmus, bcmus, all work
-vitetris
-telnet star wars
+--------------------------------=[How it Works]=--------------------------------
+
+[xterm, linux console]
+   user	|   ^ Program
+  input	v   | output
+[       ptyim        ]
+  IM    |   ^ Program
+ output v   | Output
+[   pseudoterminal   ]
+  stdin |   ^
+	v   |stdout
+[bash(session leader)]
+
+
+Terminal Emulators, Tmux, Screen, etc. all make use of linux pseudoterminals,
+which are virtual terminals controlled by another piece of software. pytim runs
+in an existing terminal or terminal emulator, and creates a pseudoterminal. It
+then routes all input from the real terminal through itself, so that it can
+apply an input method, before sending that to the pseudoterminal. Output from
+the pseudoterminal is routed as is back to the real terminal.
+
+Caveats:
+	ptyim starts the program running on the pseudoterminal, and makes sure
+	to set it to be the session leader for the pseudoterminal. This is
+	usually bash or some other shell
+
+	ptyim has to handle sigwinch signals for when the terminal is resized,
+	and relay this back to the pseudoterminal
 
-pageup/down doesn't work when im is on
-vim starts in vreplace mode for some reason
+	The line discipline has to happen entirely in the pseudoterminal, ptyim
+	makes sure to set the real terminal to raw mode, and restores the
+	previous settings when exiting
+
+The Input method is a simple sorted list of key sequences and outputs, searched
+through a binary search. 
+
+Encoding
+	Everything is written to be encoding agnostic, except for user input
+	which is assumed to be 8bit ascii (there aren't any encodings in use
+	today where the first 128 characters aren't ascii), but you should be
+	able to configure im.h to use any 8bit encoding for the input assuming
+	your terminal supports it.
+
+	All the encoded text should be in the input method. the boshiamy.h
+	provided is encoded in utf-8, but a custom im table using any other
+	encoding should work fine. Widths of strings are also stored in the
+	the same file.
+
+---------------------------=[Compatibility and Bugs]=---------------------------
+bash 
+	fg/bg ctrl-c ctrl-z works
+cmus, 
+vitetris
+telnet 
+	 towel.blinkenlights.nl
+ranger
+	pageup/pagedown does not work when the im is turned on
+vim 
+	If the im is turned on, it will start in vreplace mode
+------------------------------=[Acknowledgements]=------------------------------
+I would like to thank jdh8 on github for creating the ibus-table format boshiamy
+file I used to make boshiamy.h
+	https://github.com/jdh8/ibus-boshiamy
+-------------------------------=[Further Reading]=------------------------------
+https://www.linusakesson.net/programming/tty/
+	A great explanation on how ttys, pttys, sessions, groups, etc. work on
+	Linux
+man pty
+	Details on the linux pseudoterminal system
+man setsid
+	Creating a new session group/process group
 
--------------------------------=[Useful Commands]=------------------------------
-ps l
-tty
-infocmp
+man ioctl_tty
+	Linux Terminal System Calls
+	man TIOCSWINSZ
+		Setting window size
+	man TIOCSCTTY
+		Setting Controlling Terminal
+man termios
+	POSIX Terminal settings
+man console_codes
+	Terminal escape codes supported by the Linux Console, which along with
+	xterm are the de facto standard for how modern terminal emulators behave
-- 
cgit v1.1