--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/br-design.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,1084 @@
+\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
+