2 Invoking Teseq

The format for running the teseq program is:

teseq options [input-file [output-file]]
teseq -h | --help
teseq -V | --version

If input-file or output-file is unspecified, or specified as ‘-’, standard input/output is used. Output is written to standard output by default, but see the -o option.

-h

--help

Print usage information on standard output and exit successfully.

-V

--version

Print the version number and licensing information for teseq on standard output and then exit successfully.

-C

For control characters from the C0 set of Ecma-48 / ISO/IEC 6429, don’t write the control-key representation, only the identifying acronym. For example, write the carriage-return/line-feed combination as

. CR LF

rather than

. CR/^M LF/^J

-D

Don’t print description lines (those beginning with ‘"’).

-E

Don’t print escape-sequence lines (beginning with ‘:’). Warning: this results in loss of information, and in particular means that running the output through the reseq command won’t reproduce the input.

Still, this option can be useful (in combination with -L) for those that don’t care about the exact sequence of characters, or what their function is called, but just what their effects in the terminal are (those that Teseq understands). The output produced will describe what happened, but not how.

-L

Don’t print identifying labels (lines beginning with ‘&’) for escape sequences.

--color[=when]

--colour[=when]

Colorize the output. WHEN defaults to ’always’ or can be ’never’ or ’auto’.

-I

--no-interactive

Don’t put the terminal into non-canonical or no-echo mode, and don’t try to ensure output lines are finished when a signal is received (see below).

-b

--buffered

Force teseq to use buffered I/O (see below).

-t timings

--timings timings

Read timing information from timings and emit delay lines. This file must be formatted as if generated by ‘script -t’ (for the script command from util-linux).

-x

No effect. Accepted for backwards compatibility.

Note that there are no options for suppressing text lines (‘|’) or control-character lines (‘.’), as there are for description or escape-sequence lines.

The -L, -D and -E options also have mnemonic equivalents of -&, -" and -: respectively, corresponding to the character prefixes for the lines they suppress; and -C has an -^ equivalent, for the ‘^X’-style control representations it suppresses. However, while they may be more practical to remember, they will be less practical to type, since both -& and -" are apt to be interpreted as special by the shell, and must be quoted with a backslash (-\& and -\") in order to pass them to the teseq command.

Interactive Mode

When teseq is started with a terminal as its input, it sets the terminal to non-canonical mode. That way, you can see real-time translation of input, as you type. If both input and output are terminals, then teseq will also turn local echo off, so that the characters you type will not interfere with the output you see. You can try it out by simply running teseq without any arguments. Note, this means that the control for indicating “end-of-file” (usually ‘C-d’) will not be processed specially, but will be passed through to teseq like any other character. Use the interrupt character (usually ‘C-c’) instead, or specify --no-interactive to disable this behavior.

When run in this way, characters typed as input are immediately translated and written out. The exception is that when an ESCAPE character is encountered, teseq must wait for the next few characters before writing anything, so it can decide whether to start an escape line or a control-character line.

When teseq has a terminal as its output, it is careful to ensure that it finishes output lines when it is stopped by a signal. If it was in the middle of writing a text line, it will write the closing pipe character ‘|’, followed by a newline. If it was in the middle of trying to determine whether it’s in a valid escape sequence or just an escape character followed by other characters, it will assume the latter case, and translate all the characters it has seen so far.

To force teseq to behave as if it’s not connected to a terminal (that is, to refrain from ensuring lines are finished, or setting non-canonical/no-echo mode), use the --no-interactive (-I) option.

The teseq program does not take care to finish lines when the output is not a terminal.

Whether or not teseq is connected to a terminal, it uses unbuffered I/O by default, unless the input is an ordinary file. This is so that each character may be processed as soon as it’s seen. However, this can result in much longer processing time overall. To force teseq to buffer its input and output, use the --buffered (-b) option.