                        Xspread Programmer's Reference

    This Xspread Programmer's Reference is divided into three parts:
        1.  Implementation Theory
        2.  Relevant Files
        3.  Existing Bugs and Needed Improvements


                            Implementation Theory

    Xspread is an improved version of a Unix-based spreadsheet program called 
sc, for "spreadsheet calculator".  Sc was originally developed in 1982.  It 
was based on the standard Unix text terminal metaphor.  Keystroke entry and 
screen drawing were done through a Unix support package called "curses".

    Improvements to sc, mostly through course work for Computer Science 536 
(Introduction to Software Engineering), led to xspread.  Prior to our work, 
the biggest improvement was the addition of X Windows based graphs.  Our team 
completely converted the input and output to X Windows and repaired the 
graphing routines.

    Xspread is based on maintaining tables to hold the spreadsheet data.


                                Relevant Files

   There are a lot of relevant files in xspread.  This section will list the 
major files of importance and what each of them does.

    Document Files.  There are several documents for xspread.  Here is a 
list of the different documents, their descriptions, and their file names.

Document                            Description                             _
Xspread On-Line Manual          The on-line help document that you can get
                                using the Unix man command.
                                File Name:  xspread.1

Xspread Reference Manual        The detailed reference manual to xspread which
                                explains all of its commands.
                                File Name for LaTeX Source:  xspread.tex
                                File Name for Printable:  xspread.dvi

Xspread Programmer's Reference  This document which explains the implemen
                                tation theory, the documentation, and known
                                bugs and needed improvements.
                                File Name:  xspread_prog.txt


    Source Files.  All of the source code for xspread is in the "C" 
programming language.  
Here is a list of the files and a brief description of each one.

File Name                           Description
cmds.c              Command routines, Row/Column and miscellaneous 
crypt.c             Encryption / decryption facility
gram.c              Grammar for defining commands
graphic_main.c      All functions in the /Graphic command tree
help.c              Help facility
interp.c            Expression interpreter and support
lex.c               Lexical analyzer
psc.c               ASCII to table converter (separate program)
range.c             /Range commands
sc.c                Main program segment for xspread
scXstuff.c          X Windows input and output for worksheet window
xmalloc.c           Memory allocation for X Windows
plot_XY.c           XY graph display
plot_bar.c	    Bar graph display
plot_line.c	    Line grpah display
plot_pie.c	    Pie graph display
plot_stacked.c	    Stack Bar graph display

    Header Files.  The source code files reference many different header 
files.  All of these header files are in the "C" programming language.  
Here is a list of the files and a brief description of each one.

File Name                           Description                             _
experres.h	    Global expresions that contain info for "@" commands
graphic_gvar.h      Global variables for creating graphs
sc.h                Global variables for the whole program
scXstuff.h          Global variables for X Windows support in worksheet window
sc_menu.h	    GLobal variables for menu area
pattern.h	    Pattern used for graphing part of program
plot.h              Global variables for displaying graphs


                    Existing Bugs and Needed Improvements

                                Existing Bugs

    Here is a list of the bugs that we identified that we were unable to 
resolve.

    2.  @EXT() Function Results.  Xspread saves only one value from any call 
to external functions via @ext().  If @ext() is used more than once in a 
spreadsheet and external functions are enabled and then disabled, the last 
returned value pops up in several places.

                             Needed Improvements

    In addition to the bugs, we identified many areas which needed im
provement.  A lot of these recommendations will be a lot of work to implement, 
especially if they are done properly.  However, avoiding the temptation to 
engage in corner cutting will make life a lot easier for people who use this 
spreadsheet and for later programmers who upgrade it.

   Here is the list.  It is in no particular order of importance.

    2.  There is no way of inspecting the values of global parameters without 
changing them.  Xspread needs something like the Lotus 1-2-3 /Worksheet Global 
Default Status command.  The implementation of global settings is awkward.  
Instead of being in one place, the xspread global commands are scattered all 
over.  Xspread needs something like the Lotus 1-2-3 /Worksheet Global command 
tree.

    3.  Right now, there is little function key support.  This makes sense in 
an environment where you cannot be sure if the terminals have function keys 
available.  After porting xspread to X Windows, this no longer makes sense 
since X terminals have full function key support.

    4.  Editing is crude.  The only way to edit a cell's existing contents is 
to backspace over the text and retype it.  Xspread should support complete 
line editing with thoughtful and well documented editing commands.

    6.  Xspread right now does not support natural order recalculation, only 
rowwise and columnwise.  Implementing natural order recalculation would make 
recalculation much more efficient.

    7.  The source code needs to be much more thoroughly documented.  Right 
now, it's difficult to figure out the intent of designers.

    8.  Xspread needs to support more functions, especially in the statistical 
and financial areas.

    9.  There is no indicator of what operating mode you are in (e.g., Ready, 
Edit, Point, Command, etc.) nor is there a status line, which holds such 
information as date, time, amount of virtual memory available, operating mode, 
and similar useful information.

   10.  Currently, the column width is set by terminal settings or by the 
user's environment.  It is bad policy to set any internal parameters in this 
way.  Column width and similar things should be part of the worksheet's global 
parameters.

   11.  There is no support for worksheet macros or else the documentation is 
so sketchy that it is impossible to figure out what the macro capability is.  
Future programmers should provide the macro capability and document it 
thoroughly.

   12.  There are no display formats for numerical information.  Future 
programmers should provide the common spreadsheet display formats, such as 
scientific, general, fixed, percent, comma, and currency.

   13.  The support for printing worksheets is next to nonexistent.  Future 
programmers should provide a capability similar to the Lotus 1-2-3 /Print 
command tree.

   14.  Some commands apparently use an optional repeat count.  This area 
needs to be investigated and documented.  Even better would be to implement a 
more intuitive method for commands that handle a variable number of cells.  
For inspiration, look at how commercial spreadsheets tackle this problem.

   15.  Xspread needs a much simpler and more intuitive way of copying and 
moving ranges of data.

   16.  The help facility needs to be much more detailed and thorough.

   17.  Command Feedback.  Many commands do not give any warning to the user 
(e.g. a message or beep) if they do nothing.  Some commands should give 
confirmation of their action but do not do so.
