Sun Jun 2 20:25:55 2002 Michael Jennings (mej)

Oops, missed these.


SVN revision: 6298

2 files changed, 256 insertions, 92 deletions

diff --git a/doc/README.Escreen b/doc/README.Escreen
index 62a2d60..4d5d7af 100644
--- a/doc/README.Escreen
+++ b/doc/README.Escreen
@@ -1,100 +1,197 @@
 
-ESCREEN
 
-1 - What is it?
+ _____ _    ___          _____                              
+|  ___/ \  / _ \   _ _  | ____|___  ___ _ __ ___  ___ _ __  
+| |_ / _ \| | | | (_|_) |  _| / __|/ __| '__/ _ \/ _ \ '_ \ 
+|  _/ ___ \ |_| |  _ _  | |___\__ \ (__| | |  __/  __/ | | |
+|_|/_/   \_\__\_\ (_|_) |_____|___/\___|_|  \___|\___|_| |_|
+                                                            
+Frequently Asked Questions about the Eterm "Escreen" extension
 
-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.
+------------------------------------------------------------------------------
 
 
 
-2 - How do I get it?
+   BEFORE INSTALLING IT
 
-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 is it?
 
-3 - How do I start 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...
 
-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.
+     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.
 
 
-4 - What should I expect from it?  (subject to change)
 
-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.
+Q  How do I get it?
 
-* .screenrc, $SCREENRC, [/usr/local]/etc/screenrc and $SYSSCREENRC are
-  supported.
+A  You already have it.
 
-* Eterm-buttons are supported (left click on display-name to activate
-  the display, middle to close it, right to rename it).
+     ./configure --enable-escreen && make && make install
 
-* Sending statements to screen (^A: in the default setup) with
-  tab-completion
+   Oh, and you also need the screen program.  In our tests, we used
+   Screen version 3.09.11 (FAU) 14-Feb-02.
 
-* 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
+Q  What should I expect from it?  (subject to change)
 
-* support for SSH-tunneling through firewalls
+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).
 
-5 - What's new?
+*  Sending statements to screen (^A: in the default setup) with
+   tab-completion
 
-* Entering and exiting copy mode no longer produces a dialog box.
-  Just too bloody annoying, that.
+*  support for screen command-line options:
+   Eterm -U screen://localhost/-xRR+-c~/.screenrc.testing
 
-* SCREENRC, SYSSCREENRC, .../etc/screenrc support (thanks mej)
+*  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)
 
-* Easy-to-remember key-layout (optional, see below)
+*  alert boxes for messages from screen
 
-* Comes up much faster
+*  support for SSH-tunneling through firewalls
 
-* You can pass arbitrary paramters to screen/scream now
+*  Easy-to-remember key-layout (optional, see below)
 
+*  You can pass arbitrary paramters to screen/scream
 
 
-6 - 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.  There will likely be limited
-  support for screen (we need to keep this, it will be what we'll find
-  on remote machine), and possibly support for enhanced screen-clones
-  (like the perchance forthcoming "scream").
+Q  What's new?
 
+*  Dialog boxes now longer block the entire GUI (only Eterm's).
+
+*  Display-closing has a dialog-box now.
+
+*  Code clean-up.  It's actually understandable now.
+   (You can also compile libscream w/o support for screen now. : )
+
+*  Logs debug info through libast now if it available
+
+*  Fix for scrollbar (reported by mej).
+
+*  Fix for remote sessions with no corresponding local user
+   (reported by tfing).
+
+*  Tear-off tabs.  You can select the button-representation of a
+   display and drag-and-drop it
+
+   - 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.
+
+*  Possibly support for enhanced screen-clones (like the perchance
+   forthcoming "scream").
+
+
+
+------------------------------------------------------------------------------
+
+
+
+   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 stops 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.
 
 
-9 - FAQ
 
 Q  ^A does funny things!
 
@@ -108,6 +205,8 @@ A  Well, yes.  ^A talks to the screen program.  Put a line
                statements like "escape ^Uu"; trying things out will be
                easier that way.  yes, it 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
@@ -115,12 +214,16 @@ A  You probably already  have changed the magic escape key to something
    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 bindings?
+   to remember key-bindings?
 
 A  Sure.  Eterm is The Configurable Terminal, after all.  A pret-a-porter
-   example that you can simply add to your theme.cfg file (or %include
-   from it) lives in escreen.cfg -- enjoy.
+   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?
@@ -131,30 +234,91 @@ A  You can always override the escapes like so:
 
    Where ^X is the escape and y the literal (man screen).
 
-Q  I don't see any buttons when I connect to a remote screen!
 
-A  Some Debian-users reported this before, and it is presumed to be a
-   problem with the terminfo-data.  Call up Eterm (or xterm, or whatnot).
-   *Then* call up "screen" from inside that terminal.  Is the last line
-   inverted?  If it isn't, something is seriously weird with your setup,
-   and it's not a problem in Escreen.  Sorry.  : (
-   2002/05/13  rewritten code should handle most of these cases
-   2002/05/18  rewritten code should handle even more of these cases : )
 
-Q  Escreen opens, then closes again.
+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 "-xRR".  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/-r"
+
+   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.
+
 
-A  Escreen cannot run "screen".  If you do have "screen", and it is in
-   the search path, screen apparently terminates right away.  Normally
-   this means that your screen-sessions are messed up; "screen -ls" will
-   give you a list of them; "screen -wipe" will do the cleaning up.
-   If this happens with a remote session, 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 -Z option accordingly (cf man Eterm).
+   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.
 
@@ -162,21 +326,15 @@ 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  What's with the licence changing?
 
-A  I wrongly assumed that Eterm was GPL'd rather than BSD'd, so I stuck
-   a GPL on the first alpha.  To correct this mistake, the licence was
-   changed.  In an attempt to honour both the convictions of the authors
-   of Eterm (BSD licence) and those of screen (GPL) which Escreen tries
-   to bring together, it appears that the licensing of Escreen should
-   land somewhere in the middle; therefore, I nominally chose LGPL.
-   This may be softened to BSD at a later date.
 
 Q  Who's responsible for this?
 
@@ -186,5 +344,11 @@ A  Escreen is an Eterm extension conceived and written by Azundris.
    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/13  <scream@azundris.com>  http://www.azundris.com/
+-- Azundris 2002/05/23  <scream@azundris.com>  http://www.azundris.com/
diff --git a/doc/escreen.cfg b/doc/escreen.cfg
index ec6b43b..07655a1 100644
--- a/doc/escreen.cfg
+++ b/doc/escreen.cfg
@@ -8,7 +8,7 @@
   # See "man Eterm" for more information.
   # 2002/05/19  Azundris  <scream@azundris.com>
 
-  # CONTROL VARIETY #########################################################
+  # CONTROL VARIETY ############################################################
 
   # ctrl-left -> previous display, ctrl-right -> next display
   bind ctrl Left to echo ^Ap
@@ -35,7 +35,7 @@
   bind ctrl 0x39 to echo ^A8
   bind ctrl 0x30 to echo ^A9
 
-  # ALT VARIETY #############################################################
+  # ALT VARIETY ################################################################
 
   # alt-left -> previous display, alt-right -> next display
   bind alt Left to echo ^Ap
@@ -63,7 +63,7 @@
   bind alt 0x39 to echo ^A8
   bind alt 0x30 to echo ^A9
 
-  # FUNCTION KEYS ###########################################################
+  # FUNCTION KEYS ##############################################################
 
   # F1..F10 -> display_0..display_9
   bind F1 to echo ^A0
@@ -80,7 +80,7 @@
   # alt F4 -> close display
   bind alt F4 to echo ^Ak
 
-  # MISC STUFF ##############################################################
+  # MISC STUFF #################################################################
 
   # DISPLAY
 
@@ -129,4 +129,4 @@
 
 
 
-  # ENDS ####################################################################
+  # ENDS #######################################################################