[An Andrew ToolKit view (a drawing) was included here, but could not be
displayed.]

                                                           NEOS on Athena
                                                            Student Guide

                                                          Dorothy L. Bowe


                                                         3 September 1991
                                                                Version 2





                Copyright  c  1991  Massachusetts Institute of Technology
.bp 0
                            COPYRIGHT NOTICE

Copyright  c  1990, 1991 by Massachusetts Institute of Technology (MIT).

Permission to use, copy, modify, and distribute this documentation for
any purpose and without fee is hereby granted, provided that the above
copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation,
and that the name of MIT not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.  MIT makes no representations about the suitability or
merchantability of this software for any purpose.  It is provided "as
is" without express or implied warranty.


                            TRADEMARK NOTICES

Project Athena, Athena, Athena Dashboard, Athena MUSE, Discuss, Hesiod,
Kerberos, Moira, X Window System, and Zephyr are trademarks of the
Massachusetts Institute of Technology (MIT).  No commercial use of these
trademarks may be made without prior written permission of MIT.


                            REVISION HISTORY

Version 2 (3 Sep 91, Dorothy L. Bowe): Revised draft for Athena 7.3;
Kevin Cunningham converted document to EZ format.

Version 1 (Dorothy L. Bowe): Original draft.
.bp 1
.rm CT
.ds LB Athena:  September 1991
.ds CB %
.ds RB NEOS on Athena (Student Guide)
   Introduction

  What is NEOS?

The Networked Education Online System (NEOS) is a set of programs for
classroom oriented file exchange. NEOS is intended to mimic operations
normally performed with paper in and out of class.  There are files
which represent assignments handed in, annotated assignments handed
back, and   handouts produced by the teacher for reference. Finally,
there are files submitted for exchange, as one might trade papers for
peer review.

There are two interfaces to NEOS: one command-line oriented and one
based on the Andrew toolkit using the Andrew EZ editor.  Both versions
use the same underlying software and perform the exact same function, so
choosing between them can be a matter of preference, or can depend on
the type of "document" a user will turn in.

NEOS consists of programs for students to run, and other programs for
graders to run:

 -----------------------------------------------------------
  Command     Function
 -----------------------------------------------------------
 Students:

  eos         an editor with full multi-media functionality for
              turning in, picking up, and exchanging papers

  turnin      a command line interface for turning in assignments

  pickup      a command line interface for picking up annotated
              assignments
 -----------------------------------------------------------
 
-----------------------------------------------------------
  Command     Function
 -----------------------------------------------------------
 Graders:

  grade       an editor with the full multi-media fuctionality for
              grading and annotating in a window environment

  collect     a command line interface for collecting assignments 

  turnin      a command line interface for submitting handouts

  return      a command line interface for returning assignments 

  uncollect   a command line interface for uncollecting assignments 
              you did not mean to take for grading

  fxpurge     a command line interface for removing assignments from
              the NEOS server which are no longer needed.
 -----------------------------------------------------------

  Before You Begin

The programs eos and grade are window applications built upon the Andrew
toolkit. Before you attempt to use these programs, you should read the
document Essential EZ on Athena, available from MIT Graphic Arts Copy
Centers, W20-028 and 11-004.


  Command Line and Windowing Environments

NEOS allows you the flexibility of working in either a windowing
environment or on the command line. The window applications are built
upon the Andrew toolkit and offer all of the multi-media capabilities of
EZ, a WYSIWYG (What You See Is What You Get) editor. For more
information on EZ see Essential EZ on Athena.
   Configuring to Use NEOS

Only courses which have made arrangements with Athena will be able to
use the NEOS applications.  Faculty members interested in using these
programs for their classes should contact the Faculty Liaison Office at
x3-0115 or send mail to f_l@athena.

  Setting the Path

As of Athena Release 7.2 (January, 1991), all of the NEOS programs are
available to you without attaching any lockers. If you used the command
line versions, turnin and pickup, in the past, you no longer need to add
/mit/eos/vaxbin or /mit/eos/rtbin to your path, and you should remove
any references to these directories in your startup files.

  Selecting a Course

In order to use the NEOS applications, you must specify the course
number for which you are handing in assignments. If you will always be
working in same course, you can set the environment variable COURSE by
adding the following line to your ~/.environment file in your home
directory:

    setenv COURSE course-number

where course-number is the number assigned to your course and recitation
section; get this number from your TA.

If you prefer, or if you are taking more than one course using NEOS, you
can also specify a course number on the command line using the -course
option (-course can be abbreviated -c) of eos, turnin, and pickup:

    athena% eos -course 21.007

or

    athena% turnin -c 21.007

eos allows you to change the course after starting the program by
selecting the Change Course option on the first pop up menu card. (For
more information on using menu cards, see the Essential EZ On Athena 
document.) If you have not set the course by one of these three means
and try to hand in a paper, pickup handouts, or exchange papers, eos
will prompt you for the course number.
   Using the Window Version of NEOS

  Using the ez features of eos

The program eos offers the full editing capabilities of the ez editor.
Many of the editing functions can be found on the menu cards which pop
up when you press the middle mouse button in the eos window. For more
information on the editing capabilities of eos and ez, see the Essential
EZ On Athena document.
 
  Starting eos

To start eos, move the cursor into an xterm window and type the
following to your athena% prompt:

    athena% eos filename

where filename is the name of the file you wish to edit.

Like other Andrew programs, eos creates its own window when started,
with the contents of the file filename displayed. If you specify more
than one filename, each will be started in a separate buffer. (For more
information on buffers see the ez help on ez-buffers.) If no filename is
given, eos will start with an empty window, waiting for further
commands. At the top of the window are six buttons: Pick Up, Turn In,
Handouts, Exchange, Guide, and Help. To select one of these functions,
move the cursor into the appropriate button and click with the left
mouse button. (See Figure 1) 
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 1: Main Eos Window
The buttons have the following meanings:

  ------------------------------------------------------
  Button      Function
  ------------------------------------------------------
  Pick Up     Pick up any assignments which have been
              graded by your instructor.

  Turn In     Turn in an assignment for grading.

  Handouts    Get class handouts.

  Exchange    Exchange papers with others in the course.

  Guide       View the On Line Style Guide. *

  Help        Start up the Andrew help browser.
  ------------------------------------------------------
  * This feature was written for a specific class;
    unless your faculty member has instructed you to
    use it, it is probably not applicable.
  Turning in a Paper

To turn in a paper, start eos and select the Turn In button. If eos does
not know which course you are using (see section 2.2), it will ask you
in a dialog box to type the course number. A new window will then be
created, entitled "Turn In". (See Figure 2) The course you are using is
shown after the title.
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 2: Turn In Window

The new window is split into several areas. Below the title is a switch
that allows you to specify whether you want turn in either the contents
of the buffer or a file. By clicking anywhere in the area of the switch
you can toggle which source should be used for turnin.

Below the switch are two text areas, where the details of the paper
should be filled in. In the case of turning in a file which already
exists, the filename should be entered in the first text area.  When
turning in the edit buffer contents, enter an appropriate name -
something that represents the contents of the paper. There is also a
place to enter the assignment number. If you do not specify an
assignment number, eos will not allow you to turn in a paper. You should
find out from your TA what number to use for a given assignment.

After entering all necessary information, select the OK button to turn
in the assignment or the CANCEL button to abort the turn in operation.
If any errors occur during the turn in, a dialog box will appear
informing you of what went wrong. You must select the CONTINUE button in
the dialog window to acknowledge the error.

  Picking Up a Graded Paper

To pick up a paper which has been graded, cd to a directory where you
can save the returned paper and start eos. This can be (but does not
have to be) the same directory that contains the original version of you
paper. eos will create a unique name for the returned version when it
places it into your directory. If you try to pick up a paper and do not
have write permission in the current directory you will get the
following error message:

    Permission denied while receiving filename. Pick Up aborted.

When the window has appeared, select the Pick Up button at the top of
the window. If eos does not know which course you are using (see section
2.2), it will ask you in a dialog box to type the course number. A new
window will then be created, entitled "Pick Up". (See Figure 3) The
course you are using is shown after the title.
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 3: Pickup Window

Then eos will check to see if you have any assignments waiting to be
collected.  If not, the following message will be displayed:

    Reading course...
    No assignments have been returned.
    Press CONTINUE to close window.

Clicking on the CONTINUE button in that window will remove the "Pick Up"
window.

If there are assignments available, eos will display a message informing
you how many there are and begin collecting them. As each assignment is
picked up, its name will be displayed in the Pick Up window. The files
will be saved into the current directory and a copy placed into the main
edit window for you to view and/or edit. If you pick up more than one
paper, each will be saved into separate buffers, similar to emacs
buffers. (For more information on buffers, see ez-buffers in the Andrew
help.)

If you pick up an assignment that has the same name as a file which
already exists in the current directory, eos will create a unique name
for the new assignment. For example, if you pick up the assignment
assign1.c, eos will create a file with a name resembling assign1_1.c.

When all the assignments have been collected, a message will be
displayed in the Pick Up window informing you the operation has
finished. Clicking on the CONTINUE button at that point will remove the
Pick Up window.

Your graded paper may contain annotations which appear as icons
resembling a notebook page.  (See Figure 4) 
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 4: Edit Window with Annotation
To view the comments, click the left mouse button on the icon and it
will expand, revealing the text inside. To close the window, click the
left mouse button on the top border of the annotation window and it will
return to icon form. Alternatively, you can select the menu option Open
Notes on the Page menu card to open all the annotations in the buffer
and Close Notes to close them all.

(If you press the middle mouse button and do not get the full set of
popup menus, click the left mouse button anywhere in the eos window and
try to pop up the menus again.)

  Handouts

To pick up course handouts, first make sure that you start eos from a
directory in which you can save files.  After you select the Handouts
button, a new window entitled "Handouts" will be created, (See Figure 5)
containing a list of all the handouts available for the course.
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 5: Handout Window

On the side of the window are three buttons: EDIT, KEEP, and HIDE. The EDIT
and KEEP buttons operate on specific handouts; you must select which handouts
you are referring to before clicking on one of the buttons.

To select one handout, move the cursor to the text which describes it
and click with the left mouse button. The text for that handout will
then be displayed in bold, indicating it has been selected. To select
more than one handout, click with the right mouse button on each. If you
do select more than one handout, each will be displayed in a separate ez
buffer; see the Andrew help file on ez-buffers for more information.

Here is what the buttons do:

  ------------------------------------------------------------
  Button    Purpose
  ------------------------------------------------------------
  EDIT      A copy of the handout will be saved into the
            current directory, its name altered if necessary,
            to ensure it does not overwrite any existing files
            and then the file is placed into the main editing
            window, for you to edit.

  KEEP      A copy of the selected handout is saved into the
            current directory. The handout is given a name to
            ensure it will not overwrite any files currently
            existing in the directory, while still preserving
            any filename extensions, e.g. the .c extension.
            The name given to the handout will be displayed
            at the bottom of the handouts window.

  HIDE      This will close the handouts window.
  ------------------------------------------------------------

To print handouts directly from the handouts window, select the Print
selected paper(s) menu option on the menu card.  This operates on
however many handouts you have selected, sending each to the printer.
The printer name is taken from the environment variable PRINTER, or can
be set using the Set Printer option on the menu card.

  Exchanging Papers

To exchange papers with other classmates, select the Exchange button at
the top of the eos window. A new window entitled "Exchange" will appear,
with the course number shown after the title. (See Figure 6) All papers
shown in this window are available for reading by anyone in the class.
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 6: Exchange Window

This window has the same format as the Handouts window, with the
addition of a SUBMIT button which allows you to submit a file for public
viewing. Selecting this button will result in eos first asking you what
you wish to submit, either an existing file or the contents of the
current edit buffer. If you choose to turn in a file, you will
immediately be prompted for the name of the file you are submitting.
Then eos will then try to submit the paper. Once a paper has been
submitted, you can use the Update List function, found on the first pop
up menu card to see it in the list.

When viewing exchange papers, there is another option added to the menu
card: Remove selected papers(s). You can use this to delete papers which
you have submitted. If you try to delete papers which are not owned by
you, you will be informed that you are not the owner and the paper will
not be removed.

  Help

Selecting the Help button will cause the Andrew Help browser to appear,
initially displaying the help pages on eos. To make this window
disappear, select the Quit option on the first menu card.
   Using the Command Line version - turnin and pickup

  Using turnin for Assignments

The turnin command can be used to turn in assignments or papers for
exchange. The format of the command is:

    athena% turnin [options] [assignment number] file [...]

The notation, [...] means that you can turn in more than one file for a
particular assignment - but they will all have the same assignment
number!  For example, the following command turns in both test.c and
main.c as assignment 5:

    athena% turnin -course 1.00 5 test.c main.c


To set the course number for turnin, you can use the COURSE environment
variable or the -course option. For example, to turn in the paper
essay.tex to course 21.780 you could do either of the following:

    athena% setenv COURSE 21.780
    athena% turnin essay.tex

or

    athena% turnin -course 21.780 essay.tex

To specify the assignment number add it to the command line after all
options but before the filename:

    athena% turnin -course 21.780 5 essay.tex

This hands in essay.tex for assignment 5 of course 21.780.  Note: If you
forget to specify an assignment number, the default will be assignment
1. You will see a warning message specifying this.

  Using Pickup

The pickup command allows you to retrieve assignments which have been
graded. Like turnin, pickup recognizes either the COURSE environment
variable or the -course command line option.  The format of this command
is

    athena% pickup [options] [+n] [-n] [assignment number] [filename...]

For example, to pickup graded files for assignment 3 for course 1.00,
you could use the following command:

    athena% pickup -course 1.00 3

To list the papers which are available for pickup without actually
retrieving them, use the -list option:

    athena% pickup -list 4

This lists all the papers graded for assignment 4 in the course
determined by the COURSE environment variable.

Any option which does not begin with a hyphen or a digit is a filename,
so you should use file names which do not begin with a digit.  If no
filenames are specified on the command line, all files will be
retrieved. Using the +n and -n options, you may specify a range of dates
on the papers you wish to pickup. For more information on these and
other command line options, type man pickup at the athena% prompt.

  Using Pickup For Handouts

You can also retrieve course handouts using the pickup command by
specifying the -handout option.  For example, to pick up the handouts
for course 1.12, you could use the following command:

    athena% pickup -handout -course 1.12

which will place copies of all the available handouts into the current
directory. The list option can be used in conjunction with the -handout
option to list available handouts.
   Where to Go for Help

Man pages are available for all the NEOS applications described in this
document. To access the man pages type the following commands at the
athena% prompt:

    man turnin (or eos, etc.)

When all else fails, help is available from the Faculty Liaison Office
at x3-0115 or send mail to f_l@athena.
