[m-rev.] split-screen source linking

[Mark Brown]

On 06-Nov-2001, Mark Brown <dougl at cs.mu.OZ.AU> wrote:
> On 05-Nov-2001, Ralph Becket <rafe at cs.mu.OZ.AU> wrote:
> > Mark Brown, Friday,  2 November 2001:
> > > +	if (server->split) {
> > > +		/*
> > > +		** When in split mode, we use the bottom two windows on
> > > +		** the vim server.  The window second from bottom (which
> > > +		** will usually be the top window) displays what would be
> > > +		** shown in non-split mode.
> > > +		**
> > > +		** If there is no parent context (e.g. at internal events)
> > > +		** we leave the bottom window alone.
> > > +		**
> > > +		** If we have a parent context it will be displayed in the
> > > +		** window second from bottom.  So in this case we show the
> > > +		** current context in the bottom window.
> > > +		*/
> > 
> > This seems like it's going to look odd to me.  My original idea was
> > that all the "action" would occur in the lower window, with the top
> > window showing the return location.  What you describe here sounds
> > like the lower (callee) window can occasionally contain misleading
> > (out of date) information.
> 
> My view is that the "action" is at the call site, rather than the
> definition.  The reason for this is that to understand how execution
> proceeds through a procedure body, we want to look at the internal
> events of that procedure in conjunction with the interface events of the
> *children* of that procedure.  So we want to consider each interface
> event in its role as child of its caller, rather than its dual role as
> head of the callee.  This is why, in single-window mode, we show the
> caller rather than callee at interface events.
> 
> At interface events in split-window mode, the upper window shows the
> caller and the lower window shows the callee, which is what your original
> suggestion was (although I consider the action to be in the top window).
> Internal events, however, refer to a compound goal rather than a call
> site; as such, there is no caller/callee, just a single location in a
> source file.  Clearly we should display this location in the "action"
> window, but what should the other window show?
> 
> I have chosen to display the internal event in the top window, and leave
> the other window unchanged, which means that it will still show the body
> of the last call made.  I agree that this information is, in a sense, out
> of date.  But we don't really have any useful information to put there,
> and I think if there is a change in that window at all, then the user will
> see a noticeable flicker which is likely to draw their eyes down to that
> window.  This may, in effect, mislead them into thinking that there is
> useful information in that window.
> 
> Is there something specific you would rather see displayed in the
> non-action window, at internal events?
> 

Several of us discussed this issue face to face.  We decided to keep the
contents of the two windows as I have described it above, but to swap
the locations of the two windows.  So the "action" window still shows
the caller at interface events, but it is now the lower window rather
than the upper one.

The reason behind this decision is that we felt the user's eyes would
naturally be drawn to the lower window, since in an xterm the action
usually occurs at the bottom.

> I won't check it in yet, since I haven't yet updated the documentation
> as you suggested.  Below is the relative diff of the changes so far.
> 

Below's the rest of the change and new log message.  I'll commit this soon,
after I have finished testing.

Cheers,
Mark.

Estimated hours taken: 3.75
Branches: main

Implement a split-screen version of source linking for mdb.  The lower
window shows what would normally be shown in the full window.  This
includes displaying the parent context at interface events.  The upper
window shows the current context (the callee) at interface events.

Split screen mode is enabled with the '-2' or '--split-screen' options
to 'view'.

trace/mercury_trace_source.h:
	Add a 'split' field to the struct which holds server info.

trace/mercury_trace_source.c:
	Handle split screen mode when opening a server and when
	synchronising.

	Factor out some common code into MR_trace_source_jump().

	Close the server with ":qall" instead of ":q".

	Repair an earlier oversight: pass the verbose flag in a call
	to MR_trace_source_check_server().

trace/mercury_trace_internal.c:
	Parse the new option and pass its value around where required.

	Set the split field in the server info before starting a
	new server.

	When synchronising, pass both parent and current contexts
	(if available).

doc/user_guide.texi:
	Document the new option.

NEWS:
	Mention the new source-linking feature.


diff -u doc/user_guide.texi doc/user_guide.texi
--- doc/user_guide.texi
+++ doc/user_guide.texi
@@ -2392,7 +2392,7 @@
 at the location of the current event.
 As mdb stops at new events,
 the window is updated to track through the source code.
-This requires a version of @samp{vim}
+This requires X11 and a version of @samp{vim}
 compiled with the client/server option enabled.
 @sp 1
 The debugger only updates one window at a time.
@@ -2415,9 +2415,19 @@
 Instead it attempts to close that window first.
 @sp 1
 The option @samp{-2} (or @samp{--split-screen})
-starts the vim server with two windows.
-This allows both the callee as well as the caller
+starts the vim server with two windows,
+which allows both the callee as well as the caller
 to be displayed at interface events.
+The lower window shows what would normally be seen
+if the split-screen option was not used,
+which at interface events is the caller.
+At these events,
+the upper window shows the callee definition.
+At internal events,
+the lower window shows the associated source,
+and the view in the upper window
+(which is not interesting at these events)
+remains unchanged.
 @sp 1
 The option @samp{-w} (or @samp{--window-command}) specifies
 the command to open a new window.
diff -u trace/mercury_trace_source.c trace/mercury_trace_source.c
--- trace/mercury_trace_source.c
+++ trace/mercury_trace_source.c
@@ -45,12 +45,12 @@
 #define MR_SOURCE_SERVER_RESET_STRING           "<C-\\><C-N>"
 
 /*
-** These vim commands split the screen, move to the bottom window, and
-** move up one window, respectively.
+** These vim commands split the screen, move to the top window, and
+** move down one window, respectively.
 */
 #define MR_SOURCE_SERVER_SPLIT_STRING		"<C-W>s"
-#define MR_SOURCE_SERVER_BOTTOM_STRING		"<C-W>b"
-#define MR_SOURCE_SERVER_UP_STRING		"<C-W>k"
+#define MR_SOURCE_SERVER_TOP_STRING		"<C-W>t"
+#define MR_SOURCE_SERVER_DOWN_STRING		"<C-W>j"
 
 /*
 ** This vim command centres the current window on the cursor.
@@ -383,25 +383,29 @@
 
 	if (server->split) {
 		/*
-		** When in split mode, we use the bottom two windows on
-		** the vim server.  The window second from bottom (which
-		** will usually be the top window) displays what would be
-		** shown in non-split mode.
+		** When in split mode, we open two windows on the vim
+		** server, a primary window and the secondary window.  The
+		** primary window displays what would normally be shown in
+		** non-split mode.
 		**
 		** If there is no parent context (e.g. at internal events)
-		** we leave the bottom window alone.
+		** we leave the secondary window alone.
 		**
 		** If we have a parent context it will be displayed in the
-		** window second from bottom.  So in this case we show the
-		** current context in the bottom window.
+		** primary window, so in this case we show the current
+		** context in the secondary window.
+		**
+		** The primary window is the one second from the top (which
+		** will usually be the bottom window).  The secondary window
+		** is at the top.
 		*/
 
 		if (have_parent && have_current) {
-			/* Move to the bottom window. */
+			/* Move to the secondary (top) window. */
 			status = MR_trace_source_send(real_server_cmd,
 					server->server_name,
 					MR_SOURCE_SERVER_RESET_STRING
-					MR_SOURCE_SERVER_BOTTOM_STRING,
+					MR_SOURCE_SERVER_TOP_STRING,
 					verbose);
 			if (status != 0) {
 				return "warning: source synchronisation failed";
@@ -414,24 +418,24 @@
 				return msg;
 			}
 
-			/* Move up one window. */
+			/* Move down one window to the primary. */
 			status = MR_trace_source_send(real_server_cmd,
 					server->server_name,
 					MR_SOURCE_SERVER_RESET_STRING
-					MR_SOURCE_SERVER_UP_STRING,
+					MR_SOURCE_SERVER_DOWN_STRING,
 					verbose);
 			if (status != 0) {
 				return "warning: source synchronisation failed";
 			}
 		} else {
 			/*
-			** Move to the second from bottom window.
+			** Move to the primary (second from top) window.
 			*/
 			status = MR_trace_source_send(real_server_cmd,
 					server->server_name,
 					MR_SOURCE_SERVER_RESET_STRING
-					MR_SOURCE_SERVER_BOTTOM_STRING
-					MR_SOURCE_SERVER_UP_STRING,
+					MR_SOURCE_SERVER_TOP_STRING
+					MR_SOURCE_SERVER_DOWN_STRING,
 					verbose);
 			if (status != 0) {
 				return "warning: source synchronisation failed";
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------