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

                                                           NEOS on Athena
                                                                 TA 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 (Ta 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 - Grade

  Using the ez features of grade

The program grade 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 grade window. For more
information on the editing capabilities of grade and ez, see the
Essential EZ on Athena document.
 
  Starting Grade

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

    athena% grade

Like other Andrew programs, grade creates its own window when started. 

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 Grade Window
The buttons have the following meanings:

  ------------------------------------------------------
  Button      Function
  ------------------------------------------------------
  Grade       Grade turned in papers.

  Return      Return graded papers

  Handouts    Get or pass out class handouts.

  Exchange    Exchange papers with others in the course.

  Guide       View the On Line Style Guide. 

  Help        Start up the Andrew help browser.
  ------------------------------------------------------ 

  Grading  a Paper

To papers for grading, start grade from a directory in which you can
write files.  If you do not have write permission in the current working
directory, grade responds with the following error message when you
attempt to retrieve files:

    Permission denied while receiving filename.

After starting grade, select the Grade button at the top of the main
window.  If grade does not know which course you are using when you
click on this button (see section 2.2), a dialog box will appear, asking
for the course number.  A new window entitled "Papers to Grade" will
appear with the course shown after the title.  A list of all papers that
have been turned in and are available to grade is displayed in the
window.  There is a set of buttons to the right of the list of papers: 
OLD DOCS/NEW DOCS, DISPLAY, EDIT, KEEP, and HIDE.  
[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 2: Selecting a Paper to Grade
These buttons have the following meanings:

  ----------------------------------------------------------------
  Button      Function
  ----------------------------------------------------------------
  OLD DOCS/   Toggle behavior between OLD DOCS and NEW DOCS.  
  NEW DOCS    When grade is first started, the window displays
              new docs, those papers not yet graded and
              available to be selected for grading.  The button
              label is OLD DOCS.  Selecting OLD DOCS displays
              old docs in the window, papers that have already
              been graded and returned, and toggles the label 
              to NEW DOCS.
 
  DISPLAY     Display a text file in a large font without
              marking it as taken for grading.

  EDIT        Place a copy of the selected assignments into
              the main edit window for annotation.  This is
              the recommended way of grading papers.

  KEEP        Save a copy of the selected assignments into
              the current directory and mark each as taken.
              Keeping a papers means that other graders will
              not see the assignment when they start grade.

  HIDE        Close the window.
   ----------------------------------------------------------------

  Selecting Papers

The DISPLAY, EDIT, and KEEP buttons operate on specific papers in the
list.  You must select papers before clicking on one of these buttons.

To select a paper, move the cursor anywhere within the text which
describes the paper and click with the left mouse button.  The test for
that paper will then be displayed in bold, indicating it has been
selected.  To select more than one, click with the right mouse button on
each.

After selecting the paper or papers you want to grade, you can use any
mouse button to select an operation - display, edit, or keep.  To read,
annotate, and return papers you should select EDIT.  Selecting this
button will put copies of the assignments into separate butters in the
main grade window.  (For more information on ez buffers, see the help
file on ez-buffers.)  You will do all your editing in the main grade
window.
  Updating the List of Papers

To update the status of the list of papers in the grading window, select
the menu card option Update List.  This will insert new assignments
which have been turned in and delete assignments taken by other graders.
 

  Inserting Annotations

grade allows you to insert annotations in the form of notes which can be
opened to display text, or closed to an icon.  To insert a note:

7 edit the paper in the main grade window
7 place the ez insert cursor (the little ^) at the spot where you want
the note to appear
7 select the menu option Insert Note on the Page menu card

A small window will pop up at that location into which you can type your
annotation.  (See Figure 3)  After typing your text, you can close the
note by clicking the left mouse button in the top border of the note
window, or by selecting the menu option Close Notes which will close all
notes in the paper.  the annotation will change to its "icon" form, two
overlapped pages.  Selecting the menu option Open Notes will open them
all.

[An Andrew ToolKit view (a raster image) was included here, but could
not be displayed.]Figure 3: Grade Annotation Window

  Returning Graded Papers

Once you are satisfied with your annotations, you can return the paper
to the student by clicking on the Return button at the top of the
window.  Return returns the contents of the current edit buffer, that
is, the file you have been editing.  When you click on the Return
button, you will be prompted for the username of the recipient student
and the assignment number.  grade will display the message

    Paper has been returned

in the bottom message line area when the paper has been successfully
returned.  After the paper has been returned, you should delete the copy
grade has placed into your current directory.  The name of this file is
the one displayed at the top of the main edit window.  You should also
delete the buffer containing the file.  For information on deleting
buffers, see the ez help file ez-buffers.


  Extending a Grading Session

If you cannot finish all your annotations in one session, you can save
the changes you have made so far by typing C-x C-s in the buffer.  This
will save a copy of the file in the current directory with the name
indicated at the top of the buffer window.  You can later restart grade
on this assignment by using the command 

    grade filename

where filename is the name of the saved file.  You must have the
assignment in the current buffer in order to return it.  (You can learn
more about managing file and buffers in the Essential EZ On Athena
document.)

  Customizing Grade

If you are an experience ez user, you may be interested in customizing
grade.  grade has many options which allow you to customize your
environment as well as more options for editing assignments.  For more
information on setting preferences, see the Andrew help files
preferences and grade.  


  Handouts

To access course handouts, first make sure that you start grade from a
directory in which you can save files.  After you select the Handouts
button, a new window entitled "Handouts" will be created 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 4: Handout Window

On the side of the window are five buttons: SUBMIT, DISPLAY, 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
  ------------------------------------------------------------
  SUBMIT    This allows you to pass out a new course handout.  
            Only certain people (TAs) can do this.

  DISPLAY   Display a text (handout) file in a big font in the
            main grade window.

  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 pass out new handouts, select the SUBMIT button.  grade will ask what
you wish to submit, a currently existing file or the contents of your
current edit window.  If you choose to submit a file as the handout, you
will immediately be prompted for the name of the file.  grade will then
try to submit the paper.  Once a paper has been submitted, you can use
the Update List function to see it in the 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 students, select the Exchange button at the top
of the grade window. A new window entitled "Exchange" will appear, with
the course number shown after the title. (See Figure 5) 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 5: 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.
grade will then try to submit the paper. Once a paper has been
submitted, you can  to see it in the list by using the Update List
function 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 grade. To make this window
disappear, select the Quit option on the first menu card.
   Using the Command Line Programs

  Introduction

The command line programs, collect, return, turnin, uncollect and
fxpurge allow you to retrieve, return, submit, and clean up assignments,
handouts, and exchanges without opening multiple windows. collect will
create a separate subdirectory in the current working directory for each
student (if a subdirectory does not already exist) and put his/her
turned in papers in that directory.  return returns annotated
assignments to the student,  while uncollect returns assignments you did
not intend to take. The turnin command, used by students to turn in
assignments, may be used by graders to submit handouts.  fxpurge allows
you to clean up assignments on the NEOS server which have been returned
and picked up by the student.

  The collect command

The format of the collect command is as follows:

    collect [options] [+n] [-n] [assignment] [student...]

All the command line options are optional, but if you do not specify the
course with the -course option, you must have the COURSE environment
variable set.  If you do not set the course, you will get the following
error message when attempting to collect papers:

    collect: No course specified

If you mistype the course, you will get an error message similar to the
following:

    collect: Warning:  Course not found at OSAGE.MIT.EDU
    collect:  No course initialized while retrieving list

collect has many command line options which control its operation.  Like
grade, collect allows you to specify the course on the command line with
the -course (abbreviated -c) option and recognizes the environment
variable COURSE.  Another important option is -list (-l) to list
available files without retrieving them.  For a complete description of
the options to collect, see the man page by typing man collect.

  Listing Available Papers

A particularly useful set of options to the collect command let you list
available assignments to ensure that you retrieve only those papers you
wish to grade.  For example, to list all assignments for the (imaginary)
course 52.001, do the following:

    athena% collect -l -c 52.001
    Dorothy L. Bowe (dot):
          406 Tue Aug 28 11:35   dot/passwd
    Anne R LaVin (lavin):
           70  Tue Aug 28 11:36  lavin/motd
    Paul Boutin (paul)

To list only those assignments turned in by the user dot, specify the
username on the command line:

    athena% collect -course 52.001 -list dot
     Dorothy L Bowe (dot):
          406  Tue Aug 28 11:35  dot/passwd
    Dorothy L Bowe (dot):
          520  Wed Aug 29 9:02   dot/prog.c

You can list only those papers turned in for a particular assignment by
specifying the assignment number on the command line:

    athena% collect -course 52.001 -list 1
    Dorothy L Bowe (dot):
          406  Tue Aug 28 11:35  dot/passwd
    Anne R LaVin (lavin):
           70  Tue Aug 28 11:36  lavin/motd
    4 kbytes total

Note that if the student did not specify an assignment number, it will
default to assignment number 1.

These two options may be combined to list only those assignments turned
in by a particular student with a particular assignment number, and you
can specify more than one student's username:

    athena% collect -list dot lavin
    Dorothy L Bowe (dot):
          406  Tue Aug 28 11:35  dot/passwd
    2 kbytes total
    Anne R LaVin (lavin):
           70  Tue Aug 28 11:36  lavin/motd
    2 kbytes total

  Retrieving Papers

To actually retrieve papers for grading, simply omit the -list option:

    athena% collect 1 dot
    Dorothy L Bowe (dot):
          406  Tue Aug 28 11:35  dot/passwd
    2 kbytes total


    athena% ls dot
    passwd

Here, collect retrieved the assignment called 'passwd' that was
assignment 1 handed in by the user dot.  It created a subdirectory
called 'dot' and placed the file into it.  If there already existed a
subdirectory dot, collect would place any new assignments into the same
directory.

    athena% collect 2 dot
    Dorothy L Bowe (dot):
    Using existing directory "dot".
           70  Tue Aug 28 12:02  dot/motd
    2 kbytes total

    athena% ls dot
    passwd  motd

Once you have collect the assignments you will have to edit them with a
regular editor like Emacs (or do whatever you need to do; for example,
print them out).

The command line options +n and -n may be used to specify a range for
dates of papers you wish to collect.  For example, to collect only
papers that are 10 or more days old:

    athena% collect -list -course 52.001
    Bruce R Lewis (brlewis):
        1 brlewis          92  Thu Nov  8 16:24  brlewis/ps2motd
    Dorothy Bowe (dot):
        1 dot             493  Wed Dec  5 13:42  dot/passwd
    4 kbytes total
    athena% date
    Wed Dec  5 13:43:08 EST 1990
    athena% collect +10 -course 52.001
    Bruce R Lewis (brlewis):
        1 brlewis          92  Thu Nov  8 16:24  brlewis/ps2motd
    2 kbytes total

If you wanted to collect papers 10 days or less old, you would use the
-10 option.
  Returning Graded Assignments

The return command returns graded papers to students.  The format is as
follows:

    return [options] [+n] [-n] [assignment] [student...]

The first argument that starts with a digit is assumed to be an
assignment number.  If you do not specify an assignment number, all
assignments will be returned.  Any other argument that does not start
with a hyphen is a username;  specifying no username will result in all
students' files being returned.  The +n and -n options operate as in the
collect command.  (See earlier for more details.)

As with the collect command, various combinations can be used that allow
you to return specific assignments.

To return an assignment you must be in the directory containing the file
(in this example, it would be the directory 'dot') or specify the full
pathname on the command line.

For example, to return the file passwd, assignment 1, to the user dot:

    athena% return 1 dot dot/passwd
    Returned passwd to dot on OSAGE.MIT.EDU.

or

    athena% cd dot
    athena% return 1 dot passwd
    Returned passwd to dot on OSAGE.MIT.EDU

  Return Error Messages

The NEOS server keeps track of every assignment you have ever collected
until you purge them, and checks this list every time you return
assignments.  If you have unreturned assignments you may get warning
messages from the server when you try to return any other files.  These
warnings do not mean that anything is broken, but simply remind you to
return the assignments or purge them from the server (see section later
for details on purging assignments).

    athena% return -l -c demo
      3 dot             109  Tue Sep 18 09:41  dot/Scratch
        Couldn't return dot/Scratch (No such file or directory)
        3 nschmidt         70  Tue Sep 18 15:28  dot/motd
        Couldn't return dot/motd (No such file or directory)
        4 lavin            65  Sun Oct 14 11:42  educom4/motd
        Couldn't return educom4/motd (No such file or directory)
        3 nschmidt        831  Wed Oct 10 15:43 nschmidt/turnin_demo_1.ez
        Couldn't return nschmidt/turnin_demo_1.ez (No such file or directory)
    athena% fxpurge -t -c demo
    Dorothy Bowe (dot):
        3 dot             109  Tue Sep 18 10:11  Scratch
        3 nschmidt         70  Mon Oct  1 15:39  motd
    Edu Com (educom4):
        4 lavin            65  Mon Nov 19 14:12  motd
    Naomi B Schmidt (nschmidt):
        3 nschmidt        831  Wed Oct 10 15:44  turnin_demo_1.ez
    athena% return -l -c demo
    No papers to return.

  Submitting Handouts with turnin

The command turnin allows you to submit handouts which may be picked up
by students using the command pickup. First, create the handout using
your favorite editor. (On Athena, the default is Emacs.) You may used
ez, Athena's WYSIWYG editor, but be sure that the students know this so
that they may print the handout correctly. Once you have created the
handout, you are ready to submit it.

The syntax of the turnin command for handouts is:

    turnin -c course-name -h class-meeting [file]

where course-name  is the NEOS course name assigned to you by the
faculty liaisons, class-meeting is the number corresponding to the class
meeting for this handout, and file is the name of the file you created
above.

For example, to submit the file course_information to the course 16.226
for class meeting number 3, you would type the following:

    athena% turnin -c 16.226 -h 5 course_information

You would then see the following message from the NEOS server:

    Turned in course_information to 16.226 on EOS.MIT.EDU.

  Returning assignments taken by mistake - uncollect

If you take papers by accident that you do not want to grade, you can
return them with the uncollect command. The format of the uncollect
command is:

    uncollect [options] [+n] [-n] [assignment] [student...]

uncollect does not remove the local files which collect placed in the
working directory but merely corrects the state on the file exchange
server so that other graders can take the papers for grading. To remove
the local copies of the files, use rm or delete.

 For example, to uncollect assignment 5 of the user lavin:

    athena% uncollect 5 lavin

uncollect recognizes the -course command line option and the COURSE
environment variable. For more information on other command line
options, see the manual page by typing man uncollect.

  Cleaning Up Files - fxpurge

Papers which have been turned in, graded, and returned will remain on
the server until explicitly removed with the fxpurge command. The format
of this is command is:

    fxpurge [options] [ +n ] [ -n ] [ assignment ] [ student...  ]


For example, the following command removes all files more than 10 days old:

    athena%  fxpurge +10 -c demo

   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.
