summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorBoris Faure <billiob@gmail.com>2018-03-11 14:49:47 +0100
committerBoris Faure <billiob@gmail.com>2018-03-11 14:55:39 +0100
commit20f15e1a86e1015fb7cd43cf434ddf02083a45b5 (patch)
treeda375897793e2707b9c1d4bde3aaec3bc94445a0 /README.md
parente59b7fbd80a4a5b7863055287224642ac9428bfd (diff)
convert README to markdown
Diffstat (limited to '')
-rw-r--r--README.md331
1 files changed, 331 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8e80942
--- /dev/null
+++ b/README.md
@@ -0,0 +1,331 @@
1Terminology 1.1.1
2=================
3
4:warning: :warning: :warning:
5
6> FOR ANY ISSUES, PLEASE CONSULT THEM ON
7> http://issues.terminolo.gy/
8
9:warning: :warning: :warning:
10
11Requirements
12------------
13
14 * efl (>= 1.8.0)
15 * elementary (>= 1.8.0)
16
17Please note that some features may not quite function correctly or
18completely on EFL 1.8. Newer versions would be better.
19
20Please see http://www.enlightenment.org for information on these.
21
22This is an EFL terminal emulator with some extra bells and whistles.
23
24Compiling
25---------
26
27Once you have met requirements, compiling and installing is simple:
28
29```sh
30 meson build
31 cd build
32 ninja
33 ninja install
34```
35
36Note: to make terminology work with input methods in general you need:
37
38```sh
39 export ECORE_IMF_MODULE="xim"
40 export XMODIFIERS="@im=none"
41```
42
43
44Mouse controls
45--------------
46
47 * `Right mouse button` = controls menu
48 * `Middle mouse button` = paste highlight selection
49 * `Left mouse button/drag` = make highlight
50 * `Wheel` = scroll up or down in history
51 * `Ctrl+Wheel` = zoom font size up/down
52 * `Ctrl+Left mouse button/drag` = make block selection highlight
53
54
55Default key controls
56--------------------
57
58 * `Shift+PgUp` = Scroll 1 page up
59 * `Shift+PgDn` = Scroll 1 page down
60 * `Shift+Up` = Scroll 1 line up
61 * `Shift+Down` = Scroll 1 line down
62 * `Shift+Home` = Scroll to the top of the backlog
63 * `Shift+End` = Reset scroll
64 * `Shift+Left` = switch focus to previous terminal inside a window
65 * `Shift+Right` = switch focus to next terminal inside a window
66 * `Shift+Insert` = Paste Clipboard (`ctrl+v/c`) selection
67 * `Shift+Ctrl+Insert` = Paste Primary (highlight) selection
68 * `Shift+Keypad-Plus` = Font size up 1
69 * `Shift+Keypad-Minus` = Font size down 1
70 * `Shift+Keypad-Multiply` = Reset font size
71 * `Shift+Keypad-Divide` = Copy highlight to Clipboard (same as `Ctrl+c` in gui apps)
72 * `Ctrl+PgUp` = switch focus to previous terminal inside a window
73 * `Ctrl+PgDn` = switch focus to next terminal inside a window
74 * `Ctrl+Shift+t` = create new terminal on top of current inside window (tabs)
75 * `Ctrl+Shift+End` = close the focused terminal.
76 * `Ctrl+Shift+h` = toggle displaying the miniview of the history
77 * `Ctrl+Shift+Home` = bring up "tab" switcher
78 * `Ctrl+Shift+PgUp` = split terminal horizontally (1 term above the other)
79 * `Ctrl+Shift+PgDn` = split terminal vertically (1 term to the left of the other)
80 * `Ctrl+Shift+c` = copy current selection to clipboard
81 * `Ctrl+Shift+v` = paste current clipboard selection
82 * `Alt+Home` = Enter command mode (enter commands to control terminology itself)
83 * `Alt+Return` = Paste primary selection
84 * `Alt+g` = Group input: send input to all visible terminals in the window
85 * `Alt+Shift+g` = Group input: send input to all terminals in the window
86 * `Alt+w` = Copy selection to primary
87 * `Alt+Up` = Focus the terminal above
88 * `Alt+Down` = Focus the terminal below
89 * `Alt+Left` = Focus the terminal on the left
90 * `Alt+Right` = Focus the terminal on the right
91 * `Ctrl+Alt+Equal` = Font size up 1
92 * `Ctrl+Alt+Minus` = Font size down 1
93 * `Ctrl+Alt+0` = Reset font size
94 * `Ctrl+Alt+9` = Big font size
95 * `Ctrl+Alt+t` = Set terminal title
96 * `Ctrl+1` = switch to terminal tab 1
97 * `Ctrl+2` = switch to terminal tab 2
98 * `Ctrl+3` = switch to terminal tab 3
99 * `Ctrl+4` = switch to terminal tab 4
100 * `Ctrl+5` = switch to terminal tab 5
101 * `Ctrl+6` = switch to terminal tab 6
102 * `Ctrl+7` = switch to terminal tab 7
103 * `Ctrl+8` = switch to terminal tab 8
104 * `Ctrl+9` = switch to terminal tab 9
105 * `Ctrl+0` = switch to terminal tab 10
106
107
108
109Themes
110------
111
112Apart from the ones shipped with Terminology, themes can be stored in
113`~/.config/terminology/themes/` .
114
115
116Companion tools
117---------------
118
119Terminology ships with a set of tools to help you get the best out of
120Terminology.
121
122 * `tyls`: list directory contents with bells and whistles
123 * `tyalpha`: set transparency level of the background
124 * `tybg`: change the background image
125 * `tycat`: display inline a media file or a URI
126 * `typop`: display in a popup a media file or a URI
127 * `tyq`: queue media files or URI to be popped up
128 * `tysend`: send files to the terminal (useful through ssh)
129
130
131
132Extended escapes for terminology only
133--------------------------------------
134
135`[\033][}][COMMAND][\000]`
136i.e.
137 1. `ESC` char (`\033` or `0x1b`)
138 2. `}` char
139 3. a sequence of UTF8 chars other than `nul` (`\000` or `0x00`).
140 4. `\000` char (`nul` byte or `0x00` to indicate end of sequence)
141
142e.g.
143 `echo -n '\033}Hello world\000'`
144
145## Commands
146
147In the following, any values inside square brackets `[]` are to be replaced
148by some content (numbers, strings, paths, url's etc.).
149
150examples:
151
152 * `aa[PATH-OF-FILE]` should become something like: `aa/tmp/file.png`
153 * `aa[true/false]` should become something like: `aatrue` or `aafalse`
154
155## Available commands
156
157 * `pn[FULL-PATH-OR-URL]`
158 popup the given media file/url now
159
160 * `pq[FULL-PATH-OR-URL]`
161 queue a popup for the given media file/url
162
163 * `bt[FULL-PATH-OR-URL]`
164 set the terminal background media file/url temporarily
165
166 * `bp[FULL-PATH-OR-URL]`
167 set the terminal background media file/url permanently
168
169 * `at[on/true/yes/off/false/no]`
170 set the terminal alpha state to be on, or off temporarily
171
172 * `ap[on/true/yes/off/false/no]`
173 set the terminal alpha state to be on, or off permanently
174
175 * `qs`
176 query grid and font size. stdin will have written to it:
177 `W;H;FW;FH\n`
178 * where `W` is the width of the terminal grid in characters
179 * where `H` is the height of the terminal grid in characters
180 * where `FW` is the width of 1 character cell in pixels
181 * where `FH` is the height of 1 character cell in pixels
182
183 * `is[CW;H;FULL-PATH-OR-URL]`
184 insert _Stretched_ media (where image will stretch to fill the cell area)
185 and define expected cell area to be `W` cells wide and `H` cells high,
186 with the image/media/url.
187 * where `C` is the replace character to be identified in later text
188 * where `W` is the width in character cells (up to 511).
189 * where `H` is the height in character cells (up to 511).
190
191 note that this escape alone has no effect. It indicates a future
192 intention of inserting media into the terminal. the terminal will
193 EXPECT a grid of `WxH` _replace characters_ to follow, with each
194 sequence of such replace characters beginning with a `ib` escape command
195 and ending with an 'ie' escape command.
196
197 the `FULL-PATH-OR-URL` for all the `i` commands (`is`, `ic`, `if`, `it`)
198 may be of the form:
199 * `/full/path/to/file.png`
200 * OR `/full/path/to/link\n/full/path/to/file.png`
201 where a newline character separates a URI for a link and a full
202 path to a file to display in the region. the link is the
203 destination URI when a user may click on the given media image.
204
205 example:
206 ```sh
207 printf("\033}is#5;3;%s\000"
208 "\033}ib\000#####\033}ie\000\n"
209 "\033}ib\000#####\033}ie\000\n"
210 "\033}ib\000#####\033}ie\000\n", "/tmp/icon.png");
211 ```
212 note that `#` is the replace character, and later `#` chars if inside
213 begin/end escapes, will be replaced by the given media indicated
214 in the insert media escape.
215
216 * `ic[CW;H;FULL-PATH-OR-URL]`
217 insert _Centered_ media (centered in cell area). Otherwise parameters are
218 identical to the `is` command, but retains aspect and is padded by
219 blank space.
220
221 * `if[CW;H;FULL-PATH-OR-URL]`
222 insert _Filled_ media (fill in cell area). Otherwise parameters are
223 identical to the `is` command but ensures the entire area is
224 filled like a background even if media goes beyond cell bounds and is
225 clipped.
226
227 * `it[CW;H;FULL-PATH-OR-URL]`
228 insert _Thumb_ media (thumbnail cell area). Otherwise parameters are
229 identical to the `is` command, but uses thumbnail generation to
230 make a fast to load but low resolution version (cached) of the media.
231
232 * `it[CW;H;LINK\nFULL-PATH-OR-URL]`
233 insert _Thumb_ media with link (thumbnail cell area). Otherwise parameters
234 are identical to the `is` command, but uses thumbnail generation to
235 make a fast to load but low resolution version (cached) of the media.
236 `LINK` is a path (or url) to open _when_ the thumb is clicked on by the
237 user.
238
239 * `ij[CW;H;FULL-PATH\nGROUP][\n][cmd1][\r\n][cmd2]...`
240 insert _Edje_ object with file path given, and the group name given.
241 The command list (and the `\n` whitespace delimiter before the list)
242 is optional, but is executed/parsed before display of the actual
243 object to do things like initialize its initial state. See `iC`
244 command for more details on the command list.
245
246 Be aware that once you have an object with an assigned channel id,
247 it can send back signals and messages via escapes on stdin. These
248 escapes will follow terminology extended escape format
249 `(ESC + } ... \000)`, and the content will be one of:
250
251 * `;CHID\ndrag\nPART NAME\nVAL1\nVAL2`
252 * `;CHID\ndrag,start\nPART NAME\nVAL1\nVAL2`
253 * `;CHID\ndrag,stop\nPART NAME\nVAL1\nVAL2`
254 * `;CHID\ndrag,step\nPART NAME\nVAL1\nVAL2`
255 * `;CHID\drag,set\nPART NAME\nVAL1\nVAL2`
256 * `signal;CHID\nSIGNAL STRING\nSOURCE STRING`
257 * `message;CHID\nOPCODE ID\nstring\nSTRING1`
258 * `message;CHID\nOPCODE ID\nint\nINT1`
259 * `message;CHID\nOPCODE ID\nfloat\nFLOAT1`
260 * `message;CHID\nOPCODE ID\nstring_set\nSTRING1\nSTRING2\nSTRING3...`
261 * `message;CHID\nOPCODE ID\nint_set\nINT1\nINT2\nINT3...`
262 * `message;CHID\nOPCODE ID\nfloat_set\nFLOAT1\nFLOAT2\nFLOAT3...`
263 * `message;CHID\nOPCODE ID\nstring_int\nSTRING1\nINT1`
264 * `message;CHID\nOPCODE ID\nstring_float\nSTRING1\nFLOAT1`
265 * `message;CHID\nOPCODE ID\nstring_int_set\nSTRING1\nINT1\nINT2\nINT3...`
266 * `message;CHID\nOPCODE ID\nstring_float_set\nSTRING1\nFLOAT1\nFLOAT2\nFLOAT3...`
267
268 * `iC[CHID]\n[cmd1][\r\n][cmd2][\r\n][cmd3]...`
269 send a _Command_ (`cmd1`, `cmd2`, `cmd3` etc.) to an existing named
270 channel id `CHID`. this can be a list of 1 or more command strings,
271 with each string broken by a continuous sequence of 1 or more `\r`
272 and/or `\n` characters. e.g. `\n`, `\r`, `\r\n`, `\n\r`,
273 `\n\r\n\n\n`, etc.
274
275 commands understood are:
276
277 * `text\nPART NAME\nTEXT STRING`
278 set the text of `PART NAME` to string `TEXT STRING`
279 * `emit\nSIGNAL STRING\nSOURCE STRING`
280 emit signal `SIGNAL STRING` `SOURCE STRING`
281 * `drag\nPART NAME\n[value|size|step|page]\nVAL1\nVAL2`
282 manipulate dragable of name `PART NAME` and either set `value`,
283 `size`, `step` or `page` properties to `VAL1` and `VAL2` for `x`
284 and `y`, where `VAL1` and `VAL2` are floating point values
285 * `chid\nCHANNEL ID`
286 set the channel id of a given edje object (only valid in setup
287 commands for the inline edje object) to `CHANNEL ID` so it can
288 be addressed later.
289 * `message\nOPCODE ID\n[string|int|float|string_set|int_set|...`
290 `float_set|string|int|string_float|string_int_set|...`
291 `string_float_set]\n[message data]`
292 send a message with opcode (integer) id `OPCODE ID` of one of
293 the given types supported (`string`, `int`, `float`, etc.) and
294 then with the given `message data` at the end.
295 `message data` format depends on message type:
296 * `string`: `STRING1`
297 * `int`: `INT1`
298 * `float`: `FLOAT1`
299 * `string_set`: `STRING1\nSTRING2\nSTRING3...`
300 * `int_set`: `INT1\nINT2\nINT3...`
301 * `float_set`: `FLOAT1\nFLOAT2\nFLOAT3...`
302 * `string_int`: `STRING1\nINT1`
303 * `string_float`: `STRING1\nFLOAT1`
304 * `string_int_set`: `STRING1\nINT1\nINT2\nINT3...`
305 * `string_float_set`: `STRING1\nFLOAT1\nFLOAT2\nFLOAT3...`
306
307 * `ib`
308 begin media replace sequence run
309
310 * `ie`
311 end media replace sequence run
312
313 * `fr[PATH/FILE]`
314 begin file send for a file named `PATH` / `FILE`
315
316 * `fs[SIZE_BYTES]`
317 set the size in bytes of a file send started with the above fr escape
318
319 * `fd[CHECKSUM DATA]`
320 block of data for the current file transfer with checksum as a
321 string decimal which is the sum of every byte when taken as an
322 unsigned char per byte. the checksum is a signed 32bit integer.
323 the checksum is the sum of the data after escaping. 4 bits at a
324 time per data byte, encoded with high bits in one byte then low
325 bits, with the bits encoded as 4 bit value being `0x40` + 4 bit value
326 per byte. `(@ == 0x0, A == 0x1, B == 0x2, ... N == 0xe, O == 0xf)`.
327 so to rebuild a byte will be `(((bytes[0] - 0x40) & 0xf) << 4) | ((bytes[1] - 0x40) & 0xf)` per byte pair in the data block.
328
329 * `fx`
330 exit file send mode (normally at the end of the file or when it's
331 complete)