\documentstyle[guidemacros,psbox]{report}
\stdsizes

%\newcommand{\draft}[1]{{\huge #1}}

\title{Xdsc: A graphical interface to discuss}
\author{Andy Oakland}
\date{\today}
\maketitle

\begin{document}

\section{Background}
The discuss system is a much-used means for electronic communication
unique to MIT.  Thanks go to the members of SIPB for developing
this resource, entirely on volunteered time.
Many important announcements and discussions can
be found in discuss.  Unfortunately, the existing interfaces can be very
difficult for the casual user to use, so much of what goes on in discuss
can be lost to him.  This document describes
xdsc, a graphical interface to discuss designed specifically to be
easy for the novice user to use for simple tasks, while making more 
complex actions possible for the more advanced user.

\subsection{Existing interfaces}
There are currently two frequently used interfaces to discuss.  First, 
the command-
line interface, and secondly, the Emacs interface.  The command-line
interface is verbose and awkward to use, requiring for example that
the user type the word "next" followed by a newline to see the next
transaction.  Although abbreviations exist for many commands, they
are not obvious ones, and how to do
actions such as adding a meeting to one's .meetings
file are not immediately clear.  A list of discuss's standard
commands is given in Appendix 1.

The Emacs interface is much more terse, and is very useful to the
more advanced user.  Unfortunately, it (naturally) assumes that the
discuss reader is also a seasoned Emacs user, an assumption which
frequently does not hold.  A screen dump of the Emacs interface is
given as figure 3.

\subsection{Reason for xdsc}
Xdsc was designed to offer an inviting "point-and-click" interface to 
discuss for the novice user, with keyboard equivalents making it
possible for a more advanced user to move quickly through discuss
without ever touching the mouse.

It also adds utility to discuss by facilitating random access
to individual transactions, thereby increasing the value of the
discuss database.

\section{General appearance of xdsc}
The screen of xdsc resembles the screen of xmh.  This was chosen because
xmh is already a familiar tool on the MIT campus, and users of xmh will
find that many operations have parallels on xdsc.
\subsection{Top half of screen}
The screen is split into two basic sections, as shown in figure 1.  The
top half provides a "bird's-eye" view of discuss...Depending on the
mode selected, it displays either a list of the meetings the user attends,
with the current meeting indicated with a "+" and changed meetings marked
with a "c", or a list of the transactions in the current meeting. The
latter is shown in figure 2.

While the list of transactions is displayed, the user can search over
the transactions' subject lines for specific items.

The buttons above this display control top-level functions of xdsc, such
as asking for help and adding or deleting meetings,
as well as functions affecting
the text displayed in the upper window.  Examples of the latter are
the up and down arrows, for moving to the next or previous changed
meeting.

\subsection{Lower half of screen}
Between the two halves is a line of text showing the current status.
This typically includes the current meeting,
the range of transaction numbers within this meeting, and the current
meeting number.  This line is also used for status messages when
appropriate.

The lower half always shows the text of the current transaction.  The
buttons above this text control operations which work on the
individual transaction level.  For example, the user can move to the
next or previous transaction in a chain, go to a specific transaction,
or write the current transaction to a file.

\section{Using xdsc}
\subsection{From the mouse}
From the simplest point of view, all one needs to do to use xdsc is point
and click.  Most buttons, such as "Next in Chain," will immediately
have an obvious consequence.  Some, such as "configure," will pop up
a sub-menu, from which an entry should be selected.  Buttons will
turn gray and inactive when their functions are not available, such
as "Next in chain" when there is no such transaction for the button to
display, or "enter" when the user is reading a meeting in which he cannot
enter transactions.

When the upper window is listing the meetings you attend,
clicking on a meeting with mouse button two moves you into that meeting
and puts the text of the first new transaction in the lower window.  When
it is listing the transactions within a meeting, clicking with button
two on a transaction's line displays the text of that transaction.

Button two is used instead of button one, so that press-drag-release
selections can be made using button one without surprising side
effects.  Also, this is similar to xmh's behavior.

\subsection{Keyboard equivalents}
Xdsc has been designed to minimize dependance on a mouse.  Nearly every
function can be accessed with one or two keystrokes, and the user's hands
almost never need to leave the keyboard.  The keyboard equivalent for
any button is always the first letter of its label
\footnote{This required a bit of work to ensure all buttons had sensible 
labels which still began with unique letters!}
and hitting this key has exactly the same action as pressing the button
itself.  

A few actions, such as placing popup windows and moving to meetings
without new transactions, do require mouse motion.  This is an issue
which should be addressed.

If a button triggers a menu, the menu will appear in stay-up
mode and take focus.  Hitting a key corresponding to the first letter
of a menu entry will fire off that entry and pop down the menu.  Any
key which does not match a menu entry will abort the menu and pop it
down without any action.

The concept of first-letter-matching is stretched somewhat in minor
ways.  The buttons with arrow pixmaps have no initial letter, so the
arrow keys themselves are used as keyboard equivalents.  The lowercase
"n" and "p" keys are synonyms for the left and right arrows, for going
to the next and previous transactions, while uppercase "N" and "P"
stand for next-in-chain and prev-in-chain.  

Finally, in a way similar
to rn, the space bar is bound to "do the right thing."  If the user is
reading a transaction, the space bar will scroll one page down.  If at
the end of a transaction, it moves to the next transaction, and if at
the end of a meeting, it moves to the next-changed meeting.  If there
are no further transactions to read, it does nothing.  Backspace moves
in a similar way, but backwards.

\subsection{Special translations for popups}
When a popup appears, keyboard focus moves to it.  There are
special translations for some keys in a popup:
\begin{description}
\item[Return]
For single-line text fields, it moves focus to the "next"
textfield, if there is one.
\item[Ctrl-Return]
Makes a popup do its default action.  This means sending
a transaction, etc.
\item[Escape]
Aborts a popup without doing anything.
\end{description}
Finally, all the above-described keys can be remapped 
by editting the .Xresources file.

\section{Internals}
\subsection{Interface to edsc}
Athough xdsc appears to be a free-standing application, it is actually
an interface to edsc, the Emacs discuss client.  When xdsc is started,
it in turn starts an edsc in the background and opens a two-way pipe
to it.  As the user selects buttons and transactions, xdsc builds up
edsc command lines, feeds them to the edsc co-process, and parses the
result before updating the display.

It may be possible to realize significant gains in size and speed by
eliminating the edsc co-process and having xdsc call the discuss
libraries directly.  The chance of this, though, must be weighed
against the significant rewriting of xdsc that would be necessary
to make such calls.  Advice on whether this would be worthwhile
is hereby solicited from those familiar with the discuss libraries!

\subsection{Caching}
Xdsc keeps its perceived speed high by caching the transactions most
likely to be asked for next.  When any transaction is displayed, xdsc
caches the text of the next and previous transactions, as well as
any next-in-chain or prev-in-chain transactions which may exist.

When the user hits one of the buttons selecting one of these transactions,
xdsc immediately displays the text of the transaction from its cache,
and updates the cache in the background as the user is reading the 
new transaction.

Keeping a more-intelligent cache, such as one which predicts the direction
the reader is travelling in and prefetches multiple transactions in
that direction, may speed up the process further.

\subsection{Input focus and accelerators}
In order to make it possible to use xdsc from the keyboard in the
simplest way, the dialog boxes grab focus as they pop up.
Combined with the accelerators listed above, this makes it possible
to pop up a dialog box from the keyboard, fill it in, apply it,
and return to the main screen without ever touching the mouse.

Further work should be done on making the input focus manipulation
routines and other keyboard equivalents and accelerators more easily
available to the advanced user.  The existing functions are usable, but
expect user-unfriendly numeric arguments instead of more meaningful
string arguments.  The app-defaults table for xdsc is listed as
Appendix 2.

\subsection{Keyboard equivalents}
I decided that it was important, from a user interface viewpoint,
that all buttons highlight or give other feedback when their keyboard 
equivalent was hit.
This was done by giving each key used as a keyboard equivalent
an accelerator to call a common keystroke-handling routine with
an identifier for the button it matches.  This routine then
constructs a synthetic ButtonPress event, which it sends to the
appropriate button.  For normal command buttons, the appropriate
ButtonRelease event is also sent.

Menu buttons are not sent a ButtonRelease event, which causes them to
pop up their menu and keep it up.  Each menu grabs keyboard focus as
it pops up.  Each menu has a unique set of translations
for key presses on it, which are the keyboard equivalents for the menu
entries.  These call a routine which pop down the menu and return
focus to the main pane, as well as calling the button's callback.

\section{Design process}
Many thanks go to John Kohl and Ralph Swick as the most vociferous testers
of early versions of xdsc.  They and the other readers of the 
Xdsc\_Suggestions meeting made dozens of worthwhile comments, 
many of 
which were soon reflected in improved versions of xdsc.  A few of the 
many changes made in direct response to user requests were:
\begin{itemize}
\item Moving the status line to the middle of the screen to minimize eye 
movement while reading.
\item The goto-number feature, which allows the user to read a
specifically-numbered transaction.
\item Use of mouse button two instead of button one on the upper pane,
allowing press-drag-release selection.
\item Ability to reply to multiple transactions simultaneously.
\item Use of pull-down menus and bitmaps for some buttons.
\end{itemize}
\section{Conclusion}
Xdsc has been in trial use for several months, and has won many converts.
The high traffic in the Xdsc\_Suggestions meeting shows both that
many people are using xdsc in preference to the other interfaces,
and that there is still some work to be done.  I believe, though, that
it has reached a sufficiently high level of stability that it
should become an officially supported tool.
\newpage
\PSbox{/afs/athena.mit.edu/user/s/sao/x/doc/pix/full.mtg.ps}{6in}{6in}
\begin{center}
Figure 1
\end{center}
\newpage
\PSbox{/afs/athena.mit.edu/user/s/sao/x/doc/pix/full.trn.ps}{6in}{6in}
\begin{center}
Figure 2
\end{center}
\newpage
\PSbox{/afs/athena.mit.edu/user/s/sao/x/doc/pix/emacs.ps}{6in}{8in}
\begin{center}
Figure 3
Emacs interface
\end{center}
\newpage
\begin{tt}
\include{/afs/athena.mit.edu/user/s/sao/x/doc/pix/discuss.cmds}
\end{tt}
\begin{center}
Appendix 1
\end{center}
\newpage
\begin{tt}
\include{/afs/athena.mit.edu/user/s/sao/x/doc/pix/Xdsc.app}
\end{tt}
\begin{center}
Appendix 2
(See following pages)
\end{center}
\end{document}