source: trunk/athena/bin/xdsc/xdsc.1 @ 6127

.\" This file uses -man macros.
.TH XDSC 1 "May 14, 1992"
.SH NAME
\fIxdsc\fR \- X interface to the discuss system
.SH SYNOPSIS
.B xdsc
.SH DESCRIPTION
The
.I xdsc
program provides a window-oriented user interface to the discuss system.
It currently uses an \fIedsc\fP co-process which does the actual
communication with \fIdiscuss\fP.  By default, \fIxdsc\fR
runs '/usr/athena/etc/edsc'.  If you 
want it to use a a different \fIedsc\fP, set the environment variable
EDSC to its full pathname.

.SH BASIC SCREEN LAYOUT
\fIxdsc\fR displays a single window, divided into five areas:
.TP 4
.B \-
A row of eight buttons, some with pull-down command menus.
.PP
.TP 4
.B \-
A text window containing a listing of the meetings which the user attends.
This window can be also used to display a listing of the transactions
within a single meeting.
.PP
.TP 4
.B \-
A single line of text displaying the current status.
.PP
.TP 4
.B \-
A row of seven buttons, some with pull-down command menus.
.PP
.TP 4
.B \-
A second text window, used to show the text of the current transaction.
.PP
Also, an assortment of popup windows will appear as necessary.  These
are intended to be self-explanatory.

.SH USING XDSC
This section will provide an introduction on how to use \fIxdsc\fR.
It explains how to read transactions, how to add and
delete meetings from the list of meetings you attend, and how to
enter transactions of your own.
Each \fIxdsc\fR command button is explained.

.SS UPPER TEXT PANE
The upper text pane initially contains a listing of the meetings you
attend.  The current meeting, i.e., the one from which you are
reading transactions, will have a plus sign ("+") next to it.  
To change meetings, you
can either double-click on a meeting's line with mouse button one, use
the \fIUp\fP and \fIDown\fP buttons, or use the arrow keys as described
under "Keyboard Equivalents" below.
If this
is the first time you have used \fIdiscuss\fP in any form, only two
meetings will be listed, namely "New_meetings" and "Everybody."  
You can use the \fIconfigure\fP button, as described below,
to add more meetings.

Changed meetings, i.e., those with new transactions, will have a "c" 
next to their name.

This window can also be used, via the \fImode\fP button, to show a list
of transactions within the current meeting.  In this mode, doubleclicking 
on a transaction's line with button one will cause the transaction's text
to be displayed in the lower window.

.SS UPPER CONTROL AREA
The upper control area contains commands of a global nature:

.TP 8
.B Down
Moves the current meeting to the next one with unread transactions.  If there
is no such meeting, a warning popup will appear.
.TP 8
.B Up
Moves the current meeting to the previous one with unread 
transactions.  If there is no such meeting, a warning popup will appear.
.TP 8
.B update
Queries \fIdiscuss\fP for an updated meeting list.  The new list will reflect
any transactions which may have come in since the last update, as well
as any changes the user may have made to the list of meetings attended.
.TP 8
.B configure
Pops up a menu with two entries:  \fIadd meeting\fP and \fIdelete meeting\fP.
These are used to modify the list of meetings you attend.  Selecting
one of these items will pop up a dialog box with fields to fill in;
these fields may be cryptic to the novice, but fear not:  If the
current transaction is the announcement of a new meeting, the fields
will already be filled in, and the user need only confirm the action
by pressing the \fIAdd\fP or \fIDelete\fP button at the bottom of the 
dialog box.

The typical procedure for adding new meetings is as follows:  Read the
New_meetings meeting by swiftly double-clicking on its line in the upper
text pane.
Move through meeting announcements with the \fInext\fP and \fIprev\fP
buttons,
and add the meetings which seem interesting by selecting \fIadd meeting\fP
from the \fIconfigure\fP menu and pressing the \fIAdd\fP button at the bottom
of the dialog box.

You will need to press \fIupdate\fP before these new meetings will appear
in your list of meetings.
.TP 8
.B mode
Pops up a menu with two entries:  \fItransactions\fP and \fImeetings\fP.
Selecting either of these makes the upper window display either a list
of transactions in the current meeting or a list of meetings attended, as 
appropriate.  Note that while in "transactions" mode, you cannot
move between meetings.
.TP 8
.B show
This button is only active while in transactions mode, as it controls
which transactions are listed.
It pops up a menu with three entries:  \fIunread\fP, \fIall\fP 
and \fIback ten\fP.
\fIunread\fP causes the unread transactions to be listed.  \fIall\fP summons up
a list of all transactions in the meeting (Danger!  This can take
a while!).  Finally, \fIback ten\fP adds the ten immediately previous
transactions to the
top of the list, and is usually used for searching backwards for a
recent transaction.
.TP 8
.B HELP
Displays a screen of help, briefly explaining what the buttons
currently on the screen do.  To get rid of this screen, press the
\fIdismiss\fP button at its bottom.
.TP 8
.B QUIT
Exits the application.
.SS STATUS LINE
The status line briefly summarizes what \fIxdsc\fP is doing at the moment.
It typically lists 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 \fIxdsc\fP is doing something which may take a while, such as
reading the headers for all the transactions in the "Everybody" meeting.
.SS LOWER TEXT PANE
The lower text pane contains the text of the current transaction,
or is blank if there is no current transaction.
.SS LOWER CONTROL AREA
The lower control area contains commands which operate on the current
transaction or meeting.
.TP 8
.B next
Moves to the next transaction in the current meeting.
.TP 8
.B prev
Moves to the previous transaction in the current meeting.
.TP 8
.B Next in chain
Moves to the next transaction in the same chain as the current transaction.
.TP 8
.B Prev in chain
Moves to the previous transaction in the same chain as the current transaction.
.TP 8
.B goto
Pops up a five-entry menu, containing \fInumber\fP, \fIfirst\fP, 
\fIlast\fP, \fIstart of chain\fP, and \fIend of chain\fP, used for 
moving to specific transactions.  
Selecting \fInumber\fP
pops up a dialog box prompting you for a specific transaction number
to go to.  
Selecting \fIfirst\fP or \fIlast\fP moves to the first or last transaction
in the current meeting.
Selecting \fIstart of chain\fP or \fIend of chain\fP moves to the start or end
of the current chain of transactions.
.TP 8
.B enter
Is used for entering a transaction in the current meeting.  It pops
up a menu with two entries, \fIreply\fP and \fInew transaction\fP.
Selecting
\fIreply\fP will add the transaction to the chain of the current
transaction, while \fInew transaction\fP starts a chain.

After you select one of these entries, a dialog box will appear with
a subject line and a text widget.  For replies, the subject line will
have a default already filled in, while new transactions will have a 
blank subject line which the user should fill in.  The text widget 
is a standard Athena text widget, where you can use emacs commands
to enter the body of your transaction.

When done entering the body of your transaction, press the \fISend\fP button
to enter the transaction into the meeting.  Press \fIAbort\fP if you 
chicken out and decide not to send the transaction.
.TP 8
.B write
Is used for writing the current transaction to a file.  It pops up a
dialog box where the user can enter a file name, and pressing the
\fIWrite\fP button causes the transaction to be written out to this file.
The \fImail to someone\fP feature is not currently available.

.SH 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,
and hitting this key has exactly the same action as pressing the button
itself.   Note that uppercase and lowercase letters can be distinct.
For example,
the lowercase
"n" and "p" keys are synonyms for the \fInext\fP and \fIprev\fP buttons, 
for going
to the next and previous transactions, while uppercase "N" and "P"
stand for \fINext-in-chain\fP and \fIPrev-in-chain\fP.

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.

When a simple popup dialog box appears, such as goto-number, pressing
return will make it do its default action.  You can abort a dialog
box by pressing ESC.  For complex dialog boxes, i.e. those with more
than one text field, return moves focus between the text fields
and control-return makes it do its default action.

The arrow keys can be used to move the text caret up and down in the
upper text window.  Pressing return then reads whatever meeting or 
transaction the caret is sitting on.

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.

.SH FILES
~/.meetings - \fIdiscuss\fR's list of meetings attended and transactions read.
.br
/usr/tmp/xdsc* - temporary files.
.SH SEE ALSO
discuss, edsc, X Toolkit Intrinsics, Athena Widget Set
.SH COPYRIGHT
Copyright 1991, Massachusetts Institute of Technology
.SH AUTHOR
Andy Oakland, MIT Project Athena