From 861146c7349fed1077f63ed29703195b31e79645 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Wed, 23 Oct 2019 03:45:12 -0400 Subject: add troubleshooting section --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 913f782..c797841 100644 --- a/README.md +++ b/README.md @@ -206,6 +206,40 @@ methods are required to use `http://localhost:44141` as their redirect URL. * Name of the TTYrec file to save to or read from. * Default: `teleterm.ttyrec` +## Troubleshooting + +### I'm trying to watch someone and the output is a garbled mess! + +There are three main causes of this: + +1. *Your local terminal size is not the same as the terminal size of the person + streaming.* A smaller terminal will almost definitely cause problems here + (and the `tt watch` menu will display the terminal size in red if this is + the case), but a terminal which is too large can also occasionally cause + issues if the person is running a full-screen application that relies on the + details of the terminal's line wrapping behavior. +2. *Your terminal type is incompatible with the terminal type of the person + streaming.* Different terminals use different escape sequences to represent + various behavior (such as moving the cursor or clearing the screen) and + while many of these are shared across terminals, many also aren't. In this + case, you should switch to using a terminal which is compatible. Note that + `screen` or `tmux` counts as a terminal in this sense, and so an easy fix + here is often to just always run `tt` inside a `screen` or `tmux` session, + both when streaming and watching (and convincing the person you're watching + to do the same). +3. *The person you are watching has produced a large amount of terminal output + without clearing their screen.* Terminal output is determined by a sequence + of drawing commands (issued via escape sequences) starting from a blank + terminal, and this means that, depending on the output, it can require an + arbitrarily large amount of data to recreate the current terminal + accurately. `teleterm` puts a limit on the amount of data to save, however + (to avoid running out of memory), and so long sequences of output without + screen clears can cause display corruption. This can be fixed by just asking + the streamer to clear their screen (either by running `reset` or `clear` + from the command line, or by using the redraw functionality of the + application they are running, typically bound to something like `^L` or + `^R`). + ## Contributing I'm very interested in contributions! I have a list of todo items in this -- cgit v1.2.3-54-g00ecf