| blob | 0e43c0d33901ad2268e43cd573af387f03cce991 |
1 Ketmar's YTERM -- emulator of a terminal emulator
2 =================================================
4 YTERM emulates a proper terminal emulator with tab support.
5 It implements small subset of the real terminal emulation,
6 enough to run most console software. Many features are not
7 implemented, and will never be implemented because the author
8 doesn't need them.
10 YTERM uses "rxvt" $TERM setting, but it supports 256 colors.
11 So it may be better to use "rxvt-256", but meh... RGB color
12 support is there too (but you cannot detect it via DCS yet).
14 Keyboard --> ESC sequences translation is hardcoded. There is
15 no way to change what, for example, F1 key will send without
16 changing the source code and recompiling YTERM. This is not an
17 oversight.
19 Options set in config may be changed on the fly. You can send
20 SIGHUP to trigger config reloading (or use built-in menu).
22 You need X server session with 24 or 32 BPP to run YTERM. The
23 code doesn't try to allocate colors from X server, it is using
24 hardcoded RGB values. That is, your X server is better have the
25 same color encoding as mine (which is likely true for X.org).
27 YTERM supports only UTF and KOI locales. Locale autodetection
28 is very simplistic, but it works for me.
30 Renderer will try to update only changed screen cells, and will
31 use `XCopyArea()` to implement scrolling, if possible.
34 Building and installing
35 -----------------------
37 Use "sh 0build.sh" command to build the binary. You will need
38 pkg-config and xlib. And there is no command to install YTERM,
39 because you can copy the binary wherever you want. Also, only
40 GNU/Linux is supported, other OSes may, or may not work. Deal
41 with it.
44 Some techincal/implementation details
45 -------------------------------------
47 It is almost impossible to implement a proper terminal emulator
48 without diving into DEC VT manuals. And you cannot read one of
49 them and be happy, because various details are scattered across
50 different documents, and sometimes even erratas. But tbh, I don't
51 care about proper VT hardware emulation, I only need enough of it
52 to make most console software usable.
54 It would be much easier if there would be proper specs for emulator
55 implementors, but alas. Various escape code descriptions are vague,
56 and cannot be used as specs. Take, for example, "set scroll region"
57 command: what should happen with cursor position after setting the
58 region? What we should do on receiving invalid arguments? What
59 happens if cursor is outside of a region? And so on, so on...
60 Similar questions could be asked about almost any control sequence.
61 And xterm specific sequences are even worser, especially those for
62 switching to alt screen and back. (Wich attributes should be saved?)
64 So I decided to implement the things "as I feel right", and then
65 test with several console programs I am using. Everything seems to
66 work, therefore I happy. The implementation may be wrong, but it
67 doesn't really matter.
69 Also, I decided to skip implementing various features nobody's using
70 anymore, like switching to application keypad mode. Don't do that,
71 don't use that. Support for double-width and double-height characters
72 is missing too, and only limited support for pseudographics charset
73 is implemented. Many other obscure or rarely used features are not
74 implemented.
76 That is, stick to the minimal feature set, and assume nothing, and
77 you'll be fine. This is true not only for YTERM, but for any other
78 terminal emulator out there. Testing your software only in xterm
79 doesn't mean that it will work with other emulators.
82 Using X11 clipboard
83 -------------------
85 You will need to install xsel[0] to use X11 clipboard in YTERM. I am
86 too lazy to implement clipboard protocols myself, and tbh, I see no
87 reason in doing so. Besides, using xsel has another advantage: your
88 copied data will not disappear when you close YTERM. Yes, I am too
89 dumb to implement X selection protocol properly. Deal with it.
91 Actually, I included "xsel" into the source code tree. You can use
92 "yterm xsel ..." to run in "xsel mode". It is used for selections now.
95 Copying text from terminal
96 --------------------------
98 As I hate using mouse for this, copying with the mouse is... Oh, you've
99 guessed it: not implemented! Instead, I introduced "selection mode", in
100 which you can select vertical, rectangular, or sequential area, and copy
101 it to X11 clipboard. This mode is also a history viewer. There are no
102 special keys to view scrollback history outside of selection mode.
104 Default key to activate selection mode is Alt+Space. The tab will
105 become "amber", and you can select blocks now. Use F3 to start stream
106 block (and F3 again to end it), Shift+F3 to start rectangular block,
107 and Alt+F3 to start line block. You can change block type by pressing
108 "s" for stream, "l" for line, and "r" for rectangular. Default keys to
109 copy marked block are listed in config.
111 Additionally, you can emulate mouse clicks from selection mode. If there
112 is no selected block, pressing Enter will perfrom a left click, and
113 Ctrl+Enter will perform a double click. There is no way to emulate other
114 mouse buttons.
116 If you will also hold "Shift" while pressing Enter, YTERM will not leave
117 selection mode after sending mouse events. It may be handy when you need
118 to perform several clicks. But note that screen output is disabled while
119 you're in selection mode. Everything the app is trying to write to the
120 terminal will appear "instantly" after you leave the selection mode.
122 It is also possible to view history in this mode. Simply move the cursor
123 up. You can also use Page Up/Page Down. Holding "Alt" will scroll the
124 history without moving the cursor.
126 Note that program output is frozen while you are in selection mode, so
127 don't leave the tab in this mode for a long time.
130 Notes about scrollback history
131 ------------------------------
133 Scrollback history doesn't occupy any RAM. YTERM writes all history to
134 nameless temporary files, and reads only the part it needs for rendering.
135 Most of the time you don't need no history, so there is little reason to
136 keep it in RAM.
138 There is one little trick (or gotcha) which can be used to clear history
139 buffer: turn history off in the built-in menu, and then on again. This
140 will delete old history file, and create a new one.
142 Also, history will not survive hotswap.
145 Mouse support
146 -------------
148 Mouse support is disabled by default, and you'd better leave it disabled.
149 I am not using it, and that mode is not properly tested. And yeah, you
150 cannot use mouse to select tabs. This is not a bug, I deliberately wrote
151 the code this way. Deal with it.
154 Xft support
155 -----------
157 There is no Xft support, and I have no plans to implement it. The only
158 usable font for terminals (Terminus) is bitmap anyway. Besides, Xft is
159 a fuckin' mess, and it is defective by design.
162 Newer GCC support
163 -----------------
165 Recent GCC versions (anything above 6) are broken. Compiler warnings
166 are more and more useless, GCC warns about legitimate function using.
167 Just look at shit GCC vomited with yterm: I used `snprintf()` *exactly*
168 because it will truncate the string, so it will fit in the buffer. But
169 GCC authors are morons, and they are sure that it is wrong to use
170 `snprintf()` the way it was designed.
172 That is, I will not silence this warning (and any other idiotic warnings
173 newer GCC versions may vomit). This is compiler bug, introduced by idiots.
174 The only way to fix it is to remove idiots from GCC project, and undo all
175 damage they've done. Write to GCC bugzilla if want your good GCC back.
178 -------------------------------
179 Signed,
180 Ketmar Dark // Invisible Vector
183 [0] https://vergenet.net/~conrad/software/xsel/