\input texinfo  @c -*-texinfo-*-

@c %**start of header (This is for running Texinfo on a region.)
@setfilename br-design.info
@settitle The OO-Browser Design
@c %**end of header (This is for running Texinfo on a region.)
@synindex vr fn

@iftex
@finalout
@end iftex

@titlepage
@sp 4
@center @titlefont{Design Issues in the OO-Browser}
@sp 5
@center Bob Weiner
@center Motorola Inc.

@sp 2
@center March 1991 and January 1993

@end titlepage
@page

@node Top, Design Issues, (dir), (dir)
@unnumbered Abstract

The OO-Browser is an efficient object-oriented class browser.  It has a
completely direct-manipulation interface with multiple modalities.  It
may be used for both system exploration and for browsing purposes as
part of a professional software development tool chest.  It quickly
displays and provides views of complicated inheritance trees, making
it an important tool for understanding object-oriented systems.  It is
integrated with a powerful editing environment that can be customized
to meet personal work styles.

The OO-Browser is the first such tool to work with a multiplicity of
object-oriented languages.  It currently supports five object-oriented
languages (Eiffel, C++, Objective-C, CLOS (Lisp), and Smalltalk) and
one documentation language (GNU Info).  Adding a new language is fairly
straightforward and can be done in one to five days.

This paper has three main parts.  The first discusses issues in the design
of the OO-Browser, emphasizing its unique aspects.  Issues pertinent to
all class browsers are touched upon and an explanation is given for how
the OO-Browser approaches each of them.

The second part examines the actual implementation.  It concentrates on
the user interface aspects and how they empower the user.  Novel
concepts introduced by the browser are discussed.  They include: a
merged help/command menu construct, dynamic method location, Environment
class groupings, and browsing based on source code only.

The third part suggests directions for future work.

@menu
* Design Issues::               
* Design Specifics::            
* Further Work::                
* Conclusion::                  

 --- The Detailed Node Listing ---

Interactivity

* Build Speed::                 
* Query Response Time::         

Textual User Interface

* Environments::                

Direct Manipulation

* In C++::                      
* In Eiffel::                   

Alternate Interfaces

* Environments::                

Environments

* Env Create::                  
* Env Build::                   
* Env Load::                    
* Env Save::                    
* Env Update::                  

Expand Query Types

* Dynamic Object Browsing::     
* Tool Integration::            
* Graphical Interface::         
* Version Control::             
@end menu

@node Design Issues, Design Specifics, Top, Top
@chapter Design Issues in the OO-Browser

@section Background

The OO-Browser was initially conceived for utilitarian reasons.  A
simple, fast class browser was needed for a development project based
in the object-oriented language, Eiffel.  The browsers available for
Eiffel were deemed weak and of not much value.

Since I had built tools in the past on top of the GNU Emacs
environment, I knew that this could be a rapid process, even when a
high-level interface was needed.  GNU Emacs was also the preferred local
editor, so close integration with it was considered a benefit.

A simple prototype of the browser was completed in two days from
conception to implementation.  Its user interface was based in part on
the Smalltalk-80 class browser under the assumption that this interface
had been developed over a long period of time to maximize developer
productivity.

The prototype showed promise as a tool that would be useful for other
languages besides Eiffel.  I identified C++ and Objective-C as the
languages most needy of such a tool.  A separate prototype version for
each of these languages was done in a single day as a dramatic
demonstration of the generality of the concept.

The road from prototype to a professional tool required a good amount
of work over an extended period as as an independent project.  Browser
performance, structure and features were improved throughout this
period.  A number of new languages were also added and all of these were
integrated via a single common kernel.  A complete user manual was
written.  The shared kernel browser was dubbed the OO-Browser.

The architecture layered on top of GNU Emacs turned out to be a great
success for a number of reasons.

@itemize @bullet

@item
Both computational and interaction speed of the browser exceeded
most people's expectations.

@item
Integration with Emacs meant that when interacting with the browser,
people could reuse the editing skills they had acquired from other
tasks.

@item
The flexibility of Lisp provided a direct means for implementing
the common browser kernel.
@end itemize

@menu
* Design Goals::
* Interactivity::
@end menu

@node Design Goals, Interactivity, Design Issues, Design Issues
@section Design Goals

The OO-Browser was initially designed in response to the lack of easy to
use class browsers in the many emerging object-oriented language
environments of today.  In fact, many environments still consist of
nothing more than a compiler and a debugger.  Even those environments
that contain browsers, often offer weak ones with barely usable interfaces.
The well-known Smalltalk environments [@cite{Goldberg 83}] are the only
notable exceptions.  Some excellent C++ support environments are now
just emerging (Saber-C++, ObjectWorks for C++, Field, ET++).

The OO-Browser was meant to be small, fast, and easy to use.  So far it
has met all of those goals.  There are three main uses that I see for a
class browser:

@table @strong
@item Design Tool
A browser should allow for the location of classes
that meet a specified set of criteria.  It should be just as easy to
determine that no such class exists.  A more difficult task is to
determine similar classes that might be of interest to the user.

@item Exploration Tool
The browser should allow one to explore libraries of classes as well as
full programs.  It should be especially useful when one is unfamiliar
with the set of components that one is browsing.

@item Engine Interface
The browser engine should be usable without the user interface, so that
one can use the browser features while editing and so that programs may
use the browser capabilities with their own user interfaces.
@end table


The quality with which a browser provides the above services can be surveyed by
examining a number of issues:

@table @strong
@item Interactivity
The browser should preprocess source files quickly.
It should also answer queries with minimal delay so that the user
maintains a sense of interactivity.

@item Usability
It should be easy to invoke and just as easy to put
away, so that it does not distract from other tasks in which the
developer is involved.

@item Consistency
A user of the browser should be able to learn a small
set of interaction techniques and thereby access a broad set of
functions.  He should also be able to build on these fundamental
concepts to achieve higher levels of proficiency with the tool.

@item Scalability
It should scale up well and maintain its speediness
with libraries of thousands of classes.

@item Integration
It should integrate well with a program editing
environment, providing language specific features to speed the
development process.

@item Extensibility
The browser should be extensible by a competent programmer.
@end table

@noindent
Let us discuss separately each of these issues to see how the OO-Browser
addresses them.


@node Interactivity,  , Design Goals, Design Issues
@section Interactivity

There are two interactivity concerns associated with most class
browsers, speed of database construction and query response time.

@menu
* Build Speed::                 
* Query Response Time::         
@end menu

@node Build Speed, Query Response Time, Interactivity, Interactivity
@subsection Build Speed

The first concern involves the speed with which the browser can
extract any information it needs in building a cache or database of
information from the code.  If this is a long, involved process, users
will want it performed in a batch fashion so that it does not delay
their workflow.  The rebuilding of databases at night or on idle
processors is a common solution.  The drawback to this is that it
likely precludes the use of the browser for immediate exploration of
newly discovered or procured class libraries.  If on the other hand,
this building process is rapid, the user will be much more likely to
experiment with the tool and to use it for exploring new class sets.

The OO-Browser takes the latter approach.  It builds a minimal lookup
structure derived directly from class source.  It assumes that the
classes it scans are syntactically correct and therefore needs parse
only a small fraction of the code scanned.  This scanner can
distinguish between declarations and definitions.  It recognizes
commented passages and so ignores valid definitions embedded within
them.

The result is that even though this scanning code has not yet been
optimized, it can scan hundreds of classes a minute on a single
processor machine.  This speed is fast enough that when users come
upon an unfamiliar class library, they simply ask the browser to scan
it and wait for its initial display of the class list found from the
scan.

Still, on some platforms, the lookup structures for very large class
libraries may be better built in a batch fashion.  The OO-Browser
includes a mechanism for doing so via a simple command line invocation
which can be scheduled with the UNIX 'cron' utility.

@node Query Response Time,  , Build Speed, Interactivity
@subsection Query Response Time

Most browsing operations represent some form of query.  Show the
ancestors for this class.  List all classes that contain the string,
'window'.  How many classes are in this library?

Query responses must therefore be fast enough to give the user a sense
of close knit interaction.  This is the reason much effort is often
put into the database back ends of program support environments.

The OO-Browser instead uses basic caching techniques to optimize the
most common queries.  These techniques work surprisingly well, even
for environments containing thousands of classes.

One of the most common queries given to the OO-Browser is to show
descendency or ancestry graphs for a set of classes.  On a
workstation, a graph involving about 500 classes can be computed and
displayed in three to four seconds.  Smaller queries receive
instantaneous replies.


@section Usability

With the emergence of multi-windowed graphical interfaces in recent
years, man-machine interaction has become much more complex.  Many
environments have been converted to these interfaces in the name of
ease of use, but often the user is left with less control than he had
before.

A common example is the window pile problem that results when many
applications share a display space and each creates a new window every
time a simple action, like setting a parameter value, must be
performed.  A user often is left to use simple push and pop funtions
to wade through the window layers to find one he may want.

This sort of behavior was considered unacceptable for the OO-Browser.
To avoid those situations, the browser performs its own window
management.  The browser is invoked by a key press or menu selection.
It then displays all of its windows.  Another key can be used to put
the browser away, essentially to hide it from view.  All of its
windows then disappear.  Since the user has not actually quit from the
browser, when he invokes it again, his entire context is restored,
both visually and computationally.  With such an interface, browsing
becomes a basic reflex.  Invoke browser.  Locate desired class for
editing.  Hide browser, leaving selected class visible.  Continue work.


@section Consistency

Consistency and usability go hand in hand.  Techniques of good design
dictate that a designer should play upon the skills that his user base
brings with them.  New interface metaphors should be carefully thought
out.  Their benefits should be weighed against the cognitive strain
that new users will necessarily endure.

Editing skills, for example, become almost hard-wired into skilled
computer users psyches so that little conscious action is needed to
perform common tasks.  Yet often, each new application offers a
different editing model without adding any new editing benefits for the
user.  This sort of design is especially egregious in a tool-based
environment where the designer knows that his users will likely need a
variety of tools to do their work.

The OO-Browser avoids this sin by integrating with the popular GNU
Emacs editor.  Since Emacs provides a modeless editing environment in
which any command may be executed at any time, all normal Emacs
editing funtions are available while the user is within the browser's
Emacs interface.  So, for example, if one already knows how to search
an edit buffer for a particular string, one simply does the same thing
within the browser.

Browser key bindings are carefully selected to be both mnemonic and
consistent with standard Emacs key usage.  In mouse-based
environments, direct manipulation techniques are supported, so the
user can select the entity he wants to operate on and the command he
wants to apply without the need to memorize any key names.


@section Scalability

The term educational programming environment is too often used to
describe tools too weak to be used for real development projects.
This is a common syndrome associated with highly interactive tools.
They simply don't scale up for use in large, distributed projects.

@noindent
The symptoms of this syndrome in browsing tools include:
@enumerate
@item
the ability to browse code from only one root directory at a time;

@item
support for only one browsing environment under which all classes must
be lumped;

@item
slow performance with large class sets;

@item
ability to operate on only one class/category at a time;

@item
no portability of the interface or tool itself.
@end enumerate

The OO-Browser has so far seemed to scale well.  It uses the concept
of Environments to address symptoms (1) and (2).  For each instance of
the OO-Browser, the user selects a current Environment which he wants
to browse.  (Environments are discussed later in this paper.)  Each
Environment may include source from any number of directories,
distributed across machines using file sharing systems like NFS or
Apollo's Domain system.  Each Environment contains classes written in
a single language.  The user may select another Environment at any
time and thereby switch languages.

Symptom (3) has been addressed in the previous section on @strong{Query
Response Time}.

Symptom (4) does not exist in the OO-Browser.  Virtually all commands
that can be applied to a single class may also be applied to any class
list returned by a browser query.

Symptom (5) is not a problem either.  The OO-Browser is extremely
portable.  The browser runs on any UNIX system on which GNU Emacs
runs, which is virtually every one.  Therefore, a user can run the
browser on platforms from any vendor.  The graphical interface to the
OO-Browser runs under the portable X Window System.  It currently uses
a Motif-based interface, but may in the future be converted to an even
more portable interface toolkit.


@section Integration

A browsing tool is but one piece of the development environment.  It
must therefore not only do its job but also support the style of
program development followed at a site.

The OO-Browser supports object-oriented development.  Object-oriented
development is necessarily incremental and component-based.  The browser
allows one to edit a class and then incrementally update the browsing
environment with any changes.  It lets developers think in terms of
classes, the building blocks of object-oriented languages, without
regard to where the classes are located.

Each browser language mode is tailored to the specifics of the
language.  For Eiffel, it supports the location of method definitions
that have been repeatedly renamed throughout the inheritance
graph.  For C++, support for method overloading and multiple
inheritance is included.

Editor integration is critical in a browser, as this is the mainstay
tool for program development.  Surprisingly, this is not universally
understood.  Stepstone Corporation's Objective-C browser still does
not allow one to edit classes that it displays.  Only the newest
versions of Interactive Software Engineering's Eiffel browsers allow
one to edit classes; one still cannot simply select a class name
returned as a result of a query in order to edit it.

Besides the Emacs interface, the current OO-Browser version allows the
use of alternate editors, so that a user need not become familiar with
the Emacs editing model if he is not already.  It still uses the Emacs
lisp engine as a back end to process browser requests, but allows the
user to edit classes with whatever program he likes.  The graphical
interface also supports the use of any desired editor.  For non-Emacs
users, it is a simple matter to produce a turnkey command that allows
use of the browser without any prior knowledge.


@section Extensibility

The whole open systems phenomenon arose after corporate users tired of
relying on vendors to provide proprietary solutions to simple
problems.  The choice of an open system allows one to seek software
solutions and system support from a larger pool of organizations than
with closed systems.

Similar needs are now arising in the programming support arena.
Closed systems seldom meet all of the needs of the user base.  Without
a back end customization language, users are left to the whims of the
developer to decide whether a feature is important enough to include.
Macro language provisions are too weak to allow all the changes that may be
desired, so a full programming language interface is needed for
advanced user customization.

Simple customizations are performed by setting values of attributes
included as user variables in the OO-Browser.  More advanced
customizations, like the addition of a new query type are performed in
GNU Emacs Lisp.  Most of the OO-Browser is written in the Lisp dialect.
It is a fully interpreted language and so is natural to use as a
customization language since each change may be immediately tested.

As noted earlier, an entire language interface can be built in a
matter of days, demonstrating both the flexibility of Lisp and of the
language interface provided by the OO-Browser.


@node Design Specifics, Further Work, Design Issues, Top
@chapter OO-Browser Design Specifics

@menu
* Textual User Interface::      
* Graphical Tree Display::      
* Direct Manipulation::         
* Alternate Interfaces::        
* Environments::                
@end menu

@node Textual User Interface, Graphical Tree Display, Design Specifics, Design Specifics
@section Textual User Interface

The screen shot on the following page highlights the major components
of the OO-Browser textual user interface.  The windows across the top of the
OO-Browser screen are called @dfn{class listing windows}; they display
@dfn{class listing buffers} with a single class name per line.  The
@dfn{class viewer window}, sometimes simply referred to as the
@dfn{viewer window}, fills the bottom half of the screen.  It is used
to display class source and summary information.  Pictured here in the
viewer window is the command help/menu buffer, summarizing the browser's
command key bindings.

The number of listing windows is limited only by the screen width.  The
width of the windows may be interactively adjusted to permit more or
fewer windows for particular tasks.  CLOS identifiers are typically much
longer than Eiffel identifiers, so one would want to raise the window
width when operating on CLOS classes.

@menu
* Hierarchy Listings::          
@end menu

@node Hierarchy Listings,  , Textual User Interface, Textual User Interface
@subsection Hierarchy Listings

The directed, acyclic graph relations prevalent in languages with
multiple inheritance are translated into textual hierarchies by repeating
elements with multiple parents throughout the tree structure.  So if
class B inherits from C and class C inherits from P1, P2 and P3.  One
view of descendants would show:

@example
	P1
	  C
	    B
	P2
	  C ...
	P3
	  C ...
@end example

The ellipses indicate that C's subtree has been expanded somewhere
above, so it is not repeated.  The resultant structure is easy to
understand and very useful.  This sort of structure allows one to use
the browser on a text-only terminal and still be able to visualize
significant inheritance relations.

@noindent
Queries that may be made under this interface include:
@itemize @bullet
@item
show parents
@item
show children
@item
show ancestors
@item
show descendants
@item
total selected classes
@item
select classes matching regular expression or string.
@end itemize

@noindent
All of these commands may be applied to any grouping of classes,
eliminating the sequential bottleneck found in many other such tools.

All displays that move up the inheritance tree consume a listing window
to the left of the current one.  Descendancy displays do the opposite
and select the window to the right.  At the edges of the display, the
window selected wraps around to the other side.  An exit command
clears the current listing buffer and returns to the last one,
regardless of how the user walks up and down the trees.  Ancestor
listings may be shown with parent down to root (highest level ancestor)
or inverted, with root down to parent, so that children are always
displayed below their parents.

The class matching command is fast and easy to use.


@noindent
Besides queries, a few of the useful commands provided are:
@itemize @bullet
@item
sort classes
@item
view class source
@item
edit class source
@item
save class listing.
@end itemize

The editor is user selectable.  The ability to sort any class listing
simplifies class location.  The @emph{save class listing} command is
useful to record the output of interesting queries for documentation and
reference purposes.

All browser queries and commands work with class source code only.  This
makes the tool useful in exploratory situations where a compiler is not
available.  It also ensures that the browser receives up to date
information from which to work.


@node Graphical Tree Display, Direct Manipulation, Textual User Interface, Design Specifics
@section Graphical Tree Display

The graphical interface to the browser provides a compact tree-based
view of a set of classes or an Info manual.  (A sample enlarged display
is shown on the following page.  It uses the same set of classes as the
prior picture of the textual display, for ease of comparison.)  This
interface supplements the textual interface so that the user can easily
comprehend large inheritance structures.  (Nodes with more than one
incoming pointer (parent) are repeated throughout the tree, but their
subtrees are excised and replaced with the ellipses symbol, ..., just as
in the textual interface.  Subtrees may be collapsed or expanded
interactively.  Scrolling mechanisms are limited to horizontal and
vertical scroll bars, but a panning construct is being considered.

When the user finds a class he is interested in, he simply selects it
with the same mouse button he uses to select classes in the textual
interface.  The node is highlighted and the associated class is
displayed in the text editor.

The graphical interface can be invoked on any portion of the current
browser Environment.  One may for instance, obtain a list of classes
with 'Stack' in their name and then through a mouse click, invoke the
graphical browser on just the descendancy trees of the selected classes.

Any number of graphical browser views may be shown at the same time.
Each view is independent, so each may provide a view of any environment
previously created by the OO-Browser.  All views can communicate with a
single instance of the editor, so that one can maintain onscreen views
of multiple environments, even across languages, and simply select any
node from any view to access the corresponding source.

A new, window-system independent version of the graphical interface
provides double buffered display updates for smooth scrolling, a panner
device for rapid movement throughout a view, and a number of useful tree
display representation alternatives.

The graphical interface is presently somewhat limited, but that is only
because it is so new.  It is a straightforward matter to provide a user
of the graphical interface with the full complement of browser commands
by adding the commands to a set of menus and sending each command to the
browser engine as it is selected.


@node Direct Manipulation, Alternate Interfaces, Graphical Tree Display, Design Specifics
@section Direct Manipulation

To maximize the utility of the displays presented to the user, most
displayed entities may be operated upon through simple mouse clicks.
For example, clicking on a class name displays the associated class
definition.  Clicking to the left of a class displays its ancestors and
to the right its descendants.  Selection of the ellipses after a class
name shifts the display focus to the class' descendants list.

A click in an empty listing buffer may display the browser help text or
a menu of language-specific source files which the user has browsed.
This menu permits random access selection of any class file.

A click on any of the command descriptions in the help display executes
the associated command on the previously selected item.  This is such a
useful, intuitive means of control that it is surprising that one never
sees this capability in application interfaces.



@menu
* In C++::                      
* In Eiffel::                   
@end menu

@node In C++, In Eiffel, Direct Manipulation, Direct Manipulation
@subsection In C++

@cindex C++
Entities in C++ programs may be selected for inspection with the middle
mouse button.  Most importantly, once a class header file is displayed,
one simply clicks on a method declaration to see its corresponding
definition.  Each feature declaration should be given separately to
ensure accurate parsing.  If the method is inherited from another class,
a message at the bottom of the screen describes which class the method
is defined in once the browser displays the method definition.

The browser dynamically handles full function overloading and numerous
other complex mappings between declaration and definition that are
permitted in C++.  A complex set of pattern matching heuristics are used
which work in almost all cases.  This is a novel approach that speeds
the construction of Environments, since no normalization is performed on
function signatures until they are operated upon.  All other browsers
rely on preprocessing techniques which store a normalized form of the
declaration to match against the definition signature.

Parent classes may be browsed in a similar manner by clicking on their
names in an inheritance or declaration clause.  Multiple inheritance is
fully supported.  There is no support as yet for locally scoped classes.

Include files may be browsed by selecting their inclusion declarations
(@strong{#include} ...).



@node In Eiffel,  , In C++, Direct Manipulation
@subsection In Eiffel
@cindex Eiffel
Selection of a feature name in an export clause displays the feature
definition, even if it is renamed several times within ancestors.
Parent classes may be browsed in a similar manner by clicking on their
names in an inheritance or declaration clause.

The following example of locating a renamed feature is taken from an
actual set of Eiffel library classes:

@example
User selects feature @emph{subwindow} of @emph{POPUP_MENU}
   inherited from @emph{WINDOW}
   which renames @emph{child} as @emph{subwindow}
      inherited from @emph{TWO_WAY_TREE}
      which renames @emph{active} as @emph{child}
         inherited from @emph{TWO_WAY_LIST}
            inherited from @emph{LINKED_LIST}
            which defines @emph{active}.
@end example

The browser would display the feature @emph{active} and explain to the
user that feature @emph{subwindow} of class @emph{POPUP_MENU} is
inherited from feature @emph{active} of class @emph{LINKED_LIST}.
Location of this sort of feature definition would be incredibly tedious
without programmatic support.

If a feature reference is selected within a non-deferred (non-abstract)
class, then deferred features are automatically ignored when searching
for the feature definition.  If the reference class is deferred
(abstract), the first matching ancestral feature found is selected,
whether it is deferred or not.

The algorithm used to locate features is dynamic, so if another class
is inserted into the inheritance structure given above, the feature
definition still will be located properly.



@node Alternate Interfaces, Environments, Direct Manipulation, Design Specifics
@section Alternate Interfaces

Earlier we mentioned that the computational back end, the @dfn{engine}
part of the browser should be available for use without its interface.
The interactive nature of Lisp allows the prototyping and delivery of
different interfaces quickly.  For example, the graphical interface to
the browser was originally a standalone tree drawing program.  A
prototype interface to the browser was developed in a matter of two
hours, with most of the time spent examining the unfamiliar code in the
tree drawing program.

@noindent
Other simple but extremely useful interfaces we have provided include:
@itemize @bullet
@item
the ability to perform completion on type identifiers when programming;

@item
support for compiler error parsing when the compiler outputs only the
class name and line number of the error;

@item
a command that prompts for a class name and then edits the class,
with class name completion included.
@end itemize

@noindent
All of these were straightforward to implement based upon the browser
engine functions.

@menu
* Environments::                
@end menu

@node Environments,  , Alternate Interfaces, Design Specifics
@section Environments

@cindex Environment, the
@cindex Library search list
@cindex System search list
Whenever the OO-Browser is in use, an Environment is selected.  An
Environment may be built or simply specified.  An @dfn{Environment
specification} tells the browser what to include in the construction of
an Environment.  (@xref{Env Create, , Creating Envir Specs}, for more
info.)  An OO-Browser @dfn{Environment} includes a set of inter-class
relationships together with a few browser settings.  The phrase,
@dfn{the Environment}, refers to the current OO-Browser Environment.
Many browser commands depend on information in the Environment.  A
summary of the components of the Environment may be displayed any time
during browser use.  See the next page.@refill

The set of classes included in an Environment is specified by two lists
of directories, below which all of the Environment's class source files
are to be found.  (The OO-Browser will automatically search
sub-directories below the directories specified.)  The first list of
directories is called the @dfn{Library search list}; it defines the
locations of stable, typically reusable classes that have been released
for general use.  The second list is called the @dfn{System search
list}; it defines the locations of unreleased classes being developed,
often for a particular system.  All class names within a single
Environment must be unique to ensure proper operation of the browser.
This also implies that the Library and System class sets be disjoint.

The OO-Browser lets one create, update and save Environments.  Once an
Environment file has been created, it may be loaded at any time.  The
browser will then use this Environment for all of its operations until
another one is loaded.

The browser maintains a separate Environment for each programming
language on which it is used.  Thus, if one switches from Eiffel to
C++ browsing and then back to Eiffel browsing, the Eiffel environment
will not need to be reloaded; it will appear immediately and the
screen will appear as if the Eiffel OO-Browser were invoked for the
first time.  Only one Environment per language is kept in memory.

@cindex Environment, default
There is a default Environment file name for each browser-supported
language; these names are unique to each user account on the system:
@file{~/.br-eif-env}, @file{~/.br-c++-env}, @file{~/.br-objc-env}, 
@file{~/.br-clos-env}, @file{~/.br-smt-env}, and @file{~/.br-info-env}.
Environment files are automatically created and loaded by the OO-Browser
so that one need never become familiar with their format.@refill

Environments provide a simple, uniform way of managing numerous class
libraries.  A simple extension to the browser is planned which will
allow one to interactively select Environments as one typically does
with files.  Each Environment stores an indication of what language its
classes are in, so it can dictate which browser version to invoke.


@menu
* Env Create::                  
* Env Build::                   
* Env Load::                    
* Env Save::                    
* Env Update::                  
@end menu

@node Env Create, Env Build, Environments, Environments
@c  node-name,  next,  previous,  up
@subsection Creating Environment Specifications

@cindex Environment specification
Environment specifications are useful when one wants to describe a
number of Environments to the OO-Browser but wants to defer their
construction until later.  Large environments then can be built
overnight.  @xref{Env Build, , Building Environments}, for more
info.@refill

@findex br-env-create
@cindex initialization file
Every Environment must be specified before it can be built or used.
Thus, specifying an Environment is the first step in creating it.
An Environment create command interactively prompts for all information
necessary to specify and to build an Environment.  This command may 
be invoked repeatedly to quickly specify a number of different
Environments.@refill

@noindent
Here are the Environment specification components for which the
OO-Browser prompts:
@table @code
@item System search directories
List of directories below which other System directories containing
class source code and directories of class source files may be found.

@item Library search directories
List of directories below which Library files of class source code
and directories of class source files may be found.

@item Save all Environment lookup tables?
@emph{Yes} means that a complete set of lookup tables should be saved as
a class Environment.  @emph{No} means that some lookup tables should be
built from others when the tables are loaded from an Environment file.
Answering @emph{yes} doubles the size of each Environment file but
slightly speeds the loading of an Environment into the browser.
@emph{No} is the default that works best on most computers.
@end table


@node Env Build, Env Load, Env Create, Environments
@c  node-name,  next,  previous,  up
@subsection Building Environments

@cindex Environment building
An Environment specification tells the OO-Browser what to include in the
Environment, but the Environment still must be built before use.  When
class names or locations have changed or the Environment's inheritance
structure is modified, the Environment must be rebuilt.  For small
Environment changes, one may use the class addition and deletion
features of the browser.  @xref{Env Update, , Updating Environments},
for more info.@refill

@cindex Environment building, batch
@cindex large Environments
Very large Environments may be built overnight by invoking Emacs in
batch mode at a scheduled time.  Note that the Environment specification
file must have been created prior to execution of this command so that
the browser knows what to build.

@node Env Load, Env Save, Env Build, Environments
@c  node-name,  next,  previous,  up
@subsection Loading Environments

@cindex Environment loading
A new Environment may be loaded for use at any time within the
OO-Browser.  One may either select the load Environment command from
the on screen OO-Browser command summary or simply use the
language-specific browser invocation command that was originally used to
start the browser, except in this case, it should be preceded by a
prefix argument.  For example, the @code{(eif-browse)} command, would
prompt for and then load a new Eiffel environment, even when one is
already browsing an Eiffel environment.


@node Env Save, Env Update, Env Load, Environments
@c  node-name,  next,  previous,  up
@subsection Permanently Storing Environments

The OO-Browser automatically builds and saves Environments in most
cases.  Occasionally one may find a need to force the Environment to
be saved to a file, as in the case when one wants to save an Environment
under a different file name.

The Environment save command is used to force an Environment save to
occur.  The command prompts for a file to save to, with the default
as the current Environment file name.
 

@node Env Update,  , Env Save, Environments
@c  node-name,  next,  previous,  up
@subsection Updating Environments

@findex br-add-class-file
@cindex class, adding to Environment
@cindex class, replacing in Environment
@cindex Environment, adding classes
@cindex Environment, replacing classes
@cindex initialization file
A file containing class definitions may be added to the Environment with
the add class file command.  This will prompt for the file name, scan
the file, and then update the Environment.  If a class defined in the
file is already in the Environment, its information will be replaced
with the information gathered from the file; otherwise, the class will
be added to the Environment.

@cindex Environment, adding individual classes
To add a single class from a file containing multiple classes, the file
can be read into an Emacs buffer, the buffer narrowed to the desired
class and then the add command executed.  @xref{Narrowing, , Narrowing,
emacs, The Gnu Emacs Manual}.@refill

This command may also be used outside of the browser user interface when
one is editing a file in Emacs, so that there is no need to jump in and
out of the browser.

@kindex C-c C-d
@findex br-delete
@cindex class, deleting from Environment
@cindex Environment, deleting classes
A class is deleted from the Environment, by pointing to its name in a
class listing buffer and then executing the delete class command.
The class matching command may be used to locate it.  The browser
confirms the deletion by removing the class name from the listing
buffer.


@node Further Work, Conclusion, Design Specifics, Top
@chapter Suggestions of Further Work

@section Expand Query Types

The browser really only works with inheritance and method relations
right now.  There is an undeniable need for the addition of supplier,
client, and category-based browsing.

Suppliers are classes which contain methods invoked by other classes,
the clients.  Computation of these recursive relations is expensive.  A
technique must be developed which preserves the quickness of Environment
construction and supports queries using these relations.

Method breakdowns by visibility (public, private, protected) would also
be useful to add.  This should not require too much work.

Category-based browsing should be the next major addition.  Some other
people have already done work on adding facet-based categories to the
browser.  Facets are traits that classes have.  Classes sharing facets
are grouped into a facet category.  Facet examples might be: fixed sized
container classes, domain-specific classes, or classes that contain a
name field.

@menu
* Dynamic Object Browsing::     
* Tool Integration::            
* Graphical Interface::         
* Version Control::             
@end menu

@node Dynamic Object Browsing, Tool Integration, Further Work, Further Work
@section Support Dynamic Object Browsing

The OO-Browser works with static structures.  It therefore utilizes
class groupings but has no concept of run-time objects.  The techniques
and query relations desired in an object browser are very different from
that of a class browser.  Therefore, a separate tool should be built.
It could, however, utilize the OO-Browser user interfaces.  It would
then act as a back-end engine communicating with the class browser
interface.  This raises the inter-application communication issue of the
next section.


@node Tool Integration, Graphical Interface, Dynamic Object Browsing, Further Work
@section  Provide Mechanism for Integration with Other Tools

Emacs supports subprocess control.  This is how the textual interface
communicates with the graphical interface.  They use a simple
redirection of standard input and standard output.

A much more desirable and flexible strategy is to use a communications
medium like sockets to allow peer-to-peer communication.  On top of this
low-level mechanism, a method like Field's Selective Broadcasting
[@cite{Reiss 88}] or ET++'s Multiple Views [@cite{Weinand 89}] might be used.

@node Graphical Interface, Version Control, Tool Integration, Further Work
@section Extend Graphical Interface

A lot could be done here, none of it particularly difficult.  As
mentioned before, a full suite of browser commands should be added.
A technique that allows dynamic menu entry additions would provide the
requisite flexibility.  This could probably be achieved with a basic
resource file format and a small amount of application code to cache the
entries.

@node Version Control,  , Graphical Interface, Further Work
@section Support Version Control Systems

RCS is the likely candidate system.  One would want to be able to
browse particular releases and to avoid mixing code from one release
with that of another when building Environments.



@node Conclusion,  , Further Work, Top
@unnumbered Conclusion

The OO-Browser is a robust tool for class or generalized hierarchy
browsing.  New subsystems are easy to integrate, so we expect the
available types of queries and means of user interaction to continue
to expand.

The browser demonstrates useful user interface techniques.  It supports
multiple interaction modalities:  keyboard and mouse inputs, graphical
and textual views, menu and direct selection techniques.  This allows
the user to choose a style with which he is comfortable.  The ease of
entry and exit from the browser coupled with its access speed,
encourages a developer to use it often.  It integrates well with the
incremental development cycles often found in object-oriented projects.
It further supports the developer with external interfaces for compiler
error parsing and type name completion.

The browser implementation vividly illustrates that a single, portable
tool and interface can be used for a variety of languages.  Departmental
language needs often change.  So the ability to continue to use the same
tool with a different language lessens developer slow down and actually
provides an immediate comfort zone, so that the change need not be
overwhelming.  Another good example of interface reuse is the ET++
application development framework [@cite{Weinand 89}].  It provides a
means of building highly interactive, window system independent
applications that all share common interface constructs. One would hope
that more developers of programmer support tools will start taking an
approach of this kind.

@sp 2
[@cite{Goldberg 83}]  Goldberg, Adele and David Robson.
@emph{Smalltalk-80:  The Language and its Implementation}.
Addison-Wesley, 1983.


[@cite{Reiss 88}]  Reiss, Steven P.  "Integration Mechanisms in the FIELD
Environment," Brown University Technical Report CS-88-18, October 1988.


[@cite{Stallman 87}]  Stallman, Richard.  @emph{GNU Emacs Manual}.  Free
Software Foundation, Cambridge: MA, March 1987.


[@cite{Weinand 89}] Weinand, Andre, Erich Gamma, and Rudolf Marty.
Design and Implementation of ET++, a Seamless Object-Oriented
Application Framework, @i{Structured Programming}, Springer-Verlag: NY,
NY, Vol. 10, No. 2, 1989.


@contents
@bye

