Here's a list of problems you might encounter. There usually isn't a
satisfactory solution, but at least you won't live in ignorance.

1. Terminal emulator doesn't set WINDOWID

  Most terminal emulators set that environment variable for you. It
  contains a number which uniquely identifies terminal's X window.
  Slrnface needs it to know which window the terminal emulator is using
  and cannot operate without this information.

  If your terminal emulator doesn't set this variable, you're out of luck.
  You can set it manually, but it's a cumbersome procedure:

  a) Start "xwininfo"
  b) Click somewhere in the terminal window
  c) You'll get several lines of output. The first one will be something
     like:

     xwininfo: Window id: 0x900003 "xterm"

     That's your window identifier. Put it in the environment variable.
     For sh compatible shells:

     WINDOWID=0x900003; export WINDOWID

     For csh compatible shells:

     setenv WINDOWID 0x900003

  Slrnface should be happy now, but I suppose this isn't a procedure you'd
  like to execute often. You might try to upgrade to the newer version of
  the terminal emulator, if there is one, in hope that it got this
  feature. If that proves to be futile, the only remaining option is to
  use another terminal emulator.

2. WINDOWID is not forwarded along telnet/rlogin/ssh/whatever session

  For a start, read the documentation for your client program. It might
  have an option to forward environment variables. For example, some
  telnet clients can be asked to do that in ~/.telnetrc file.

  If your client has this feature and you've told it to use it, but it
  still doesn't work, perhaps the server doesn't support it. In that case
  you're out of luck.

  Most notably, OpenSSH cannot forward environment variables. You might
  try to do something like:

  ssh -t user@remotehost "export TERM=$TERM; export WINDOWID=$WINDOWID; slrn"

  but that will only start a remote slrn session, not the shell session.

  You might get around the problem if you write a wrapper for your
  communication command. Since most of the communication protocols and
  tools support forwarding the TERM variable, you could overload it with
  the WINDOWID info. For example, the wrapper could set it to
  $WINDOWID::$TERM before invoking the real command. Then your shell
  startup script on the server side should check if the TERM variable
  contains "::", and if so, initialize both WINDOWID and TERM to the
  proper components. It's messy, but it works.

  And, of course, you could mail OpenSSH folks and nicely ask them to
  do something about environment variable forwarding.

3. X resources don't have any effect

  It could be a bug in slrnface or it could be a buggy terminal emulator.
  Slrnface is somewhat equipped to work around problematic terminals, but
  the support is far from ideal. The problem comes from the way certain
  terminals identify themselves to the X Window system. To check if your
  terminal has a problem, execute:

  xprop | grep WM_CLASS

  and click on the terminal window. You might get something like:

  WM_CLASS(STRING) = "Eterm 0.9.2", "Eterm"

  The dot in any of those strings is a problem. X resources use dots (as
  well as stars and question marks) as separators between fields. When
  slrnface asks for a resource property, it first constructs the full
  resource name from the name which terminal window has registered with
  the window system and the property name its interested in. So with the
  above example, the full name might be "Eterm 0.9.2.slrnface.xOffsetChar".
  Then it calls certain X function which retrieves the value. But the poor
  X function is utterly confused with this and usually won't return a
  match, no matter what you try to do.

  Even worse are terminal emulators which can open several windows from a
  single process, but then they give them different names, such as
  "Terminal.0", "Terminal.1" and so on.

  In case when X resource matching function doesn't return a match,
  slrnface will take a look at the command line arguments and use the
  values set there[1]. That might be good enough for you. If you're using
  slrnface with slrn, you can just edit the S-Lang script and add command
  line options for the slrnface invocation. If you want to make it work
  with different broken terminals, you'll have to read them from a file, I
  suppose. In case you are using slrnface with mutt, you'll have to edit
  the mutt patch and recompile mutt.

  In any case, don't forget to send the bug report the the terminal
  maintainers.

  [1] Normally, that same X function takes care of the command line
      arguments too, so X applications don't have to process them, but the
      poor function gets so much confused with this business that it
      completely ignores them. So slrnface code base had to grow somewhat.

4. slrn and slrnface don't agree about color shades

  Suppose you configured slrn to show certain kind of text in red and you
  configured slrnface to paint X-Faces in red. Chances are that those two
  red colors won't look the same. Almost, but not quite.

  Color terminals usually have 8 or 16 colors. There is no good reason for
  this limitation and terminfo capability base provides ways for a terminal
  to advertise most of the features you can think of, but most terminal
  emulators just don't implement nice features.

  Sometimes users can configure the colors, but not always. When you can
  configure them, it's usually by using X resources or by storing the
  values in some file. If you don't configure them, the terminal will use
  hard-coded fallback values.

  If the color values are in a file, slrnface has no way to know which
  file and what the format might be. If the X resources are used, slrnface
  has no way to know the names of those resources. If the user hasn't
  configured anything, slrnface has no way to know which defaults were
  used when the terminal application was compiled.

  So slrnface cannot adjust itself to the terminal. Instead, slrnface is
  using the color database which is supposed to be used by all X
  applications. The mapping from color names to RGB values is usually
  stored in a file called rgb.txt[2], somewhere in your X directories. X
  server knows where it is and all applications are supposed to ask X
  server about the mapping, so all applications should show the same shade
  when the user asks for "red".
  
  If you can configure the colors used by your terminal, you have a good
  chance that "red" will mean the same shade it means to slrnface. If you
  keep using the defaults, tough luck.

  [2] Some systems also use a file called Xcms.txt for device independent
      color schemes, but that also doesn't help us.
