This is a document on how to read and modify a program (Sil) that I wrote at the Xerox PARC Computer Science Lab (hereafter known as CSL) as a programming project for Stanford University. I want to set a few ground rules for the style and organization of, as well as the assumptions behind this document.

I am going to avoid linguistic gymnastics by writing this document in the first person: while this leads to a less formal style than the standard professional third person, I think it will increase the clarity of my presentation.

I am going to assume that the reader of this document has some familiarity with the CSL computers [1], [4], languages [2], and environments, but not that he is a member of CSL. I am also going to assume that the reader is familiar with Sil, either by reading the Sil user manual [3], or by having used Sil (either Alto or Cedar Sil would provide the requisite familiarity). Because of the breadth of experience of my target audience some of the sections of this document may seem unnecessary to some readers. In particular, the following section is mostly history, and may be safely skipped over by the hard-core Sil maintainer.

Sil (Simple Illustrator) was originally written for the Alto environment, and became quite a popular program in the Xerox community. However, as the years passed, CSL developed Cedar - an experimental programming environment that runs on machines much more powerful than an Alto, and uses a language (Cedar Mesa) much more high level than BCPL (the "native" language of the Alto, and the original implementation language of Sil). As of the summer of 1983 almost all CSL members were near full-time clients of the Cedar world. Unfortunately, there are a few beloved programs that did not yet have cognates in the Cedar world: many lab members were forced to forgo the pleasures of Cedar for the concrete design tools available in the Alto world.

While a Cedar version of Sil has been desired for some time, there are several reasons beyond simple implementation language incompatibility that made Cedar Sil more than a problem of simple transliteration.

When Sil runs in the Alto world it can assume that it "owns" the world: access to and manipulation of the screen bitmap, the cursor representation, the main storage, and even the disk is entirely under Sil control. On the other hand, Sil did not receive much help from the Alto operating system in the areas of graphical manipulation (bit-blt or raster-op, clipping, scaling and translation) or storage allocation. There were no problems associated with copying a Sil object from one window to another, as Sil could only display one window, and manipulate one set of data, at a time.

A Cedar application must start from very different assumptions. In Cedar, an application must run in a general window package. Cedar applications must share address space, user attention, and CPU power, and the amount of any one of these available to the application may change at any time. Users will expect that an application can be used to view multiple files in multiple windows; given their experience with existing applications, they will even expect to be able to copy or move application entities from one window to another. On the more pleasant side, Cedar applications receive the support of sophisticated graphics packages [5], and the Cedar garbage collector and large virtual address space leave the applications programmer unhindered by questions of storage allocation.

What Cedar Sil must have in common with Alto Sil is file format compatibility (Alto Sil files must be readable in Cedar Sil, and, at least until the other logic design programs are transported to Cedar, it must be possible to ship Cedar Sil files back to the Alto world for post processing). Because Sil has so many dedicated clients, the rudiments of the user interface must be the same in Cedar Sil as in Alto Sil (there are Sil users that claim that Sil has been wired into their spinal columns). Of course, this stipulation does not give any guidance as to the correct behavior of Sil's user interface in the presence of cross-window object manipulation.

After learning the rudiments of the Cedar environment, using Sil, and talking with Sil's original designer (Chuck Thacker) and my CSL summer host (Mark Brown), I decided that the organization and assumptions of the Sil BCPL code were so different than those required by my Sil, that I would not even read the BCPL code. I think that this decision has been the right one: I was not transliterating an existing program (a program that had been tuned for optimal Alto efficiency) - I was taking a set of specifications and designing a program to meet these specifications.

A module is the basic unit of compilation in Cedar. There are two types of modules in Cedar: definitions modules and implementation modules. Both kinds of modules are loaded and interconnected to provide a complete system. While a full description of definitions and implementations modules is available in the Mesa Language Manual [2], I will give an abbreviated explanation for the sake of experience.

Definitions modules provide common definitions that can be referenced by other modules being compiled. It is common to think of a definitions module as an interface, but in practice it may only be part of an interface. Implementation modules contain actual data and executable code. At compile time, an implementation module containing calls on procedures defined by some interface must import the definitions module that specifies that interface This allows for complete compile time type checking, but, it does not link the procedure referenced to actual procedures in other modules - this binding occurs when the program is linked (bound is another term for it) with other modules.

There are four sets of modules in Sil. The four areas that they represent are: data file representation, user input, display, and top level control. In general, a module with the name fooImpl.mesa will be the implementation module corresponding to foo.mesa - a definitions module.

At the top of each module is its name and a quick description of its function. Next will be a Directory statement and a Program statement followed by constant, type, variable and procedure definitions. While I am assuming that the reader is at least passing familiar with most of this material, I will quickly cover some highlights while emphasizing my personal quirks and style.

In this section I am going to follow a user action through my modules in a manner which you might use if you were trying to figure out what Sil does, or how to add a new behavior. I am going to follow a CONTROL-c. While this walk through may seem simplistic, it is important to realize how many things you can ignore when you discovering program behavior in response to a special case. This section is meant to be read with the code sitting directing in front of you.