_____ _    ___          _____
|  ___/ \  / _ \   _ _  | ____|___  ___ _ __ ___  ___ _ __
| |_ / _ \| | | | (_|_) |  _| / __|/ __| '__/ _ \/ _ \ '_ \
|  _/ ___ \ |_| |  _ _  | |___\__ \ (__| | |  __/  __/ | | |
|_|/_/   \_\__\_\ (_|_) |_____|___/\___|_|  \___|\___|_| |_|

Frequently Asked Questions about the "Escreen/Etwin" extension



------------------------------------------------------------------------------



   BEFORE INSTALLING IT



Q  What is it?

A  Eterm now offers you to compile in experimental support for the
   "screen" program.  "screen" is a terminal multiplexer (one window,
   several shells).  Yes, it's like konsole or multi-gnome-terminal,
   only that your shells won't die just because X or the Window Manager
   do.  Oh, and you can pick up your home session from work, and vice
   versa.  And several people can connect to the same session at once,
   and...

     You get this picture -- if you're a power-user, this is for you.

   Also, if you're not a power-user, this is *not* for you.  It's alpha.
   It's experimental.  Reported bugs will get fixed where possible, but
   there can be no newbie support at this time.



Q  How do I get it?

A  You already have it.

     ./configure --enable-escreen && make && make install

   Oh, and you also need the screen program.  In our tests, we used
   Screen version 3.09.11 (FAU) 14-Feb-02.



Q  What should I expect from it?  (subject to change)

A  An Eterm should open with a screen (without a status-line) running
   inside of it.  There should be a button-bar in the Eterm enumerating
   the multiplexed terminal (you usually start with one), and button with
   a menu of screen-related actions.  If you normally don't use a button-bar,
   Escreen will create one for you.  Otherwise, it will add buttons to your
   existing bar.

*  .screenrc, $SCREENRC, [/usr/local]/etc/screenrc and $SYSSCREENRC are
   supported.  To a point.  If something doesn't work, try things without
   the screenrc.  If it works then, find the offending line in the screenrc
   and send it to me if you'd like a fix.  Thankyou.

*  Eterm-buttons are supported (left click on display-name to activate
   the display, middle to close it, right to rename it).

*  Sending statements to screen (^A: in the default setup) with
   tab-completion

*  support for screen command-line options:
   Eterm -U screen://localhost/-xRR+-c~/.screenrc.testing

*  menu for "screen"-functions (if you add your own, use ^A as the
   escape-character in the ECHO action; Escreen will remap it to
   whatever is actually used in the session)

*  alert boxes for messages from screen

*  support for SSH-tunneling through firewalls

*  Easy-to-remember key-layout (optional, see below)

*  You can pass arbitrary paramters to screen/scream



Q  What's new?

*  Should work with Debian Unstable now (2002/10/03)

*  libscream's functions are available through Eterm's scripting
   facility.  See escreen.cfg for an example.

*  Preliminary Twin support. For now, Twin-URLs (Eterm -U twin://)
   and Twin's mouse-protocol are supported, allowing you start twin
   within Eterm (making it the only terminal emulator to support Twin,
   AFAIK).  Next release should feature Twin support through libscream
   (thus exposing Twin to button- and key-bindings through Eterm's
   scripting interface).

   For more information on Twin see
   http://freshmeat.net/projects/twin/?topic_id=158

*  Tear-off tabs.  You can select the button-representation of a
   display and drag-and-drop it [currently under reconstruction]

   - to another button:

     The display is moved to that position; the dragged-to display
     and all displays following it each move one slot to the right.
     (Yes, a swap may occur rather than an insert, cause that's what
     screen does.  We'll provide a work-around with the next version.)

   - to the desktop:

     This opens another Escreen window (selecting the dragged session
     where possible).  This is very alpha and not intended for productive
     use (yet).



Q  What should I expect in the future?  (TODO)

*  Limited support for scrolling.  screen doesn't give us all the info
   we'd need to make this really sexy.



------------------------------------------------------------------------------



   AFTER INSTALLING IT



Q  How do I start it?

A  If you call it an Eterm, it will behave like one.  Same for an Escreen.
   (you'd have to symlink from Escreen to Eterm first, of course).
   Additionally, when called with a command-line (-e "/some/program"), the
   suite will *always* behave like an Eterm, even if invoked as Escreen.
   Likewise, when called with an URL (-U screen://user@some.host.gov/),
   it will behave like an Escreen, even if invoked under another name.



Q  Something is amiss!  Moan, moan, complain, complain!

A  Before you complain:

*  Take a deep breath, remember you didn't pay for this.

*  Check whether you are using the latest version.  Support for each
   version ceases with the release of a new one!

*  Read all of the FAQ, your question may be answered in there.
   Remember that the FAQ grows with almost each release, so re-reading
   it with each release is a good idea.  Gives you something to do while
   compiling, too.  Also see the manual page for Eterm, and that for screen.

*  Check whether the problem only occurs when using your screenrc
   (see below).

*  If remote sessions break, check whether terminfo isn't broken on the
   remote machine.

*  Send a detailed bug-report.  Often, it will not be possible to reproduce
   the bug on my set, so I'll need the info from yours.  This includes your
   screenrc.  Sometimes tracing the problem will only be possible if you send
   me Escreen's debug output.  To get it, #define NS_DEBUG in screamcfg.h
   and recompile.

*  If you send a usable bug-report, you will normally receive a free fix,
   or at least an explanation why there will be no fix.  If on the other
   hand you asked something that's explained in this FAQ, we will laugh
   at you and THEN be rude.  Sorry, but you already got free code, a free
   FAQ, and, in many cases, free support.  Wasting my time with questions
   I already answered is not a welcome response to this generosity.



Q  Creating a new screen takes forever!?  (While connecting to an
   existing one doesn't?)

A  It's the price of making things compatible with stupid screen.  To
   disable compatibility mode for local connections, pass -z 0 to Eterm
   on the command line.  (This has no effect on remote sessions!)
   Depending on your setup, -z 0 will either make creating new screens
   much faster, or not work at all for you.  Good luck.



Q  ^A does funny things!

A  Well, yes.  ^A talks to the screen program.  Put a line
   like "escape ^Aa" in "~/.screenrc".  The example declares
   Control-A (^A) to be the magic key (and ^A-a what you need
   to press to send the escape (^A in the example) to the application
   instead); you'll want to put something else to move it around.
   See "man screen" for details.

   Note that ^A: opens a buffer where you can directly enter
   statements like "escape ^Uu"; trying things out will be
   easier that way.  Yes, it the magic key will be ^U: afterwards. ; )



Q  I typed ^A and it *doesn't do* funny things!

A  You probably already  have changed the magic escape key to something
   other than ^A (on the command-line, within Escreen, or in .screenrc).
   Er, you *did* hold Control, then press A, rather then typing a ^ and
   an A, right?



Q  But I don't like all this control-whatever stuff, can I have easier
   to remember key-bindings?

A  Sure.  Eterm is The Configurable Terminal, after all.  A pret-a-porter
   example that you can simply add to the action context of your theme.cfg
   file (or %include from it) lives in escreen.cfg -- enjoy.



Q  Escreen changes the escape on the remote box to the same thing as on
   the local box, does it have to?

A  You can always override the escapes like so:

     Eterm -U screen://user@host.com/-e^Xy

   Where ^X is the escape and y the literal (man screen).



Q  Escreen only creates a new session when there is none; otherwise,
   it connects to the existing one!

A  It's not a bug, it's a feature. : )  The default parameters for
   the screen Escreen starts are "-RDD".  You can override those by
   putting your own parameters in the URL

     Eterm -U "protocol://user@host:port/screen_parameters"

   like so:

     Eterm -U "screen://foo@bar.com/-xRR"

   or, for a local screen with no parameters:

     Eterm -U "localhost/ "   # which is the same as
     Eterm -U "/ "            # which is the same as
     Eterm -U /+



Q  Escreen complains about stuff in my .screenrc!

A  If it works aside from that, ignore the machine.  If it doesn't, try
   things without the screenrc.  If it works then, find the offending
   line in the screenrc and send it to me if you'd like a fix.  Thankyou.



Q  When Escreen connects to an existing session, things don't work.
   They do otherwise.

A  In all likelihood you're not using the same .screenrc when picking
   up the session that you used when creating it.  If it's just a matter
   of the escapes being different, you can tell the front-end which ones
   the backend uses either by providing the right screenrc, or by setting
   them on the command-line:

     Eterm -U "/-e^Xy"

   Where ^X is the escape-character, and y the literal.  Replace as needed.
   See "man screen" for more info on escapes.



Q  I don't see any buttons when I run Escreen (Eterm -U "")!

A  Escreen could not set up screen in a decent way.  Don't use -z 0.
   Try it without the screenrc interfering.  If this only happens when
   picking up a session, see above.



Q  Escreen opens, then closes again (with a local session).

A  Escreen cannot run "screen".  If you do have "screen", and it is in the
   search path, screen apparently terminates right away.  Normally
   this is a session-problem:  there are several sessions, and Escreen
   doesn't know which one to pick up, or all sessions are "dead"
   (unreachable).

   screen -ls                   will give you a list of the sessions;
   screen -wipe                 will remove dead sessions;
   Eterm -U "/-r session_name"  will pick up the session named session_name.



Q  Escreen opens, then closes again (with a remote session).

   If it's not one of the problems described above, the remote end might
   just find your terminal type confusing.  The "--term-name" option with
   something vanilla (--term-name vt100) should remedy this.



Q  Escreen works, except when I use -Z to tunnel through a firewall?

A  Try to manually ssh to the firewall, see how long that takes.  Then,
   tune the delay in the -Z option accordingly (cf man Eterm):

     Eterm -U ... -Z "localport:firewall:remoteport,delay"



Q  I'd like for the button labels to be in a different colour.

A  At this time, the labels follow the general (text) colours.
   You will be able to define colours for (foreground|background|active|bell)
   windows' labels in later releases.



Q "screen" support rocks!  Can we have it in konsole/multi-gnome-terminal?

A  I will not attempt anything like that before I am happy with Escreen.
   The code, however, is LGPL'd, and its use is documented by example of
   Eterm (grep for ESCREEN).  If you can work with that, do.



Q  Who's responsible for this?

A  Escreen is an Eterm extension conceived and written by Azundris.
   Do not complain to KainX (who courteously added the patch for the
   enjoyment of the hardy) if you break your Eterm by compiling this
   in (or by trying to use the alpha-functionality).  By using this,
   you agree that anything happening while or because of using it is
   your fault, and your fault only.
   Unfortunately, screen is poorly coded, and a bummer to support.

   Someone (perhaps this kitty) may at some point provide a better
   backend, but since we cannot expect that backend on our every
   client's machine, we'll still need to support GNU screen, much
   as we may hate its protocol (or lack thereof, really).

-- Azundris 2002/05/23  <scream@azundris.com>  http://www.azundris.com/