[Caml-list] Re: ocamlbrowser [was labels]

["Benjamin C. Pierce" <bcpierce@saul.cis.upenn.edu>]

> Thanks for the feedback. This is what is needed to improve
> ocamlbrowser :-)

I'm glad I asked -- I didn't realize OCamlBrowser was this cool!

[Warning: long and detailed response follows...  I almost took this
off-list, but eventually decided that others may have useful thoughts,
especially about the first couple of points.]

> I was only too lazy to develop a preference file format. That would
> really be a nice utility module to share between Caml applications,
> and it would help to have a compatible syntax. Could the unison
> preference format be made an independent, reusable module ?

We've worked pretty hard on the Unison preference handling stuff, and it
would be nice to see it packaged in a form that would be easy for others
to use.  However, it will take a little thought to figure out what is the
right way to "extract" it from Unison and make it stand on its own,
without splitting the code off into a separate version that is not the
one used by Unison.  The issue is that there are several low-level
utility functions that the preferences module gets from a standard Unison
utility module, but it probably doesn't make sense to export that module
verbatim to the whole world, since it also has quite a bit of
Unison-specific functionality in it.  Some refactoring is in order.

> As somebody else suggests, moving to a more smalltalk style navigation
> would not be difficult. The current approach is mainly due to a
> historical evolution, taking for first model the original camlbrowser,
> where one window pops up for every definition!
> In the current system you have one window per module, but one could
> easily have a single window for all modules, as long as we do not have
> recursive modules including each other...
> I could include this as another style of UI.
> 
> Yet, I'm not 100% sure it would be better. The way you use
> ocamlbrowser is different from a smalltalk browser, in that most of
> the navigation is done through types: first look for a function, then
> for the definition of the type of one of its argument, then for the
> definition of a type appearing inside this definition... You often
> want to see several things at once, and the current approach can help
> there. Once in a while you press close all to collect the garbage.

I think no single, simple mechanism is going to be right all the time.  

  * When I'm following a thread to get somewhere else, I want to reuse
    the same window that I'm looking at now.

  * When I'm looking at a piece of code and want to check something that
    it refers to, I want to pop that up in a different window that I can
    close when I'm done without disturbing the main one.  

  * Moreover, I may sometimes want to look at several modules together,
    and for this it would be useful to somehow attach them together so
    that they do not obscure each other, so that they can be moved and
    closed (and perhaps later re-opened?) together, etc.  This kind of
    "tiling" organization can sometimes also use screen space more
    efficiently.

Reaching a design that uses screen space optimally in all these
situations (and the ones I didn't think of) seems pretty hard, but
at least we could probably get a little closer.

Here's one possible design (I'm sure it can be improved).
   * Every navigation command comes in three forms:
       1) open a *new* window for the new information
       2) re-use *this* window to display the new information
   * Style (1) is the default.  Pressing SHIFT while clicking gets you
     style (2).  
   * A netscape-style "back" command can be used to restore the contents
     of the current (or temp) window to its previous state, or to close
     a window that you just created.  
   * Perhaps there chould be some way to make the SHIFT and CONTROL
     modifiers sticky.

A possible refinement: 
   * One window on the screen is designated the "temp window" (initially,
     there is no temp window; one is created the first time it is needed,
     and the same window is used thereafter).
   * Add a navigation style:
       3) use the *temp* window 
   * Pressing CONTROL when clicking gets you style (3).   
(I'm not sure whether this refinement is worth the trouble -- just having
mode (1) plus a "back" keystroke to close the new window when done might
be enough.)   

Neither of these ideas addresses the last point above, about sometimes
wanting to "tile" parts of the screen.  I have the impression that good
tiling schemes are hard to find.

A more minor comment: the window that pops up when you click a module
name is usually too short to show all of the things defined in that
module, which means there's almost always some scrolling involved in
finding what you want.  What about making these windows initially tall
enough to show everything (within reason), and providing a Minimize
button to save space if needed?

> This problem of list length is real. What you really want is to use
> the same path (because it is also used for type checking), but to
> restrict the list (and maybe search) to the part of the path your are
> interested in. This could be done.

What I'd *really* like is to be able to have several module listing
windows -- one for the standard OCaml libraries, one for the LablGtk
interfaces, one for the application program I'm browsing, etc.  

> > * One feature that I'd REALLY like would be the ability to click on a use
> > of an identifier and be transported to its def-site.  Similarly, I'd like
> > to be able to click on a declaration in a .mli file and be taken to the
> > corresponding definition in the .ml file.  I guess doing this right 100%
> > of the time might be hard (at least, it might require help from the
> > compiler), but I'll bet a simple guess would usually be OK.
> 
> You can. Because of the Amazon patent, this is not single click:
> first type check the file you are browsing with Alt-t, then
> double click once on the identifier to get to its interface
> declaration, and then press either Impl (for implementation) or Intf
> (for the interface, including comments).
> It should be 100% correct.

Wonderful!!

Wouldn't it be possible to make the typechecking step automatic -- do it
the first time someone clicks on an identifier?

> > * I was never able to make the search functions work (which is precisely
> > what would have made it REALLY useful).  
> 
> That's pretty strange. You just have to input a defined name in the
> entry field and press Search. Remark that it can take a long time when
> you do it for the first time, since it must load all the .cmi in the
> load path.

I don't remember what I was having trouble with before, but it does seem
to work fine now.

> I would suggest you first read the 2 pages in the manual describing
> how ocamlbrowser works, they should answer some of your questions.
> In particular it explains how to search using type patterns.

It would be nice if this information were somehow available from the
program itself.  (In Unison we do this by simply dumping the HTML
documentation into a text file using Lynx, cutting it up into sections
using some not-too-ugly hacks, and build a menu from these.  The result
is not as pretty as it might be, but it seems to get the job done.)
Another alternative is something like tool-tips.


Two last items for the wish list: 

  * It would sometimes be really helpful to be able to see a module
    dependency graph beginning from the present module, to get a sense of
    how things fit together. 

  * Some kind of outline mode for implementations would be nice.

Whew -- that should keep somebody busy for a while.

      Benjamin

-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr