How to Submit Programming Assignments

Suppose that you've just finished working on a programming assignment for a computer science class. You now need to submit something to your instructor, so that she can grade the assignment.

If she happened to be with you (say, in the lab), you do the following steps:

• Show her the source code (using the cat command).
• Show her that the program compiles correctly (say, using the g++ or make commands.
• Show her that the program runs correctly.

Since your instructor isn't likely to be around, the next best thing would be to create a computer file containing all the ``evidence'' listed above, which you could then print. In other words, you want to make a recording of the entire computer/user conversation that appeared on the screen when you did all the steps listed above. Such a file is called a transcript, and is generated by the photo program. The main idea is that you launch a photo session, run the commands whose output you want your instructor to see, close the photo session, and then submit the transcript (by giving a printed copy to your instructor or by emailing it to her).

Before going any further, note that you only do this when you are ready to submit something for grading. You should not do this while your are developing the program. Moreover, photo does not deal well with graphics, and so you should never run any commands (such as emacs) that produce graphics while you're within a photo session.

So here's what you do, in more detail.

1. Launch a photo session, by typing ``photo'' in a terminal window. If you get a message saying

   A photo session is already in progress.  Use "exit" to stop it.
   

   then you are most likely already in the middle of a photo session. You should type ``exit'', which will terminate same.
2. You should now enter the cat commands that are needed to display the computer files that you wrote. Most of the time, these will be program files; if your instructor also asks you to provide data, then you might need to cat the data file(s). Your instructor will provide you with the details.²
3. You should now recompile and link program, which will show that it contains no syntax errors or warnings. If your instructor provides you with a Makefile (or tells you to make one on your own), this will probably be a matter of simply issuing the command ``make clean'', followed by the command ``make''. If there is no Makefile involved, then this will be one or more instances of a command such as g++ or gcc. Once again, your instructor will provide the details.
4. You should now run the program. If you're supposed to run the program with several data sets, you'll be running it more than once.
5. Exit the photo process, by typing the command ``exit''.

You now have a file named typescript, which contains a transcript of your photo session. Unfortunately, the typescript file contains a lot of strange control characters, which you will want to supress. This task is handled by the photo-clean program, which takes one command line parameter (the name of the file that needs the cleanup). The output of photo-clean (i.e., the contents of the cleaned-up version of your transcript file) goes to standard output, which means that you'll probably want to redirect the output to a new file. If your login shell is tcsh (this is almost everybody), then issue the command

photo-clean typescript >! proj4.out

(this assumes that you're doing Project 4 and that you want the name of the clean version of typescript to reflect same). If you are one of the few people whose login shell is bash, then the command should be

photo-clean typescript >| proj4.out

The greater-than sign means ``output direction''; the extra character (either an exclamation mark or a vertical bar) means that if a file named proj4.out exists, it should be overwritten. Of course if you really wanted the file proj4.out to stick around, you should use a different file name for the redirection.

The next step is simple, but often omitted: look at the cleaned-up transcript. Make sure that its contents are what you expect. (The most common errors are for the cleaned-up transcript to be empty, or to be the transcript of a previous session.)

Finally, you should submit the clean typescript. You can do one of two things:

• You can print the file, and then give it to your instructor. If you use the enscript command, you can get ``2-up'' printing, which saves paper:

  enscript -2r proj4.out
  

• You can submit the file via email. Assuming that you're submitting the Project 4 typescript proj4.out, that your own email address is harry@bovik.com, and that your instructor's email address is vader@dsm.fordham.edu, the shell command

  mail -s "Project 4" -r harry@bovik.com vader@dsm.fordham.edu < proj4.out
  

  will do the trick. (The -r flag makes it easier for your instructor to send an acknowledgement message.) If this mail command produces no output, then everything is probably okay. However, if it produces a warning message, then you should pay attention to what the what the warning is trying to tell you. The most common case is

  Null message body; hope that's ok
  

  This means that you sent your instructor an empty file. You should investigate why the file is empty, fix the problem, and try again.