diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 124 |
1 files changed, 103 insertions, 21 deletions
@@ -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 |