HELP BROWSESELF_MESSAGE                     Mark Rubinstein  April 1986

    <object> <- browseself;

This library provides a "browser" for the flavour package (for full
details of the package see TEACH * FLAVOURS).  The library makes use of
*SEETREE and *SHOWTREE and as a consequence can take a while to load, but
by default it is built into the flavours saved image.

Once loaded you can "browse" through a network of instances, examine the
flavour class-hierarchy, metaflavour class-heirarchy and get some
information about the definition of a flavour.

--- INVOKING THE BROWSER -----------------------------------------------

To invoke the browser on an instance you send the message "browseself" to
it, for example if the value of CHARLES is an object:

    charles <- browseself;

Often you will find that there are some attributes which are not
particularly interesting and which you do not wish displayed when you are
browsing.  You can tell the browser not to display selected instance
variables by sending the message "donotbrowse(ivar-name)" to the object or
to its metaflavour (see HELP * METAFLAVOURS).  For example if you are not
interested in the age of people you can do

    person_flavour <- donotbrowse("age");

(assuming that instances of people have an instance variable called AGE).
This will be effective for all instances which have PERSON as part of
their flavour hierarchy.  You can make the browser display AGE slots again
by doing:

    person_flavour <- dobrowse("age");

--- USING THE BROWSER --------------------------------------------------

When you are browsing an instance you will be shown a tree diagram in VED
with boxes representing each of the object's instance variables and their
value.  You can move to one of the boxes or values using the VED cursor
control keys.  You can quit from the browser by using the key strokes you
would normally use for going to the end of the file.  For details of how
to explore the tree see HELP * SEETREE.  If the values of an instance
variable is itself an object then you can either switch to browsing it, or
get the browser to browse both the current object and the tree for the
selected instance variable.

When you are on a box there are three keys which have a special function.

    ENTER KEY   This will make the browser display the tree for the
                instance in the box under the cursor in the position where
                the box is.  In order to do this *SHOWTREE has to
                completely replan how the tree should be shown so the
                screen will go blank while it is planning, and then the new
                expanded tree will be displayed.  SHOWTREE will take
                longer as the tree becomes bigger.

    RETURN KEY  (Sometimes called the DOCR key).  This will make the
                browser select the instance for the box under the cursor
                and browse upon it.  The tree above and to the left and
                right of this box will not be displayed.  This allows you
                to "re-centre" your focus of attention and will speed up
                SHOWTREE's thinking time.

    CHARDELETE KEY   This will include the instance variable under the box
                in the list of unintersting instance variables so that you
                can trim the amount of information the browser shows about
                the current kind of object.  (This uses the DONOTBROWSE
                message mentioned above).  The display will not be altered
                immediately but future instances of the same flavour will
                not include displays for this instance variable.

    REDOCOMMAND KEY  This will cause the flavour browser to be invoked on
                the flavour of the current instance.  When you quit from
                the flavour browser (using the ENDFILE key) you will be
                returned to browsing the instances.

While you are browsing flavours most of these special keys have no effect
except for the REDO key which will switch to browsing the metaflavour
heirarchy and the RETURN (or DOCR) key which will cause the browser to put
a new file in the ved buffer with an example of how the flavour might have
been defined, this is to say it will have the headers for the flavour and
all the methods and daemons but it cannot reproduce that actual code of
the methods and daemons.  You cannot examine the file until you have left
the browser.

--- OTHER UTILITIES PROVIDED -------------------------------------------

The browser adds several messages to the protocol of vanilla_flavour and
metaflavour_flavour that might be of interest.  These are as follows.


-- New Protocol for vanilla_flavour ------------------------------------

browsetree
    Returns a tree (embedded list structure) which would be used to
    display the instance - this is with sub-lists for slots and their
    values apart from those that have been made invisible with the
    donotbrowse message q.v.
donotbrowse(ivar-name)
    Notes ivar-name as an invisible instance-variable.  Will not be
    displayed by the browser.
browseself
    Invokes the browser or -self-.
browsemyflavour
    Invokes the browser on -myflavour-.

-- New Protocol for metaflavour_flavour --------------------------------

browsetree
    Returns a tree (as above) for the flavour.
browseself
    Invokes the browser on -self-.
browsemyflavour
    Invokes the browser on -myflavour-.
dodisplayself
    (Used by displayself message).  Prints out the skeleton of the flavour
    definition.
displayself
    Print out skeleton into a temporary file and edit the file.

-- New Protocol for flavour_flavour ------------------------------------

donotbrowser(ivar-name)
    Note ivar-name to be an invisible instance variable.
dobrowse(ivar-name)
    Make ivar-name become visible again.

--- A WORD OF WARNING --------------------------------------------------

The browser is new and experimental never the less it has been found to be
useful for sorting out some problems.  There are problems with it and I
still not convinced that the last feature of decomposing a flavour record
is useful or does the right thing yet.  I would appreciate feedback of all
kinds.

See also
    TEACH * FLAVOURS, for full details of the flavour system
    HELP * SEETREE, * METAFLAVOURS.