Here are a few quick hints and tips that may make using HyperScheme
easier, and more fun! 

  + My handlers never get called, even though I registered them in the
    "correct" (most specific first) order.   

    If your handlers never get called, even though you declared them
    religiously according to the ``prime directive'++', one of them is
    probably ``failing''.  All the HyperNeWS/Scheme primitives return
    non-nil if they succeeded in performing their action or () if they
    ``fail''.  It's a good idea to "and" calls to the primitives
    together, then you can use sdb to see which call is failing.    

  + I can't set the menu items for my pulldowns, only the current
    selection changes. 

    You have probably missed out a level of parentheses on the value
    argument to `hns-set-value'.  Pulldowns expect to get either a
    string or a list of strings as their value argument, but
    `hns-set-value' expects to get a list of values as it's value
    argument.  This means to send '("a" "b" "c") to a pulldown you
    have to give '(("a" "b" "c")) to `hns-set-value'.  

  + (require 'HyperNeWS) fails, saying either "feature HyperNeWS was
    not provided" or (autoloading HyperNeWS.o), "Undefined" and a
    longish list starting with "_hn_new_name" ending with "_hn_show".

    You are trying to load HyperNeWS into a scheme that is running in
    a directory containing a file called HyperNeWS (causing the first
    error message) or HyperNeWS.o (causing the second).  This file is
    being used instead of the correct library versions because "."
    precedes the library directory in the default scheme load-path.
    Run scheme in another directory, or change load-path before
    calling require in your program, and the require will find the
    correct versions. 
  
  + I'm trying to use sdb in conjunction with the Xt/Motif interface
    (because my management are unenlightened/consider portability
    paramount -- delete as appropriate), but loading the second
    package fails, saying (where <intf> is the second package):

    ld: /local/ELK/lib/<intf>.o: _Find_Object: multiply defined
    /local/ELK/lib/<intf>.o: _Deregister_Object: multiply defined
    /local/ELK/lib/<intf>.o: _Register_Object: multiply defined
    /local/ELK/lib/<intf>.o: _Bits_To_Symbols: multiply defined
    /local/ELK/lib/<intf>.o: _Symbols_To_Bits: multiply defined
    /local/ELK/lib/<intf>.o: _Terminate_Group: multiply defined
    /local/ELK/lib/<intf>.o: _Unique_Id: multiply defined
    /local/ELK/lib/<intf>.o: _init_util_objects: multiply defined
    /local/ELK/lib/<intf>.o: _XauDisposeAuth: multiply defined
    /local/ELK/lib/<intf>.o: _XauGetAuthByAddr: multiply defined
    /local/ELK/lib/<intf>.o: _XauFileName: multiply defined
    /local/ELK/lib/<intf>.o: _XauReadAuth: multiply defined

    This occurs because loading <intf>.o (which has been statically
    linked) tries to load a second copy of various ".o" modules. Some
    of these definition conflicts are part of ELK-Scheme,
    (../util/symbol.o and ../util/object.o are loaded by both
    interfaces) and some are caused by the window system libraries
    (the Xau.. quadtuplet). The easiest solution is to copy the
    offending library, delete the appropriate modules from it, and
    relink <intf>.o using the new copy. Don't install the hacked
    library in place of it's original counterpart, it's only useful
    for creating <intf>.o! 

    For example (assuming Motif has been built and loaded correctly,
    and you're now trying to add HyperNeWS):

    % cd /local/ELK/lib/HyperNeWS
    % cp $HNHOME/lib/libhn.a .
    % ar d libhn.a AuDispose.o AuFileName.o AuGetAddr.o AuRead.o
    % ranlib libhn.a
    % rm ../HyperNeWS.o
    % ld -r HyperNeWS.o libhn.a
    % rm libhn.a
    % mv a.out ../mHyperNeWS.o
    % chmod 644 ../mHyperNeWS.o
    % cp ../../scm/HyperNeWS ../../scm/mHyperNeWS
    
    Now edit ../../scm/mHyperNeWS to (require 'HyperNeWS.o 'mHyperNeWS.o)
    and (provide 'mHyperNeWS). Note that ../util/symbol.o and
    ../util/object.o are omitted when mHyperNeWS.o is created this
    way: this version of the HyperNeWS interface can only be used in a
    scheme with the Xt/Motif interface already loaded (which is why
    it's called mHyperNeWS).

++ The prime directive states that:

   If a message matches the requirements for multiple handlers andthe
   handlers return nil or #f so that other handlers can be considered,
   the handlers will be invoked in the order that they were registered
   with `hns-set-handler'.