N M

E-L Users' ManualI

DTICS ELECTE

MAR 0 7 1994 DJudy G. Townley E

I

* • 94-06845

I February 17, 1994

I

Software Options, Inc.22 Hilliard Street

Cambridge, Mass. 02138

This work was supported in part with funds provided by the Defense Advanced ResearchProjects Agency under contract N00014-85 C-0710 with the Office of Naval Research.

*4 "... .-

MATERIAL INSPECTION AND RECEIVING REPORT

**4" ~. '4~t 'eO no *# U.fA9 t' AmIi,4 of .01ýe* %P,4 ' lego'Cft bý14t5

ftW-MP X e vW*tt 1 (OtS1lO

PM~PLA5 I, 4- RITUMf VOIJR COMUKT110 FORM TO EITHIR Of THESE ADONESSIS. -7 r&%(Fw"1. MOC IT wasT (CONRACT 85 -0710 I VK %9, ACC(P'S Y. iks O

I swgrulM MY O I DATI S4IW*E 4 & S VVOjl4T TEILMS

soi-001 23 F-eb '94 TC1 N/A N/A ____

IPWMt Co~ffTOAC711 cm~ 2V50 OA(1-6i- 7(ft7(72

Software Options, Inc. DCMNAO, Boston22 Hilliard Street 495 Summ~er StreetCambridge, MA 02138 Boston, MA 02210IS 5fI 9WO I KM Of gom tA. 0t~ ) CM o PAYM YI(FAL, It S MAQ( 0Vcot1Yc o i

DYAS-Columbus Center ~ Sli

ATTN: Bunker !1ill Division

PO Box 182077

________________________________Columbus, Ohio 43218-2077

see Enviosure Number 1 of contract

it, STOCK/PART NO. O(SCT4,PTICN 17B

NO.M ";bzC;0.~so~rwn L; N UNIT PRpCk AMC\.NT

A00021, Final Report in accordance withA0002 and Exhibit A

15 copies enclosedDistribution made in accordancewith Enclosure Number 1 of contract 1 11O NSP NSP

CIrPC QUAI.'iT' ASS,.3ANCF . RECEiVER S USEA. ORIGIN 8. DESTINATION 0aa'~sPown in r~w1 1 7 ýe e ot

P CQA [~ACCEPTANCE 0l 1swwd rIeMS CQA Ej ACCEPTANCE 1,1$ ted Cs1 has beent in apparent~ good condition except as -iotod

has beens made by me or Ynder my superision' me' je t~y mv U'Jtvf w~v myn~tt od theyand th" conform to wftrect.#ueeptas ngted co, Jor- tO c~fitr3C, *wpt as noted heroin Or 0on - tt D -A-- I-,-t=UCh-O AUTH r.~VA

hV91s or on %uppotimg doitumtpritt s-ipportng dOcY3Yf13. C$6AIUP ~ t

'03FE NAME

YrPIEo FLAWi TTPtý *AA41 if qudrittry r~erevr4 by the Goveromheot is thesow %t*.AJ AVO MTir sirivJ as11ort)Shf, f~fd(rt by / )

pr~lrK o ;? 4renft, ervrer dcTjdI1 qLudmiry rv.__________ ________ ebt~d biIiw quontrt shipper and e.-Kirrd.

41 MYUNTh*g Via vmr

DO Form 360, Oic 91 PreVioW1 #00or1fks off 06,o10r.

UUsers' MalnualI

Contents

I Introduction 11.1 Artifacts ............................................... 11.2 Updating ......... ..................................... 21.3 Plexes ......... ....................................... 3

2 Getting Started 12.1 Drafts ......... ....................................... 12.2 Simple Commands ........ ................................ .

2.3 Notices ................................................ 32.4 Subsequent Editing ........................................ 4

3 More About IATEX Artifacts 13.1 References to Other Artifacts ................................ 13.2 Creating an Index or Bibliography ....... ........................ 25 3.3 Dividing a Document into Parts.......................... 33.4 Customizing Errors ........................................ ,53.5 postscript Artifacts ....... ............................... 6

4 More About Artifacts and Drafts 14.1 As Arguments to Commands ................................... I

S4.2 Further Dealings with Artifacts........................ . .4.3 Further Dealings with Drafts ................................... 44.4 Further Dealings with Problems ............................... 54.5 Comparing .............................................. 64.6 Searching ........ ..................................... 74.7 Highlighting ......... .................................... 84.8 Annotating ......... .................................... S

5 Plexes 15.1 Introduction ......... .................................... 15.2 The artifacts Plex ........ ............................... 25.3 The drafts Plex ........................................ 45.4 Scheduling .............................................. 55.5 The notices Plex ........................................ 75.6 The users Plex ..........................................

5.7 The hosts Plex ......................................... 7

6 Troubleshooting 16.1 Servers .......... ....................................... 16.2 Missing Drafts ........................................... 2

I A Customizing LATEX Output 1Iiii

I

Users' ManualIB Automatic Deletion

l C Installation IC .1 P rerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IC.2 Installing E-L ......... ................................... 2C.3 Artifacts System Administration ............................. 7C.4 Obtaining Assistance ........ ............................... 8

I Index Accesion For 1NTIS CRA&IDTIC TABUrannounced 0

B y -----. .... . . .

Dis;t:ib tioni

5 Availability Codes

Avail and I orDist Special

IIIIIIII

ivI

UUsers' ManualI

1 Introduction

I E-L is a software development environment that reflects a fresh look at how the design ofa programming system and the design of the languages it supports can reinforce each otherin ways that increase software productivity. The benefits of this coordinated environment-and-language designi are reflected most directly in E-L's tools for manipulating programs.In E-L, one sets up a structure that indicates a desired result. E-L uses a strategy called3 opportunistic scheduling to minimize manual tool invocation and to mediate the objectivesof maximizing the use of tools and maximizing responsiveness. Most tool invocations areautomatic, typically in response to editing or to actions taken by other tools, which arethemselves automatically invoked. Because tools are "scheduled", not run immediately, tiesystem can optimize the use of resources. For example, the system may locate idle machineson the network and use them for some invocations. The system will usually not run morethan one scheduled tool on any one machine at a time (to minimize swapping and thrashing).

E-L also supports multiple distributed users in an unusual way. Rather than mereiv trivingto keep different users from harming one another, the goal is to encourage close cooperation.For example, in addition to supporting branching and merging lines of development, E-L alsoaids users in concurrently editing different but closely related pieces of the same programor document and coordinating the construction of the next version. In particular. a userexamining a part of the E-L repository will see changes to that part as they are made. evetiif by other users or by background tool invocations, perhaps on other machines.

1.1 Artifacts

In most environments one deals with files; in E-L, one deals with arlifact,. which differfrom files in several respects. Perhaps the most significant is that while one can "changethe contents" of a file, the contents of an established artifact are immutable. In E-L, whenone "edits an artifact", what actually happens is that one creates a new artifact, startingfrom the existing artifact. The image is that of producing a new edition of a book, ratherthan modifying what is written on a piece of paper. The latter is the model provided byfile systems. The former takes a while to internalize but provides a better basis for trackingthe evolution of a constantly changing system. Because an artifact is immutable, it is also aversion, that is, it is unchanging data created at a particular time. A user of E-L need notresort to an external system like RCS to track versions-it happens automatically as part ofusing the system.

Another difference between artifacts and files is that an artifact has a type. Typing offiles is done by some operating systems (e.g., text vs binary), but typing of artifacts in E-Lplays a central role in integrating tools. The set of types grows as new tools are added tothe environment. In classical file systems, naming conventions are often used to achieve

something of the effect of types, but there is generally no enforced correspondence bet ween anami,.g convention and the contents of a file. Types of artifacts ale used in a more classicalprogramming way: they govern the structure of the artifact and the operations that can be

'The name E-L is intended to suggest the simultaneous concern with environment and language.

1-1i

IUsers' Manual

applied to it.Artifacts can reference other artifacts. A reference is more than just a relation between

artifacts-a reference emanates from a particular place in the contents of the referencingartifact. For example, an artifact that describes a document might have references to artifactsthat describe the chapters, one of which might, in turn, have a reference to an artifact thatprovides a drawing to be inserted in the document. Unlike file systems, E-L understands thesereferences. For example, you cannot delete an artifact that has references to it. Combinedwith the immutability, the guarantee of "no dangling references" provides a conceptuallysimple basis for configuration management. In E-L, a configuration is defined to be thetransitive closure of an artifact under the references relation. It is the smallest structurecontaining a given artifact, called the "root" of the configuration, and all artifacts referencedby an artifact in the structure. The rule about not deleting an artifact having references toit means that the integrity of configurations is guaranteed.

The integration of tools involves both the notion of a reference and that of a derivati?'c.A derivative of an artifact is an object that can be computed from the configuration rootedat that artifact. A derivative does not depend upon any other information than what is inthe configuration, such as the time of day or the contents of a setup file. Furthermore, aderivative is associated with the artifact at which the configuration is rooted. Thus, the user

Sdoes not stumble across an executable and wonder where it came from. Instead. the userpoints to the artifact that specifies the executable-that is, the one with the executable as"a derivative-and says "execute". E-L then finds the derivative and executes that program.

A deriver-that is, a tool that computes a derivative--does not care about the type of"a referenced artifact, only about the kinds of its derivatives. This is the basis for an openarchitecture. One can write a new deriver, whose input is a new type of artifact and whoseoutput is an existing kind of derivative. The new tool is automatically integrated: artifactsthat reference artifacts of the new type will automatically trigger the running of the new3 tool when their their tools need a derivative of the existing kind.

1.2 Updating

I When several people are working together on a single program, making changes to it re(quirescoordination. Some of the difficulties are unavoidable-everyone wants the system theyare using to incorporate all the latest changes, but no one wants the latest bugs that areintroduced in the process of making those changes. E-L is not magic, but it does providesome help in allowing several people to work on a program at once, in a reasonably controlledSway. You have enough flexibility to step on each other's toes, and enough information tofind out who did it.

In E-L, when one edits an artifact, what actually happens is that one creates a new draft--starting from the existing artifact. The draft comes into existence when editing begins, andit is committed, and turns into a new artifact, when editing ends.

There is the question of whether an artifact is up-to-date. This attribute of an artifactcannot be part of its contents, because it can change long after an artifact is committed.Artifacts become out-of-date when they are superseded by other artifacts; committing an3 edit is a common way that this happens. With the notion of "up-to-date", we can correct a

1-2

IUsers' ManualI

white lie of the previous section:

5 o Editing an artifact has the effect of editing all artifacts that reference the edited artifactand that are also up-to-date.

5 A visual image is given in the following picture, in which A, B, C and D are the artifacts.and x marks the change.

5 old new

A A'

AI

After the change, C is out-of-date (and its successor is C') because it was edited directly.and A is out-of-date (and its successor is A') because it references C. Note that B and Ddo not have successors but are referenced by two artifacts: B by A and .4'. D by C andC'. The rule that editing affects only up-to-date referencers means that a new version of BU will bring forth a new version of A', but not of A. Additional details about the effects ofcommitting a draft are in sections 3.1 and 5.3.

One might worry that propagating the effects of editing would consume tremendousI amounts of storage, but this is not so. Clever representation reduces the storage required for

both A and A' in the above example to about what it is for one of them alone. Treating themas two artifacts simplifies the bookkeeping for version control and provides a simple mentalmodel to account for the effects of an edit. It also provides a basis for building incrementaltools: the derivative associated with a predecessor can be used to compute the derivativeof its successor with confidence; one always knows what went into producing the derivative.U(Much more can be said about incremental tools than is appropriate in a Users' Manual.)

3 1.3 Plexes

Up to this point, we have been concentrating on artifacts, whose contents are static. We usethe term plex to describe a portion of the E-L repository whose contents are dynamic. The

notion generalizes that of "relation" as it. is used in database terminology. A relation is aplex whose state at any one time can be described by a set of tuples, all of the same length.

I Plexes generalize this by allowing the state to take other forms, for example a list or a tree.(It is understood that relations are logically sufficient; the reason for plexes is that, sets oftuples may not be convenient for some purposes.)

I A user views a plex with an editor and, to the extent allowed by the plex, uses an editorto change it. Because plexes may be large, viewing is controlled by a filler to limit theamount of the plex that the user sees on the screen. While a filter controls which artifact"

II

IUsers' ManualI

a user sees, a format controls how those artifacts are presented on the screen. The detailsof what a user sees when viewing a plex through a particular filter, arranged according toa particular format, are of course dependent upon that plex, as are the specifics of how tospecify a filter or a format for the plex. However, the notions of filter and format apply5 when viewing any plex. The commands for specifying filters and formats are described insection 5.

Several important plexes are built into the system. One of these is the artifacts plex.which not only keeps track of all the artifacts in the system, but also various attributesattached to them; these include type, time of creation, whether the artifact is up-to-date.name, and the person who created it. The artifacts plex is the means by which a personlocates a particular artifact; for example, users generally organize their data so that there isno more than one element in the set of artifacts that is up-to-date and has a particular nameand type, or name and creator. The interface for the E-L system makes locating artifacts illthis way no more difficult than specifying a file name. It is also common to use the viewingmachinery to locate artifacts in other ways. For example, a user may wish to see all artifactswith a given type that are up-to-date and created before a given time or all artifacts with agiven name, regardless of their type or whether they are up-to-date. Such subsets of artifact.smay be viewed by specifying the appropriate filter. Similarly. a format may indicate sort ingfirst by name or by time of creation or may say to include or omit the display of certainattributes.

In the normal daily life of a programmer, artifacts may be created by' the score: a largeSprogram may have thousands of up-to-date artifacts. In contrast, the creation of a new plex

is a relatively rare event; doing so has more of the flavor of extending the environment thandeveloping a program.

iIIIIII

1--1I

Users' NManualI2 Getting Started

I The current user interface to E-L, which is not the one of our dreams, is based on EPOCH,an extension of GNU EMACS that runs exclusively under the X window system. So beforestarting EPOCH E-L, you should be at an X terminal or a workstation running X, talking to a

shell that has its DISPLAY environment variable set appropriately.1 Then the shell commande-J starts an EPOCH that has been augmented with commands for using E-L.3 This manual assumes familiarity with EPOCH, which provides highlighting and multiplefonts, versatile mouse commands, and the use of multiple X windows (called screens inEPOCH) in a single EMACS session. EMACs has complete on-line documentation for EMACS1 and EPOCH, including a tutorial under the command M-x help-with-tutorial.2 All keybindings for E-L commands begin with C-z.3 Each command also has a name, of course,and can be invoked from EPOCH by first typing M-x and then the command. You may useE-L to edit files in the usual way, but this will not be your normal activity. To exit, typeC-x C-c.

Because E-L makes it especially easy to program by writing a document (in which tilecode is sprinkled), we will introduce E-L by describing how to prepare a document, usingIATEX. We assume some knowledge of LATEX and defer exposing the full generality of mostfeatures until later chapters. By the end of this chapter you will be able to create and editsimple iýTEX documents.

3 2.1 Drafts

When you are editing in E-L, you are working on a draft. For the present, you may think3 of a draft as corresponding to an EMAcs buffer. Unlike ordinary uses of EMACS on files.a draft is not connected to some file whose name you know, but exists unto itself. A draftalso has a type. When preparing LATEX documents, the first type of interest is latex-root.

corresponding to the "root" file for a document.There are several ways to begin working on a new draft. One of these initializes the draft

to be the default for a type:

9 create-draft type name C-z C-c

'The DISPLAY environment variable is described in the on-line X manual. To check its value, say

echo $DISPLAY

To change it, say, e.g.,

setenv DISPLAY myhost:O.0

'The EMACS notation for commands is the first thing explained in tile tutorial. If you aren't familiar wit hit, press the Escape key, then x, then type help-with-tutorial and press Return. The Meta key mentionedin EMACS documentation usually exists on X terminals, but is rarely labeled as such 'Try keys marked with0, Left, Right, Alt, Compose Character ....

3 Non-E-L EPOCH also uses C-z as a prefix for commands having t~o do with EPocn screens. These ke.bindings are not available in EPOCH E-L, but you can of course bind such commands to other key sequencesin your own initialization file (-/.emacs).

2-1I

Users' 'Manual

IFor example, suppose you wish to prepare the root for a new document. You can use create-draft, supplying "latex-root" as the type argument 4 and, say, "trial" as the name. Afteryou supply the name, the following will appear on your screen:

\documentstyle [12ptl {article}\begin{document}

\end{document}

The cursor will be on the blank line between the \begin{document} and \end~document}commands.I2.2 Simple Commands

3 You edit a latex-root draft in the usual way. To indicate to the system that Yon havefinished editing a draft, you can use the following command:

3 * commit-one-draft draft C-z C-s

The command supplies a reasonable default and asks for confirmation. It uses the draftto make an artifact, which, like a draft, has a type but, unlike a draft, is permanent andunchanging. You will note that, while the buffer remains, it changes to read-only. signifyingits change from a buffer on a draft to a buffer on an artifact.

Once you commit a latex-root draft, you are guaranteed that LATEX will be run onit.' Once the LATEX run completes, you may preview the results on the screen, print theresults, or examine the log that LATEX produces. Each of these commands may be applied3 to a latex-root and, in each of the cases, if you ask for something before it is ready. youwill be told of the difficulty. We complete the description of these commands in section 3.3.

To preview the output, use the first command to invoke a "dvi" previewer and the secondto invoke a full PostScript previewer (if you don't know what the difference is. use the firstcommand):

5 * preview artifact

a ps-preview artifact

I If you want to print the output, use

3 * hardcopy artifact switches

The contents of switches depend upon the particular Unix utility used to print .dvi files.Your system administrator can give you the specifics for your site.

You can examine the log that 1ATEX produces with

4E-L allows completion of type names in the same way that ENIAcs allows completion of command namesA TAB following partial input causes the name to be extended as far as possible. A second TAB at that point

produces a list of acceptable completions.'Unless you commit it with a C-u prefix.

2-2U

Users' Manual

•latex-log artifact

This command sets up a buffer whose contents are the LATEX log pertaining to the artifact.The cursor is positioned at the end of the buffer, making some of tile warnings and errormessages (if there are any) visible right away. You will see that the buffer on the logcontains references to the artifact(s) involved in the run; each reference is prefixed by theword "Insert", "Begin", or "End". The latter pair are used to indicate that processing the

referenced artifact generated the several enclosing lines of output in the log. The buffer-dependent commands

5e follow-link C-z

and

3 . follow-link-reverse C-z M--

allow you to bounce, in this case, from the log to a buffer on a refeCrenced artifact and Lack.

respectively. We do the best we can, given the limitations of LATEX's error reporting. toposition the cursor in the buffer on the artifact near the cause of the warning or error. While

in the artifact buffer, typing two C-xs will bounce the cursor to the opposite eild of theI offending construct.

The following commands, though perhaps less fundamental to the use of LATEX. give Vouaccess to additional information that it produces.

"• latex-aux artifact

3 * dvi-file artifact file

"* ps-file artifact switches file

I The first displays the .aux file, and the latter two allow you to obtain the raw data for dviand PostScript, respectively. The switches are extra arguments passed to dvips. and theoutput is put into the file argument. These latter commands are useful, for example. wheii

you want to transmit the data to someone who doesn't have E-L.

I 2.3 Notices

Errors may arise in computing derivatives and, when they do, they will bc transmitted back3 to you as a notice. Notices appear in a pop-up screen, with each notice containing yourname, an id for the notice (currently a number), and a short description of the reason forthe notice. If, after committing the artifact, you get out of E-L before the notice arrives.3 you will see the pop-up screen when you next start E-L.

Notices can alert you to other events than the discovery of an error. For example. Youmay want to know when a job. like the running of LATEX, is complete whether or not an

error was discovered. The value of the variable job-done-notice controls whether a notice

is sent to you upon job completion.3 To get more details on a notice and to delete a notice, use the following commands:

2-3I

IUsers" MIanialI

e display-notice user id C-z C-n

e delete-notice user id C-z M-n

An undeleted notice is carried over from session to session, so you will eventually want tuuse the second of these commands. A natural response to the arrival of a notice is C-z C-nto display it, followed by a C-z M-n to delete it. The notices buffer is actually a view of thenotices plex, about which you can le,.rn more in section 5. The first command, in the case

I of ITEX artifacts, calls a generic function

* examine-problems artifact

that you can also call directly. It will display a buffer on the log file LATEX created, thushaving the same effect as calling latex-log on the latex-root artifact.

Because we take care to rerun LATEX automatically as many times. but only as manytimes, as necessary to catch forward references (of labels, for example), anything that L\TEXreports as a warning is an unresolvable error. Thus we treat these situations, plus conven-3tional errors (in which LATEX waits for a response from the user), as error situations anldgenerate a notice. You can customize the definition of an error. however, and thereby cus-tomize the situations in which the system generates a notice. We describe these features iWsection 3.4.

3 2.4 Subsequent Editing

Suppose you have examined the output of LATEX, as described above, but you don't likethe results. We have said that you can't change an artifact. This is because it serves as a

version. However, you can create a new artifact, based on the contents of an old one. Forthis you use

I * edit-artifact artifact C-z C-e

A draft that is started by an edit-artifact command may be edited and committed in thesame way as a draft resulting from create-draft.

IIIII

2- I

I

Users" MlanualI3 More About LATEX Artifacts

I As a gentle introduction to E-L, we told you about some of the features for creating LATEXdocuments. What follows here is the next chapter in th;, story.

3.1 References to Other Artifacts

In ordinary 1ATEX, you can embed one file in another with an \input command. In allartifact, you use a reference-where the \input{file} would appear-and omit the \inputcommand. A reference is not an ordinary sequence of characters. Rather, you must insertit, while editing a draft, with one of several commands.

The first of these that you are likely to want is

* * create-draft-and-reference type name C-z M-c

Like create-draft, this sets up a new draft with a given type and name. In addition.it inserts a reference to that draft at the cursor. The type of artifact that most closelycorresponds to a file that you would "input" in a LATEX document is latex-piece. SU)ppOSethat you choose latex-piece as the type and triall as the name. The text that will appearas the reference is [triall latex-piece]. However, this is not ordinary text, as indicatedby the fact that it is highlighted. The characters that appear are just a readable way ofdisplaying what is in reality a reference to another draft. To edit the draft, simply switch3 to the buffer labeled triall latex-piece, using ordinary EMACS commands like C-x b orC-x C-b.

You can also insert a reference to an existing artifact or draft into a draft buffer (at the3 position of the cursor) with the following commands. The first two commands are mostappropriate when you want to identity the artifact or draft to insert by it's name.

3 * insert-artifact-into-draft name

e insert-draft-into-draft name

I The following command uses the cursor position to identify a default argument. That is, ifyour cursor is near the artifact or draft you wish to insert, you can use

* copy-as-kill C-z x

This command copies an artifact or draft reference into the kill-ring, from which you call3 yank it (into the draft buffer, for example) using an ordinary EMACS command like C-y.When you have finished editing the reference, you can use the commit-one-draft coin-

mand to commit it. One aspect of committing that you must be aware of from the startis the following: you may not commit a draft that references other drafts. Continuing thleprevious example, suppose that you first try to commit the latex-root draft named trial.before committing the latex-piece draft named triall. You will see the following messagein the minibuffer:

g This draft references a draft

3- 1U

tUsers' ManualI

You may commit the drafts one by one bottom up (i.e., triall first) or use one of thecommands described in section 4.3 that commit several drafts at once. In all cases, whenyou commit a referenced draft, the reference changes to include a timestamp, indicating thedate and time of committing the draft. (We say more about timestamps in section 5.2).

I Returning to the specifics of LATEX artifacts, the contents of a latex-piece artifact isordinary input to LATEX, except for its references to other artifacts. The semantics of a refer-ence from either a latex-root artifact or a latex-piece artifact to a latex-piece artifactis essentially that of textual inclusion. However, a latex-root or latex-piece artifact canreference other types of artifacts as well. For example, if E-L supports programming ill agiven language, it will support typesetting of program fragments in that language. A refer-ence from a latex-root or latex-piece artifact to an artifact whose type indicates that itholds source text for the language will result in a typeset version of the program fragmentappearing at the point of reference.

The usual rule is that, when a latex-root or latex-piece artifact references an artifact.the manuscript derivative of the reference is inserted. Each artifact type has its own rulefor how manuscript derivatives for artifacts of that type are produced. if at all. Thereis enough flexibility here that no general rule is possible. For example, the manuscriptderivative of a latex-piece artifact is simply the contents of the artifact, with suitableprovisions for obtaining the manuscript derivatives of its references. On the other hand.

a latex-root artifact has no manuscript derivative-what with the \documentstyle and\begin{document} and \end{document} commands, a reference from another document to3 such text would only confuse LATEX. To learn about the manuscript derivative for a specifictype, you have to read about the details for that type.

An exception to the usual rule occurs when a reference to an artifact is immediatel\followed by <caption>. In this case, the caption derivative, rather than the manuscriptderivative, is inserted at the point of reference. Like manuscript derivatives, each typehas its own rule for producing a caption derivative, but, as the name suggests. caption

derivatives are intended to be short. The caption derivative of a latex-piece is seldomused; consequeitly, the default simply indicates that the user did not provide a cal)tion.To specify a non-default caption, start the first line of the artifact with %%Caption:: the

remainder of the line following the : and stripped of leading and trailing whitespace. willbe used for the caption derivative. You can specify a caption derivative for a latex-rootsimilarly, useful when referencing a latex-root.

3.2 Creating an Index or Bibliography

To create a document with an index, you need to do two things: put a \makeindex commandin the preamble before the \begin{documentI command in the latex-root (just as you5 would do in ordinary LATEX) and put a \printindex command where you want the indexto appear (where you would put \input{file. ind} in ordinary LATEX).

You can engage BIHtFX's help in producing a bibliography by using a latex-bib artifact

type. The text you put in a latex-bib artifact is the same that you would put in a . bib file.A latex-root artifact may reference one or more latex-bib artifacts- each should appear

I just before the \begin{document} command-that is, after any \makeindex command or

3-2

IUsers' NlaiualI

references to other latex-piece artifacts-with <b,&bliography> immediately following thcreference. The derivative of a latex-bib artifact is another exception to the rule that refer-ences in latex-root or latex-piece artifacts supply manuscript derivatives. Its derivativeis a bibliography, which is used like a file argument to the \bibdata command. Again.3 where you want the bibliography to appear, use, in this case, a \printbibliography com-mand (in the same way you would use the \bibliography command in ordinary LATEX)-along with a \bibliographystyle command, if desired. In combination with the usual

S\cite command, these commands and the use of latex-bib references will produce cita-tions and a bibliography in the document. E-L does all the delicate, interleaved invocationsof lATEX andBigIffX automatically, something that you won't appreciate if you haven'tI struggled through it.

As a matter of style, one typically puts references in the latex-root to latex-piecescontaining the \printindex or \printbibliography commands. You can examine a logthat describes the results of the \printindex or \printbibliography command.

o makeindex-log artifact

* bibtex-log artifact

These commands work like the latex-log command, setting up a buffer whose contents arethe appropriate log. The cursor is positioned at the end of the buffer, making some of thewarnings and error messages (if there are any) visible right away.

A single command

* latex-summary-file artifact name

3 displays any of the many log and summary files that the various processors of a manuscriptproduce. The first argument must be either a latex-root or latex-piece artifact. and thesecond argument is the name of the summary file that you want to see. (You can see the

list of possible file arguments in the usual way, by asking for completion with a Lt]. aftersupplying the artifact argument.)

I 3.3 Dividing a Document into Parts

In using ordinary LATEX for a large document, the \include and \includeonly command.divide the document into smaller parts on which LATEX can be run. To achieve the sameeffect with artifacts, place a \parts command immediately after the \begin{document}command. Each reference is then treated as a separate part and E-L will rerun LATEX only

on those parts affected by an edit.If you apply one of the commands mentioned in section 2.4 to a latex-root with parts.

Syou will be prompted for the name of a part. You can also supply just the name of the partif it is referenced by only one latex-root. As this suggests, the full story on the commands

is * preview artifact [part]

which assumes it will not encounter any PostScript in the artifacts;

3.3U

IUsers' ManualI

9 ps-preview artifact [part)

I which is for prevewing artifacts that contain PostScript; and

* hardcopy artifact [part] switches

* latex-log artifact [part]n latex-aux artifact [part]

* dvi-file artifact [part] file

e ps-file artifact [part] switches file

The latex-log, latex-aux, dvi-file, ps-file, and the preview commands r'quire a part5 if you have used the \parts command. The hardcopy command will print either a latex-root or a part.' If you supply a latex-root artifact as the argunment to hardcopy. thcsystem asks for a part name, assuming you typically want to print part of a docUmenl. Youcan reply with an artifact or type a carriage-return. If the latter is supplied, the system willask for confirmation that you want to print the whole document. If you type "no", it willprompt you again for the name of a part; if you type "yes", it will print the whole document.

The examine-problems command similarly takes advantage of the finer structure of alatex-root artifact with parts. A document with parts typically has problems with morethan one part; the examine-problems command will present you with a list of just theseparts, from which you can use follow-link to see the latex-logs. If only one part has anerror, the examine-problems command will take you directly to the log fox" that part (ratherthan presenting you with a one-line list).

If you ask for something to be done for a part when a part is expected, no second argumentis necessary if the part is referenced in exactly one up-to-date latex-root artifact. (WVe say3 more about what up-to-date means in section 4.3.) If you apply a command to a partreferenced by more than one up-to-date latex-root artifact, you will see the error

5 Sorry - can't deal with more than one referencer yet

If there is no latex-root artifact referencer of the given part, you will see the error

3 Artifact name has no ref erencers

To summarize, if you use \parts, your latex-root artifact would conform. in general.* to the following structure

\documentstyle [12pt] {article}preamble(artifact] <bibliography>

I 1The utilities used for printing and previewing depends upon the user's installation. The values ofthe variables hardcopy-command, preview-command, and ps-preview-command (which can be examined in5 EMACS with M-x describe-variable) iihdicate which will be used.

3-IU

IUsers' Manual

[artifact] <bibliography>\begin{document}\parts[artifact]

[artifact]\appendix(artifact][artifact]

\end{document}

where anything that you want in the preamble could be contained in references. You callcount on the following to guide your use of LATEX artifacts.

o If you change anything in the preamble, LATEX will be rerun on everything.

o If you change, add, or delete a bibliography reference, LATEX will be rerun only on theg changed references and those parts whose citations are affected.

o If the document uses \parts, you can change a reference and/or add and/or deletereferences after the \parts command and E-L guarantees LATEX is rerun on every partand only those parts affected by a change. For example, if you add a new referencethat changes the section or page numbering in the rest of the document, LATEX will bererun on subsequent sections. On the other hand, if page numbers are start at I at thebeginning of each part, then changing the number of pages in one part will not causeIATEX to be rerun on subsequent parts.

1 o E-L will rerun IATEX on parts affected by a change until the results (such as labels andcounters) stabilize-that is, until subsequent runs would leave the output unchanged.

If the document does not use \parts, LATEX is always run on the entire document, so theissue of where it must be rerun does not arise.

1 3.4 Customizing Errors

After running IATEX, we scan several log files to look for errors. For this scan, we use threeregular expressions (re's). One is for the LATEX log (log), one for the BIHTEX log (big) andone for the makeindex log (ilg). You can substitute your own re's for the defaults. To do so.5 you add comments of a particular form to the latex-root. For instance, if you included

%watch-log: "! \\VILaTeX \\(error\\.\\iWarning: \\)"Xwatch-blg: "Warning--\\W(There w\\(ere\\Ias\\) [0-9)+ error messages?)$"Xwatch-ilg: "done ([-))*[1-9] [0-9]* rejected)\\."

33-5U

Users' Manual

anywhere in your root artifact, you would preseve the default behavior. Note that there's themselves must be double-quoted string constants. They obey EMACS Lisp escapeconventions, so, for example, the constants "\n", "\C-j", and "\012" are equivalent, andeach contains a single character, i.e., newline. There can be spaces and tabs between theIwatch-xxx: and the string constant. Anything at all can follow the string constant, e.g..-. ne explanatory words.

Because these regular expressions must be skipped entirely by lATEX, it's not feasible tolet quoted re's cross line boundaries. So none of the string constants can contain an actualnewline character, although any of the escape sequences mentioned above are permissible.I What's not allowed is something like

Ywatch-ilg: "[0-9]+V[] *errors"

because LATEX will try to interpret each line that doesn't start with a percent sign. The* equivalent

%watch-ilg: "[0-9] + [\n] *errors"

would be fine. To build up a long re, you can put several %watch-xxx: lines together, withthe same xxx in each. For example

%watch-log: "'! \\IlLaTeX \\(error\\.\\IWarning:\\) " (Default error checks)Iwatch-log: "\\'\\(Over\\IUnder\\)full \\\\[hvbbox " (Knuth aesthetics)

produces a single re for scanning .log files. It is obtained by concatenating the two stringconstants, Note that the whitespace and comments at the ends of the lines are ignored.The lines for a given watch-xxx declaration must be contiguous, and there can be at mostone such declaration (possibly occupying multiple lines) in the latex-root for each of thethree expression types. Furthermore, the (concatenated) re must be a valid EMACS regularexpression. If any of these rules is broken at commit time, an error will be raised to prevent3 commitment.

3.5 postscript Artifacts

This section is of interest to aficionados of LATEX and PostScript who want to use PostScriptin documents, for which we offer a postscript artifact type. A postscript reference can3 appear anywhere that a manuscript derivative is expected. When you create a postscriptartifact, the first line must contain a macro string that can serve as the replacement text of

* a TIX macro that conforms to the following rules:

o It may not have F2] (the null character), M (C-a), or -(newline).

o It must have a single parameter, denoted in the usual way: ####1.

o In the eventual expansion of the macro string, one of the following macros must be3 applied to the parameter:

3-6

I

1 Users' Manual

oo \ELPH-insert the PostScript file in the "header", where it will be outside thesave or restore context of individual pages. This is typically used for setting upPostScript libraries.

oo \ELPP-insert the PostScript file where it will remain only for the current page.This is typically used for insertion of PostScript pictures.

In other words, the first line of a postscript artifact might be

I Macro string: \ELPP{####1}

which, in fact, is the default in an initial postscript draft buffer. The ultimate effect of a

reference to a postscript artifact is that the text of its contents, after the first line, is madeinto the body of a PostScript function that is called at the point of reference.

111I1I11I1I

S3-7.

1

Users' ManualI4 More About Artifacts and Drafts

4.1 As Arguments to Commands

The default for an argument identified in this manual as artifact is taken from the cursorif possible. If the cursor is on a line that references an artifact, the artifact just after thecursor or else the last artifact on the line becomes the default argument. If the cursor is in abuffer on an artifact, but not on a line referencing another artifact, the artifact becomes thedefault argument. If you wish to refer to an artifact other than the default, simply type itsname. You will be prompted for a type when one is needed for disambiguation. Yet other

Sways to use the cursor to identify an artifact argument are mentioned in section 5.2. Theconventions for specifying a draft argument are analogous.

Once an artifact argument appears in the minibuffer, with the cursor at the beginningof the buffer, you can navigate to neighboring artifacts. [Ephemeral navigation is not yetavailable for drafts.] A neighbor is chosen with an EMACS-like command:

o C-p-referencers (previous/up)

o C-b-predecessors (back)

o C-f--successors (forward)

o C-n-references (next/down)

U o DEL-previous default (where you just came from)

The DEL command is particularly handy if you have navigated from artifact A to one ifits referencers, B, and then want to get back to A without going through a menu of B'sreferences. Just hit DEL and you'll be back at A. If there is a unique neighbor in thedirection indicated, it immediately becomes the new default without an intervening menu.

The navigation menu is an EMACS buffer invoked in a mode similar to the one used byelectric-buffer-list (C-x C-b). It lists the artifacts one step away from a given artifact in thedirection mentioned the menu's first line. The order of lines and the format of each lineis the same as the default format on the artifacts plex. To select a new default artifact,place the cursor on the appropriate line and type a space. To get more information aboutmenu keys, type your help key followed by "m" while in the menu (i.e. get help on the menubuffer's mode).

Some commands require two artifact/draft arguments. These commands will take theirfirst argument from the mark, if possible, and their second argument from the cursor, ifpossible. Sometimes you want to cut and paste references into a draft buffer. For this,and for multi-artifact/draft commands, you can use the kill ring as you would in ordinaryEMACS. That is, you can put references into the kill ring with the usual functions (C-w, M-w,C-k, M-d, or C-d, with or without a numeric argument), and you can yank them from the killring with the usual functions (C-y or M-y). This means you can cut and paste text withina draft buffer or even between draft buffers, using ordinary edit commands and not loseartifact references. You can also use the command copy-as-kill mentioned in section 3.13 to copy a reference into the kill ring.

4-1

I

IUsers' ManualI

4.2 Further Dealings with Artifacts

To examine an artifact without creating a draft, use

9 examine-artifact artifact C-z C-x

m This creates a buffer on the artifact, exactly like the buffer obtained after committing adraft. To examine an artifact in another window, use

m * pop-to-artifact artifact

It is sometimes useful to base an edit on several artifacts, rather than zero (create-

draft) or one (edit-artifact). The following command allows you to do this.

9 append-artifact-to-draft artifact draft

- The draft must iot be owned by another session. If not owned by this session, itis taken over.

- The artifact and draft may be of different types, but, if they are too dissimilar,you will get an error message. The command attempts to put the picces of the

artifact into reasonable places in the draft.

- The artifact becomes thc predecessor of the draft.

You can append several artifacts to the draft; each becomes a predecessor of it.As you continue editing, you will generate more and more artifacts. Rather than rely

completely on users to delete irrelevant artifacts, the system includes a customizable auto-matic deletion mechanism, described in appendix B. Situations also arise in which you dowant to delete one or more artifacts directly. An artifact may be deleted only under thefollowing conditions:

m o The artifact is not referenced by another artifact.

So There is no active draft based on the artifact.

o There is no other process (such as a user) that has it cached.

If these conditions are met, you may delete artifacts with the following commands:

* delete-one-artifact artifact C-z C-d

I * delete-artifact-and-references artifact C-z M-d

e delete-artifacts-in-region C-z M-D

The first command confirms the deletion or says why it was not done. The second commandattempts to delete the given artifact, and, if this was successful, attempts to delete referencedartifacts, and so on. It reports how many artifacts were deleted (perhaps none), but doesnot indicate why any particular artifact was not deleted. The third command is usable onlywhen the cursor is in a view on the artifacts plex. It deletes all the artifacts between the

4-2I

IUsers' Manual

mark and the cursor, including the end points. Note the uppercase D in the command, whichis there to make it difficult to issue the command accidently. The command announces thenumber of artifacts it has deleted, it will say when it's done, and it will update the view onthe artifacts plex as it goes. If an attempt to delete multiple artifacts is unsuccessful, youcan, of course, try deleting one of the artifacts (not referenced by any other artifact). If thatis unsuccessful, you will learn why. (When you delete an artifact, its predecessors becomeup-to-date. Thus, even after you delete an artifact, you may still see an up-to-date artifactwith the same name, but a different creation date.)

As with any repository system, you may eventually find that you want to export datastored in it-to archive the data off-line or to move it to another, compatible repository-ina form that permits it to be imported at a later date. The first command that you will needis

* write-archive artifact file [pred-p]

which stores the appropriate representation of the artifact and all its direct and indirectreferences in file. If the command is prefixed with two or three C-us, it will archive all of theartifact's direct and indirect predecessors as well. The mate of this command is

* read-archive file [override-timestamp] [override-creator]

which, by default, will restore the original timestamps and creators of the archived artifactsif possible. If the command is prefixed by one or three C-us, the current date and time willbe used for the timestamp. If the command is prefixed by two or three C-us, the current userwill become the creator. (Section 5.2 describes the timestamp, creator, and other attributes

* of artifacts.)Each of the following commands has to do with derivatives. After being asked to confirm

the artifact, you will be prompted for the kind of derived information that you desire. Thesystem also provides completion for kinds of derived information, so, by pressing tab at theprompt, you will see your choices. The commands also will take the kind argument, likethe artifact argument, from the cursor's position if possible. A reference in a buffer to aderivative, again like an artifact, is not ordinary text, as indicated by the fact that it ishighlighted. The first command allows you to examine a derivative of an artifact.

* examine-derivative artifact kind C-z M-x

You can call examine-derivative, for example, with a latex-root and an errorlatex-directory as arguments; this has the same effect as calling examine-problems on thelatex-root (if it has no bad derivatives). It is a generic function that you can apply to anytype of artifact, however. You can delete a derivative.

* delete-derivative artifact kind C-z d

Though the need seldom arises, you can request the derivation of a particular kind of deriva-tive from an artifact.

3 * derive-from artifact kind

4-3I

IlUsers' Manual

4.3 Further Dealings with Drafts

We mentioned earlier that there are commands to commit several drafts at once. One ofthese is the following command, which, if it finds a referenced draft, first attempts to commitit and, recursively, its references.

* commit-draft-and-references draft C-z M-s

If the draft that you are trying to commit references drafts that someone else is editing,however, the commit wi!l not be successful; you must get the other person to commit first.Another command

* commit-draft-and-references-and-ref erencers draft C-z M-C-s

attempts to commit drafts that reference the current draft and those that it references. Infact, it tries to commit every draft that it reaches by following reference relationships, ineither direction.

To commit a draft without scheduling any tools (such as LATEX) to be run on its behalf,precede the commit command by C-u, a standard "prefix" argument in EMACS. This isuseful, for example, if you expect to make several passes over a part or parts of a documentand want to commit them periodically but delay running LATEX until things settle down.

You may wonder what happens to an up-to-date artifact, like trial in the examplein section 2, when a referenced artifact, like triall, is edited. Is it up-to-date or out-of-date? The answer is almost out-of-date. When the user creates a draft of triall, thesystem generates a draft of trial, call it d. Starting a draft doesn't make an up-to-dateartifact out-of-date, but E-L does consider an artifact that has a draft successor to be almostout-of-date. The user must explicitly commit d to create an up-to-date successor artifact,after which the original trial is simply out-of-date. A user may want to edit a number ofreferenced artifacts before bringing forth an up-to-date referencing artifact. (The commandcommit-draft-and-ref erences-and-referencers is provided for this very purpose.) Westate some additional rules linking the notions of up-to-date, almost-out-of-date, and out-of-date in section 5.3. If you commit a draft of, say, triall, you will have two artifacts namedtriall; if you use the name in a subsequent edit-artifact, it will be assumed that youmean the most recent one.

To rename a draft, use

* rename-draft draft name

To delete a draft, use

@ delete-draft draft

If another draft references the draft you're deleting, the reference will revert to a predecessor.If the deleted draft has no predecessor, the reference to it will become empty.

If there is a crash while you were editing, drafts that you were working on become"abandoned". To continue working on them (from the last autosave, with the cursor restoredto the position it had when the draft was abandoned), you may use the command

4-4I

IUsers' ManualI

* takeover-draft draft C-z e

This command can be used to resume working on any "unhosted" draft. See section 5.3 tolearn more about system and abandoned drafts, both of which are considered unhosted. Youmay deliberately abandon a draft with the following command:

* abandon-draft draft C-z C-a

A typical use of this command is in handing a draft off to someone else to finish editing.without having to do an intervening commit. If the system finds any drafts lying aroundwhen you exit E-L, you will be given the option of abandoning or deleting them beforeexiting. You can also C-g and pursue other options, such as committing drafts. If youget out of EMACS in some other way, such as by exiting a window system, all your draftsautomatically become abandoned.

If you attempt to edit an artifact that has a draft successor, you will be warned that theartifact is "almost-out-of-date" and asked if you wish to edit it anyway. If you respond witha yes, and eventually commit both successor drafts, you will end up with two up-to-dateartifacts with the same name and type. If you respond with a no, you will be asked if youwish to takeover the draft. If you respond yes and the draft successor is unhosted, you willsimply become the creator of the draft and may proceed to edit it in the normal way. If thedraft is hosted, you may edit it only if you are the creator. If you respond no, the systemwill prompt you again for an artifact to edit. You can find the successor draft of an artifactby issuing the command

* find-successor-draft

while in a view on the drafts plex.Sometimes an editing mistake will so destroy the contents of a buffer that undo will not

restore it properly. If this happens, the following command wil! restore the buffer from thelast autosave

* revert-buffer draft

with the cursor restored to its position at the time of the autosave.

4.4 Further Dealings with Problems

The command, examine-problems, in general, provides information about bad or errorderivatives. The former occurs, for example, when a tool crashes or is aborted; the lattei,when a tool signals an error. If the examine-problems command finds only one probiernderivative-the typical case-it takes you directly to a buffer on that derivative. (In the caseof INTEX artifacts, this is an errorlatex-directory derivative.) If none exists, it tellsyou that. If there is more than one problem derivative, it sets up a buffer with one line perproblem in it, indicating the bad or error derivative, a short description of the problem,and a button to follow to learn more about the problem-or * if there is nothing furtherto examine. Placing your cursor on the button and issuing the follow-link command willexamine the kind derivative of the artifact if the artifact button is followed by <kind> or willexamine the artifact otherwise. If your cursor is not on a button, but, on a line without a *.

the follow-link command will examine the problem derivative.

4-5I

mUsers' Manual

4.5 Comparing

m The two commands tkat highlight differences between artifacts use a single command diff-buffers that highlights differences between any two EMACS buffers. This command promptsfor two argument buffers and, with a prefix argument (C-u), asks for a result buffer. Thedefault result buffer is *merge*. Using the Unix utility diff, diff-buffers1 combines thefirst two buffers and, in the third buffer, displays

I o their common parts with the standard background,

o data in the first but not in the second on a red background, and

"o data in the second but not in the first on a green background.

The unbutton command C-z u, when issued with the cursor in a differing (red or green)region, removes the highlighting; with a prefix argument (C-u), it deletes the highlighted text.You can move to the next, or previous, differing region with the next-diff-button-pair

I command C-z >, or previous-diff -button-pair command C-z <, respectively. You caneven customize the colors that diff-buffers uses with the commands set-diff-bucton-colors and set-diff-reference-colors; the latter is relevant when using the followingartifact-oriented commands.

The command

3 @ diff-artifacts artifact1 artifact2 buffer

is similar to diff-buffers, except that the first two arguments are artifacts not buffers.The result buffer has not only the red and green regions from diff-buffers, but also theusual blue regions displaying artifact references. Artifact references in differing regions stillhave a blue background, but the letters are red or green indicating that they are in differingregions. The command

e diff-artifacts-recursively artifact, artifact2 buffer

takes the same arguments as diff-artifacts but lists in the third argument the pairs ofdifferenced artifacts, one line per pair of artifacts. A C-z - (follow-link) in this bufferswitches to the buffer where the differences are displayed; killing such a buffer deletes theline. This command will compare artifacts that seem to be in the same place in the tworeferencing artifacts, without regard for whether they have the same name.

As with other commands that take two artifact arguments, these commands will usemark to offer a default for the first argument and the cursor to offer a default for the secondargument. If it is not convenient to have both artifacts in the same buffer, you can put oneof the artifacts in the kill ring and, when diff-artifacts[-recursively] p:-ompts you forthe artifact, yank the argument into the minibuffer. (It will be blue in the minibuffer. too.)

iThe present implementation requires EPOCH and color monitors.

4-6

Imm m m lll•m

IUsers' Manual

4.6 Searching

To search through a set of artifacts, you can use one of a couple of commands.

* re-search-artifacts-recursively artifact regular-expression filter [prefix] C-z s

- Starting at the given artifact, this command searches for the given regular expres-sion in its contents. With no prefix argument, it stops when a match is found, atwhich point you should respond with one of the following keys:

* c-continue the scan

* s-suspend the scan

* mr-mark this occurrence by placing it in a log buffer and continue the search

* !-continue the scan without further interaction, marking each match.

With a prefix argument, it does not stop when a match has been found but behaves

as if m had been typed.

- After searching the contents, the algorithm is applied recursively to each of theartifact's references that pass the filter and have not yet been scanned.

- The filter is accepted in the same way as the filter for a view on the artifactsplex. The first time this command is executed the default filter is one that includesall artifacts. For subsequent commands, the default filter is the filter given to the

command previously.

- If the prefix was used or if you responded with m oi, !, the command switches to abuffer having a line for each occurrence that you marked. You can jump to thatoccurrence in the usual way, with C-z -.

- The re-search-artifacts-recursively command names its buffer *Re-SearchArtifacts*. To get two searches going at once, simply rename this buffer andstart another search.

e re-search-artifacts-recursively-continue [log-buffei] [artifact] [prefix] C-z

- The purpose of this command is to allow you to resume a suspended search orextend a completed search. A suspended search is associated with a buffer. Ifthere is only one such buffer, you will not be asked for the log-buffer argument.

- If the previous search was suspended (using s), the artifact argument is not re-quested and the scan resumes just after the last match detected. (It rememberswhere it was in the recursion.) Previously scanned artifacts are not rescanned.

- If the previous search exited normally, the artifact is requested and a new scanbegins at that point. Again, previously scanned artifacts are not rescanned.

- The prefix argument plays the same role as in the previous command-it says tomark matches without interaction.

4i 4-7

Users' Mai.ual

4.7 Highlighting

i Several artifact/draft types have contents that indicate certain information by highlightedregions, where by "highlighted", we mean having a special color in a buffer. This is in additionto the use of highlighting for artifact references and the use of inverse video to indicate theformat of contents. The visual effect of the highlighting and, of course, the interpretationdepend upon the type. The command that you use to highlight text is independent of type.3 Several of the current artifact/draft types, including those that support programming,support two uses of highlighting. You indicate your intent in a particuiar use of highlightingby giving a numeric argument to the highlighting command.2 (If you specify a numeric argu-ment that is greater than the number of kinds of highlighting for that buffer, the maximumfor that buffer is used instead.) The default value of the numeric argument is 1, for the morecommon kind of use. Thus, for the common case, you need no argument; for highlightingwith a prefix argument of 2, you can use C-u 2. You may also use M-n in all cases.

To highlight text, use

3 . highlight-region3 7zC-z C-h

- Using the prefix numeric argument n, highlights the region from mark to point.U You may see other changes to the buffer, depending upon the type of the draft.

- If your cursor is in a highlighted region, this command will unhighlight the region.

Instead of mark and point, you can use left-mouse click and drag to indicate the region. Ifyou move your cursor into a highlighted region and begin typing, the new text will become

* part of the highlighted region.

4.8 Annotating

i The artifact type note allows you to attach a note to an artifact, much like you might attacha Post-It to a document. The contents of a note is unstructured and. in particular, mayfreely reference other artifacts. A note artifact differs from other types of artifacts in severalways: it has no derivatives, the system does not automatically create a successor draft to anote artifact when you create a successor to an artifact it references, and the system doesnot automatically delete note artifacts. You could use a note artifact, for example. to attach

a version number and list of recipients to a system artifact (that would naturally continueto evolve) or to associate profiling data with an artifact for future comparisons.

I

3 See the section "Numeric Arguments" in the Gnu Emacs Manual. In the fifth edition (version 18), thisis section 4.9, page 29.

3 lnteractively, the arguments are mark and point and a prefix argument indicating the kind of highlighting,or 1 if none has been given.

4-8I

I Users' Manual

I 5 Plexes

5.1 Introduction

3 We use the term plex for that portion of the E-L repository that describes dynamic relation-ships, such as among the artifacts, drafts, and their various properties. Plexes may involvelarge amounts of information, much of which you are not interested in at any one time.Consequently, a buffer on a plex has an associated filter to limit the amount of data thatyou see. Filters not only allow you to reduce clutter on the screen, but also result in fasterinteraction, because EMACS is dealing with smaller buffers. A buffer on a plex additionallyhas an associated format to control how the information in the plex that passes the filter ispresented on the screen. The contents of filters and formats depend upon the particular plexand cannot be described in general. However, the commands for examining the informationin plexes allow you to specify filters and formats in a uniform way.

To open a buffer onto a plex, use the following command:

3e view-plex plex [filter] Vormat] C-z C-v

- The second and third arguments are optional; a value for filter is requested if the3 command is prefixed by one or three C-us, and a value for format is requested ifthe command is prefixed by two or three C-us. (Thus three C-us means that botha filter and a format are requested.) Default values are used if these argumentsI are unrequested.

- This command opens a buffer on plex and makes this buffer visible in a window.

A buffer on a plex may be killed in any of the usual ways of killing a buffer.You may change the filter or format on a buffer by issuing one of the following commands

while the cursor is in the buffer. If they are given when the cursor is not in a buffer on a

plex, you will get an error.

e ref ilter filter C-z C-i

* reformat format C-z C-o

A fundamental point to keep in mind is that a buffer opened on a plex is actually a bufferof characters representing the "real" plex. You can think of it as a view onto the plex. Donot confuse the commands that change this view with commands that can actually changea plex.

You will notice that a buffer on a plex is always read-only. This does not mean that youcannot change a plex, but you usually can change plexes only in a very controlled way, withthe details depending upon the particular plex.

To find out the names of the available plexes, you can say

* view-plex plexes

The default format of the plexes plex is an alphabetized display. You may change this plex

only by adding or removing plexes. You can get on-line documentation of many of the plexes5by issuing the command

g 5-1

I.. ... .. ... . . • • • mm m m• - - -

IUsers' Manual

* buffer-documentation C-z ?

I with your cursor in the plex about which you want information.

3 5.2 The artifacts Plex

The artifacts plex is used to view all the artifacts in the repository. It displays artifacts,one per line, permitting the use of the cursor position in the artifacts plex to identity anartifact argument to commands. Both filters and formats for this plex are based on universalattributes, attributes that exist for every artifact. The current universal attributes are

I o name-this can be any sequence of inking characters.

o type-one of the types recognized by the system.

o creator-the user who created the artifact.

3 o timestamp-the time, down to the second, when the artifact was created. These aredisplayed according to the format

1 year/!mo/dauhr: mn: sc

In this format, all fields have two digits except year, which has four.

o up-to-date-a flag indicating whether the artifact has been superseded by one or moreartifacts, or whether a referenced artifact has been superseded, and so on, recursively.

I The system automatically completes names of attributes for filtering or formatting. A filteron the artifacts plex is a set of filters on the individual universal attributes, and an artifactpasses such a filter if each of its attributes passes the corresponding filter on the universal

attribute. The syntax and semantics of filters on universal attributes are

o name-a regular expression.' A name passes the filter if the regular expression matchesthe entire name. (This tends to discourage the use of characters that are special toregular expressions in the names of artifacts, e.g., + and *.) The default is . *, which5 matches all names.

o type-a set of types. A type passes the filter if it is in the set. The default is the setof all types. For this, as well as other attributes drawn from finite sets, the 11ser ispresented with an electric menu for augmenting and removing elements from the set.It is modelled after the electric buffer menu mode, and typing ? when the menu is firstpresented will display the available commands. The differences between the electric

menu and the electric buffer mode are that a space doesn't exit an electric menu, thesearch commands C-s and C-r are available, and < and > scroll the menu left and right,

3 respectively.

iYou can access the on-line description of the syntax of regular expressions in EMACS, with H-x infoand going to the node (emacs)regexps.

5-2I

Users' ManualI"o creator-a set of users. A creator passes the filter if it is in the set. The default is

the set consisting only of your name; elements are added or deleted from the set in thesame way as for types.

"o timestamp-a pair of strings, each of which is either a timestamp in the usual formator is the empty string (meaning open-ended). A timestamp passes a filter if

- the first element of the filter is the empty string, or this element is before (inclu-sive) the timestamp, and

- the second element of the filter is the empty string, or this element. is after (ex-3 clusive) the timestamp.

In other words, the filter defines a time interval, perhaps open at either end. The5 default is open at both ends.

"o up-to-date--one of the symbols +, -, or +-; an up-to-date flag passes these filters,

respectively, if it indicates the artifact is up-to-date, if it indicates the artifact is out-of-date, or always. The default is +.

When you are queried for a filter (either as an argument to view-plex or by the ref iltercommand), there is always a notion of the "previous filter", perhaps the default. You areprompted to indicate the universal attribute whose filter you wish to change-completion isprovided for the names of the attributes-and after doing so are presented with an electricmenu indicating the previous value, which you may edit in the minibuffer. Also, you onlyneed to specify an initial segment of a timestamp sufficient to indicate the non-empty element.Typing C-] while being prompted for the next universal attribute allows you to avoid going

through all the universal attributes once you have changed what you want to change.A format for the artifacts plex is a list of formats for the individual universal attributes,

called "column formats". Order matters, because each line in a view on the artifacts plexlists the attributes in the order of the column formats. A column format consists of the nameof a universal attribute, the width of the column (perhaps 0, which suppresses the column),3 and some data that depends upon the pal t;cular column.

o name, type, creator, timestamp-no format data in addition to the width.

I o up-to-date--two strings, the first to be used when the artifact is up-to-date, thesecond when it is out-of-date.

I As with filters, when you are queried for a format, there is a "previous format". You areprompted for universal attribute names in the order in which they appear in the previousformat; to change the order, just type the universal attribute that you want to appear next.Once you indicate which one is next, you are given the chance to change the width, and., ifthere is additional format data, then that too. The following commands may be useful:

I * C-)-signals the end of input: use the changes indicated so far, followed by the un-changed columns in their original order.

55.3

I

IUsers' ManualI

e M-])-restart input with the changes made so far acting a&- the previous format.

3 * M-C-l--restart the input with the original format.

3 5.3 The drafts Plex

The drafts plex tracks all drafts in the system. A user's principle interaction with it ib toprovide arguments to commands for drafts (such as those in section 4.3). Filters for this plexare not available, but there is little harm in that since there are never many drafts aroundat one time.

The format for the drafts plex is similar to that for the artifacts plex, although adraft has only a subset of the universal attributes of those for an artifact:

3 o name, type, creator.

(It does not have the timestamp or up-to-date universal attributes.) In addition to fieldsfor the universal attributes, the drafts plex has fields for predecessors and references. Ifthe draft has no predecessors, the corresponding field is blank; if it has one predecessor,the name, type, and timestamp appear; if a draft has more than one predecessor, a numberof dashes equal to the number of predecessors appears. A number of asterisks equal to thenumber of references appears in the references column. [Eventually you will be able to supplyan artifact argument by positioning the cursor on a reference in the drafts plex.] An entryin the drafts plex also has "where" and "initialized" fields. The where column presentlyI has a host and port number, not yet quite reasonable to look at, identifying the E-L sessionresponsible for the draft. If the where column is blank, the draft is said to be unhosted.The initialized field is either blank or simply the string "initialized". Drafts may thus becatalogued as follows:

o system draft-unhosted and uninitialized

o abandoned draft-unhosted and initialized (see section 4.3)

3 o starting draft-hosted and uninitialized

o normal draft-hosted and initialized

I There are a number of invariants governing the maintenance of the drafts plex. Thefirst two of these require the presence of certain lines in this plex.

I o For every EMACS buffer on a draft, there is a line in the drafts plex whose where fieldis the host and port number for that buffer's E-L session.

£ o All referencers of an almost-out-of-date artifact are also almost-out-of-date.

If necessary, the system creates drafts to maintain the latter invariant. We also need aninvariant to remove such drafts if edits are aborted, but, before we get to that, it is necessaryto understand the roles of the user and the system in editing references. The general principleis that only a person may add or delete a refeience, while the system is allowed to change an

5-4I

Users' Manual

existing reference, such as changing a reference to a draft to a reference to a newly committed5 artifact. Recall that artifacts referenced by an up-to-date artifact have no successor artifacts(by definition). There is a similar rule for references within drafts.

5 o An artifact that is a reference of a draft must be up-to-date and not almost-out-of-date.

Assume that this holds at the start of an edit. [At present, E-L does riot check this.] Ifan artifact p referenced in a draft d becomes almost-out-of-date during the edit of d, it isbecause there is some draft d' having p as one of its predecessors; in this case, the systemchanges the reference of p in d to a reference of d'. Similarly, if d' is subsequently committed,the reference of d' in d is changed to an reference of the new artifact generated by the commit

of d'.A reference in a draft may actually "reference" multiple artifacts or drafts, reflecting

Ssupport for divergent and convergent evolution and aborting drafts. For example, creatingtwo successors of an artifact (divergent evolution) will create a system draft where thereference corresponding to the now out-of-date artifact will be the two references, one toU each successor. Similarly, referencing a draft with two predecessors (convergent evolution)and then aborting the draft will result in a reference (with references) to the two predecessors.Finally, consider the reference of a draft with no predecessors, followed by an abort of thedraft. This will result in a reference with a null set of references.

We are finally in a position to describe the elimination of system drafts if edits arei aborted.

o A system draft exists only so so long as it has at least one reference that is different* from the corresponding reference in its predecessors.

5.4 Scheduling

I Whenever you commit an artifact, E-L schedules one or more jobs that take that artifact asinput. A job is run by a process called a job server. Although job servers may be started andstopped by E-L commands, the lifetime of a job server is independent of any E-L session.Jobs are run one at a time by a given server, but there may be several servers per host and,of course, several hosts on the network. In general, nothing prevents a job server on one

I host from running jobs scheduled anywhere on the network. We describe the commands forstarting and stopping a job server in section 6.1.

The variable job-done-notice provides a convenient way to know whether a job thatyou have scheduled is done. The default value of the variable is the symbol query, whichmeans the system will ask you each time vou commit an artifact whether you want it to sendyou a notice when it has completed computing the relevant derivatives. If the variable's

value is nil, E-L sends no notice, and, if the value is neither 'query nor nil, E-L alwayssends a notice. Thus, if you want to be notified when a job is done, you can set the value ofjob-done-notice to, say, t.

You can also get all the gory details about the status of jobs by viewing the schedulingplexes-past, present, and future.

55-5I

Users' Manual

"o future-this plex has one line for each job that is scheduled but not yet being run.5 Columns in this plex are

- priority-a single digit integer indicating the priority of the job; 1 is the highestpriority, and 9, the lowest.

- start-time-a timestamp indicating the time at which the job was scheduled.

- who--the person who submitted the job (often by committing an artifact).

- tool-specifies what is to be done. If some kind of information is to be derived,then the job to be run is what is called a deriver for that information (and tool3 will be derive); otherwise, it's the name of the specific tool to be run.

- args--specifies arguments for the tool. When the tool is derive, this field is thename and type of the artifact and the kind of information to be derived.

o present-has one line for each active job server on the network. Job servers run toolsopportunistically. Columns in this plex are

I - server-a host and port. If the server is not actively running an E-L tool invoca-tion, the other columns are blank. Otherwise, the other columns give informationon a currently running job.

- start-time-carried over from the future plex.

- who, tool, and args-same as in the future plex.

"o past-has one line for each completed tool invocation.

S-- start-time-carried over from the present plex.- stop-time-time at which the job completed. (The year, month, and day are not

displayed.)

- who-carried over from the present plex.- results-in the case of derivers, a string indicating a successful completion (ok)

Sor giving some hint of the difficulties encountered.

- tool and args-tool-dependent.

In each of these plexes the default order of columns is that given above. [There is presentlyno meaningful format to change the appearance of these plexes, nor are there meaningfulfilters for the future and present plexes, each of which is usually quite short.] A filter forthe past plex is the same as the filter on the timestamp attribute of the artifacts plex: apair, each of which is either a timestamp or the empty string. Only jobs whose start-timepasses the filter appear in a view on the past plex. The default filter has the time of thestart of the E-L session as a lower bound and an open-ended upper bound.

The following command offers a convenient way to delete jobs from the future plex:

5 a delete-future-j obs

[There will eventually be a schedule plex that provides a way of looking at the past,i present, and future plexes in a single window.]

5-6I

Users' ManualI5.5 The notices Plex

5 The notices buffer discussed in section 2 is actually a view on the notices plex. A filterfor this plex is a list of users, initialized to the name of the person starting the E-L session(so by default, you see only your own notices). The filter may be changed in the same wayas the creator attribute of the artifacts plex. A format for the notices plex consists ofthree integers: the widths of the name, id, and summary fields.

A view on the notices plex is established as part of starting an E-L session, but thewindow is displayed only if there are notices that pass the filter. Changes to the noticesplex cause a screen on the buffer to pop up.

If you create several views on the notices plex or if you delete all views on it, thereare obvious difficulties with the behavior of the default arguments to the notices com-mands described in section 2. Since the notice commands always ask for confirmation, theindeterminacy of default arguments should not be a serious problem.

In the present version of E-L, if you delete all views on notices, the system stops alertingyou as new notices arrive. The notices are not lost, however. You can see them by viewing3 the notices plex with C-z C-v.

3 5.6 The users Plex

Every user of E-L must be registered in the E-L repository. This happens automaticallynow, when you start E-L. In the future, installations may want to have some control overthe addition and removal of users. With that in mind, we have the following basic EMACScommands:

I * new-user name (this must be a login name)

9 delete-user name

The set of authorized users is kept in a users plex, which may be examined in the usualway. You are not permitted to delete a user who is the creator of an artifact. Though you3 are the default creator of artifacts, you can change this default behavior with the command

e change-active-user name

5.7 The hosts Plex

Every machine that is expected to host a job server must be registered in the repository, forwhich we have the following commands:

3 . new-host host machine

9 delete-host host

I where host is the local name for an instance of a particular machine architecture, like sun3or mips. Each line in the hosts plex simply names a registered host and its machine type.

55-7I

IUsers' Manual

6 Troubleshooting

6.1 Servers

The E-L system employs several servers in its efforts to support multiple simultaneous users,active views, and opportunistic tool invocation. These include one lock server; one activationserver, which invokes the repository checker and automatic deletion mechanism using theinformation in the alarm-clock plex; any number of job servers, entries for each of whichappear in the present plex; and a pair consisting of a utility server and a message serverfor each EMACS session. Should it be necessary, you can abort, stop, and start the serversfrom within E-L with the commands described below or, as a final resort, you can stop themfrom the shell with kill -2.

If you are told that there Is no active job server on the network, you may need to starta new one. To do so, use the command

3 e start-job-server

To shut a job server down gracefully, use the following EMACS command:

U e stop-job-server server

The default for a server argument is taken from the cursor position if the cursor is in a viewon the present plex; alternatively, a host and port number, separated by a colon, may beprovided. If the server is running a job, shutdown will occur when the job is complete. Ifthe job server has crashed while in the middle of a job, the job data will be moved to the

Spast plex. If you want to terminate a job pre-emptively (because, for example, you know itcannot complete), you can issue the command

e abort-job server

with the cursor on a line in the present plex. The job server will try to terminate thespecified job and, if successful, will produce a bad derivative with an indication of why itwas produced. For a stronger hammer, you can prefix the abort-job command (with theusual C-u); it will then definitely abort the job (and may abort other jobs in the same jobserver as well) and produce a bad derivative.

If a job server crashes after it has created an artifact (and updated a view on the arti-facts plex) but before the artifact has been preseved on disk, the user can see the following3 warning:

Artifact is in a view twice

I This is only a warning, reflecting an operational problem, not a bug.Host crashes and other system failures can leave E-L's repository with dangling references

to processes-either job servers or E-L sessions-that no longer exist. In such cases, E-Lwill warn you that it cannot connect to a particular hostport, and it records the warning ina buffer called *error-log*. If you believe that the process identified with the hostport is

I no longer alive, you can safely remove the dangling reference with the command

6-1

IUsers' Manual

i * goodbye-hostport server

This will pick up its argument from the cursor's position, much as is done for artifact anddraft arguments. For example, you can position the cursor on the appropriate warningmessage in the *error-log* buffer. If the hostport identified an E-L session, then any draftthat was hosted by that session will become unhosted (see section 5.3 for a discussion ofthis aspect of drafts) and can be taken over or deleted (see section 4.3 for a description oftakeover-draft and delete-draft). The command not only excludes the hostport of theuser's current session from consideration but also checks, in general, whether the process fora hostport is actually dead.

If the system seems to be taking unduly long to respond, it may be because a server hasan exclusive lock on data that you need. You can determine the status of all the locks and5 servers with the command

e show-locks [server switches]

SYou can request information about a particular hostport with the usual notation (host andport separated by a colon) or request some other subset of information with switches:

3 o -i displays information about the lock server

o -s displays the status of all locking clients

3 o -p displays the pending lock requests

3 o -g displays the granted locks

o -c displays the locks held by each client

5 Giving no server or switches displays the status of all the locks and servers.

3 6.2 Missing Drafts

If your E-L session crashes, references may exist to drafts that do not appear in the drafts

plex. In that case, you will be told to use

9 find-missing-draft draft-id

and given the relevant draft-id to provide as the argument. The command tries to return a

hostport to which you can apply goodbye-hostport, after which all references to the draftare gone.

II5 6-2

IUsers' Manual

A Customizing LATEX Output

I As we say in section 3.1, each artifact type has its own rules for producing manuscript andcaption derivatives. To encourage uniformity, however, we advertise here several macrosthat allow users to affect the way a deriver typesets an artifact, its caption, a reference's

caption, and any inter-section dividers. By redefining a macro, with \renewcommand, ina I0TEX artifact you can change the typesetting of subsequently referenced artifacts. Acommon practice is to include customizing definitions in the preamble of your latex-rootreferencer. Any deriver using the default definitions should also give reasonable output onmost text. Be warned that what we describe below is expected, but not required, behavior3 of derivers.

"o \MScaption This is used to typeset an artifact's caption (when typesetting the artifactitself). Whatever appears in the caption line-that which follows Caption: in thebuffer-is passed as the sole argument to this macro. Its default definition

3 \def\MScaption#1{{\rm\bf #1}\hfill\\}

typesets the caption line in bold Roman type. If, say, you wanted the caption line in3 italic type followed by extra vertical space, you could make the following redefinition:

\renewcommand{\MScaption} [1) {{\it #1}\hfill\\ [2ex] }

5 You can also inhibit the typesetting of the caption altogether by defining the macro todo nothing:

3 \renewcommand{\MScaption} [1i {}

"o \MSreference This macro is used to typeset a reference's caption, arising when areference is followed by <caption>. By default, it typesets the caption derivative in

Roman type and encloses it in square brackets, while respecting, of course, any furthertypesetting commands within the caption line itself. Its default definition is

I \def\MSreference#1{{\tt [}{\rm #l}{\tt III

You could redefine the macro in the following way if you want references to stand outmore

3 \renewcommand{\MSreference} [1] {\fbox(\bf #1}}

"o \MSuncaptionedreference If the caption of a reference is wanted but none has beenprovided, a manuscript deriver would use this macro, with the reference's type as itsU argument. Its default definition is

\def\MSuncaptionedreference#i{Uncaptioned{\tt #i}}

A-IU

Users' Manual

"o \MSdivider The editor may display an artifact with dividers to delineate sections ofthe artifact. A manuscript deriver can use \MSdivider to typeset such dividers, withthe divider's label (e.g. Targets for unix-program artifacts) as its single argument.The default definition is

\def\MSdivider#l{\raisebox{ 6ex}{\makebox [\linewidth] %\makebox[lin]{\hrulefill}\raisebox{-.6ex}{\it\ #1 }\hrulefill}}}

I which you are free to override.

"o \MSnulldivider This differs from \MSdivider only in that it has no argument for alabel. Its default definition is

\def\MSnulldivider{\raisebox{. 6ex}{\makebox [\linewidth] {Y,\makebox [lin] {\hrulefill}\raisebox{-. 6ex}\hrulefill}}}

" \MSsetcaption This one-argument macro typically appears first in a manuscriptderivative. It would be passed an artifact's caption, either one explicitly providedby the user or a type-specific default. If neither is available, the command would notg appear in the derivative.

\def\MSsetcaption#l{\def\MScapt iontext{#I}}

Its function is to make the text of a caption available for use, via \MScaptiontext, inother macros.

You would normally put these definitions in a referencing latex-root artifact or just beforethe first reference that you wanted them to affect.

AIIIIIUIII

A -2I

UUsers' Manual

B Automatic Deletion

I The system includes a repository checker that looks for inconsistencies in the repositoryand deletes artifacts according to parameters we describe below. The following observations

* motivate the deletion policy:

"o The time between the creation of artifact p and its youngest succezsor is a roughmeasure of the difference in their content and the "stability" of p. If p is succeededalmost immediately, the chances are that the change is small. If p persists for quite awhile before it is changed, its content is more likely to be correct. However, as p's ageincreases it becomes less and less likely to be preferred to its immediate successors.

"o If p has many, many successors, it is probably unimportant unless it has somehow been3 marked as important by a user.

To make precise the policies implied by these observations, we need some definitions. Asuccessor chain of length n of artifact p is a sequence of artifacts p = po, pi ... , p, such thateach pi-I is a successor of pi (i = 0,..., n - 1) and p,, has no successors. A minimal successorchain for p is one whose length is no greater than any other. Define kp to be the length of aminimal successor chain. For example, kp = 0 if and only if p has no successors.

Let p' be the youngest successor to p. Let t' be the difference between the timestampof p' and that of p, and let t, be the age of p. Define the age ratio of p to be rp = t1/t'.

Obviously this definition only makes sense if p has at least one successor.The criteria for automatic deletion fall into two categories. The primary deletion criteria

are formulated as conditions under which an artifact may not be automatically deleted.

3 o The artifact has referencers. The reason is obvious.

o The artifact is of type note. This allows users to preserve artifacts by including themin note artifacts.

o The length of a minimal successor chain is less than two. Thus an artifact must bedoubly out-of-date to be considered for automatic deletion.

Once these conditions obtain, deletion depends on the secondary deletion criteria, based ontwo integer parameters:

o R, the maximum allowable age ratio; and

o K, the maximum length of a minimal successor chain.

3 An artifact p is subject to deletion if it meets the primary deletion criteria and if either

or rp > RI or

kp> K

B-II

Users' ManualIThe present value for each of R and K is 20.

To give users an additional last-minute opportunity to retain useful artifacts, we createa list of so-called doomed artifacts that meet the deletion criteria; we actually delete theartifacts 24 hours later. You can view this list with the command

SI a view-doomed-artifacts

The command presents the list of doomed artifacts in the format of a default view on the

artifacts plex. The first two lines show the parameters used to determine the list. Artifactentries may be copied to the minibuffer or used as arguments to commands that take artifact3 arguments, just as in a view on the artifacts plex.

BIIIII

IIIIII

13-2

I

U5 Users' Manual

I C Installation

This chapter is intended for the installer of the E-L system-someone who wants to set up3 E,-L from the distribution as received via network or tape.

C.1 Prerequisites

U An E-L distribution contains:

a * E-L sources.

o Sources for Epoch-3.2 E-L, a variant of Epoch-3.2 (patch level 2) that has been modifiedfor use with E-L. Epoch-3.2 is a version of GNU Emacs 18.55 that has been integratedwith the X window system.1

* Sources for Emacs-18.55-E-L, which is a GNU Emacs that has been customized in thesame way as Epoch-3.2-E-L. This version of Emacs is used for batch-mode compu-tations, such as the nightly running of an integrity checker and garbage collector forg E-L's repository.

The customizations of these editors made for E-L enable its database views, error summaries,menus, and so on, to be more informative. Furthermore, the customized versions are morereliable than the stock versions from which they derive; they respond more gracefully tosignals and transient memory exhaustion, and they can automatically checkpoint certaincritical buffers when an interactive session is idle. Each is also suitable as a stand-alone3 editor, independent of its use for E-L.

Until recently, we did not distribute Emacs as well as Epoch. There is a good deal ofcommon code in the source trees, and much of it (notably the Emacs Lisp library) remainsafter installation. We have added Emacs to our distribution because of storage corruptionbugs that we have fixed in Emacs 18.55; with vanilla Emacs, these bugs sometimes made itimpossible to collect repository garbage in the background. Rather than spend time makinga merged distribution of Epoch-3.2-E-L and Emacs-18.55-E-L, we intend to move as soon aspossible to Epoch 4.2. That system has been structured so that an ordinary, batch-operableEmacs can be produced from the same source tree as Epoch.

In addition to Epoch, E-L uses, or may optionally use, other commonly available systemswhich are not on its distribution tape.

X windows. E-L is intended to run under X, and it works best on a color monitor.While it can be used acceptably on a monochrome display, E-L has some commands3 that require color to be useful. For example, a class of "diff-based" commands, basedon a fancy display of differences between files, artifacts, etc., distinguish old and newversions using color.

'Epoch war developed by researchers at, the computer science department of the University of Illinois.

1I C-i

UUsers' Manual

"* INTEX. E-L is a highly document-oriented environment, and it depends on the LATEXtypesetting system. If you do not have it already, you'll need to obtain and installITEX. (Note: the makeindex program distributed with LATEX is old; a more recentversion is available in the pub/tex/pub directory at csc-sun. math. utah. edu.)

1 * dvips. E-L also supports postscript artifacts, to allow PostScript inserts in LATEXdocuments with efficient incremental update processing. The implementation of post-script artifacts depends on a particular utility, called dvips, for translating LATEX'soutput (in "dvi" format) into PostScript. In the US, dvips seems to be the mostpopular and feature-full of the PostScript drivers for dvi files. It is quite well docu-mented and maintained. On the Internet, it can retrieved by anonymous ftp fromhost labrea. stanford. edu.

If you do not plan to use postscript artifacts, you don't need to obtain dvips, butyou will need some means to convert dvi files to printable form.

" Ghostscript. E-L's activity coordination facility requires this PostScript interpreter.It is also the basis for a very good PostScript previewer called ghostview. Bothcan be retrieved from the pub/ghost directory at ftp. cs.wisc. edu. Version 2.5.2 of

Chostscript works quite well with E-L. A later version is available but has not yet beentried with E-L.

"" Lucid Common Lisp. E-L supports programming in Lucid Common Lisp, version3.0 or later. (The dependence upon Lucid has to do with its foreign function facilityand its asynchronous processes. Other Lisps with similar facilities could be similarly

supported.) As we will see later in the installation instructions, this is optional on anarchitecture-by-architecture basis, including the case of no support for Common Lispat all.

3 To date, E-L has been ported to Sun3 and Sun4 workstations running SunOS 4.x and tothe DecStation 3100 running Ultrix 4.2. All the hosts sharing an installation of E-L mustg be linked by a common file system.

C.2 Installing E-L

I To install E-L, you need three source directory trees, one for E-L (called e-l-distribution),one for Epoch (called epoch-3.2-e-1), and one for Emacs (called emacs-18.55-e-1).

Disk space for installation. The three source trees (E-L, Epoch, Emacs), in uncom-pressed form, together consume about 30 megabytes of space. If you install E-L for use on3 N types of machines ("architectures") of which L will have artifact support for CommonLisp, expect the space required to swell to about 28 + 34N + 8L megabytes. After everythingis in place, you'll need to retain about 18 + 24N + 8L megabytes.

To start installation, make an empty directory on in a filesystem with sufficient free spaceand change into that directory.

CC- 2I

UUsers' ManualI

Reading sources from tape. If you received E-L on tape, mount the tape and use tar5 to read the tape:

$ tar xf /dev/rstO

3 The device /dev/rsto used here would be typical for reading a cartridge tape on a Sunworkstation. Substitute the correct device file for your tape drive. You will have threesubdirectories named e-1-distribution, epoch-3.2-e-1, and emacs-18.55-e-1.

Extracting E-L sources from a compressed tar file. If you received E-L by net-work file transfer, you can uncompress and extract the E-L source tree from the file e-1-distribution.tar.Z as follows.

5 $ zcat e-1-distribution.tar.Z I tar xBf -

Once the E-L tree has been extracted, the compressed tar file can be deleted to save space.Repeat the same procedure for the compressed tar files epoch-3.2-e-1.tar.Z and emacs-18.55-e-1 .tar.Z.

Installing Emacs and Epoch Next, install the customized versions of Emacs and Epoch.Since Epoch is a variant of Emacs, the directions for building them are the same. Thefile README.E-L in the emacs-18.2-e-1 subdirectory just created by tar leads to full in-structions for building and installing Emacs. The corresponding file in the epoch-3.2-e-1directory tells how to install Epoch.

5 Installing Ghostscript If you plan to use E-L's activity coordination facilities, be surethat your installation of Ghostscript includes support for the PostScript level 2 and DisplayPostScript extensions. With Ghostscript version 2.5.2, this is done by adding level2.devand dps.dev to the definition of FEATUREDEVS in either unix-cc.mak or unix-gcc.mak(depending on whether you compile Chostscript with cc or gcc). The resulting definition3 typically reads

FEATUREDEVS=filter. dev dps. dev level2, dev

5 Contents of e-1-distribution. The file named MANIFEST in the e-l-distribut ion sub-directory contains a list of the files and subdirectories in the E-L portion of the distribution.

* Check to be sure that all seem to have been extracted.

Setting configuration parameters. Set up three directories to hold the permanent re-3 sults of installation:

"• The repository directory, where all the data for E-L is kept. In the example below, the5 name is /usr/local/e-1/repository.

"• The bin directory, where E-L programs are kept. The example will use /usr/local/3 e-1/bin.

C-3I

UUsers' Manual

* The lib directory, where libraries needed for certain extensions of E-L are kept. The5 example will use /usr/local/e-l/lib.

These do not need to be subdirectories of a common directory, as they are in the example.However, they need to be accessible from any host on which E-L will be used. The pathleading to each must exist before you install.

Make a copy of e-l-distribution/configure-e-l. sample. Call it configure-e-l, orwhatever you like. We'll refer to it as your configuration script. It records decisions made insetting up E-L, such as where the three permanent directories mentioned above are located.

Following the instructions in configure-e-1. sample, edit your configuration script tocustomize it for your repository. Record the paths of the three permanent directories byediting the values of CONFIG.REPOSITORY, CONFIGBIN, and CONFIGLIB.

When E-L refers to programs and other files that are not part of the artifacts systemitself, it does so via links that reside in the bin directory. (This ensures that utilities likelATEX that may be invoked within E-L processes will not be misidentified through some quirkof a particular user's $PATH setup.) For each of the remaining CONFIG-.... variables in theconfiguration script, supply an absolute path that is appropriate for your sy,,Lem. For eachtype of host on which you compile E-L, the configuration script will be read and a separatesets of links will be created, so you may use (Bourne shell) conditionals to differentiate amonghost types if you wish.

In the same directory, the file universal-paths .el contains additional absolute paths,those of system header files and commands that may be referred to within C language arti-facts. Installation incorporates these paths in universal artifacts as a way of encapsulatingdependence on the external objects and tracking changes to them. (See the Language User'sManual.) Scan the lists for appropriateness at your site; edit and extend them as needed.The set of universal artifacts created during initial installation (owned by the pseudo-usere-1) will be adjusted accordingly.

Building the E-L executables. All executables are built on site. This minimizes instal-lation difficulties, but it takes a while. To prepare executables for the machine architectures

(e.g., sun3, sun4, or mips), on your network, go through the following steps once for each,using a representative host machine.

* Log in to the host, if necessary, and make the e-l-distribution directory (createdabove) your current working directory.

3 o Using the configuration script that you customized, issue the command

$ ./compile-e-1 [-no-lisp] ./configuration-scriptoutput from the compilation process, ending with:5 Finished compiling

Use the no-lisp switch if you do not want lisp support on the particular architecture. Theeffect of the compile-e-1 command is to add a subdirectory (named by the machine type)to the e-l-distribution/bin directory, and to put the relevant executables into it. It alsoadds subdirectories to the lib directory. One, named by the machine type, receives object3 files and archives. Another, called include, receives header (.h) files.

C-4I

Users' ManualIThe installation environment. After the above step, the e-l-distribution directoryis ready for installation. You must be running X, and Epoch must be available. Be sureyour DISPLAY environment variable is properly set for your X server, e.g.:

$ setenv DISPLAY server-host:0.0

E-L uses the environment variables E.LREPOSITORY, EL.BIN, EL._LIB, and E-L-MACHINE tocommunicate with the processes it creates. An attempt to install E-L or to run E-L once3 installed while you have any of these set in your environment will produce an error messageunless your settings agree precisely with the ones E-L means to establish. In short, be surethese variables are not in your environment before installing E-L or starting an E-L session.

The installation program starts a daemon process named e-l-lock-server and leavesit running after installation is complete. This lock server process is E-L's resource managerfor the whole network of machines sharing E-L, and there should be only one instance of itrunning at any time on the network.' Choose as stable and fast a machine as possible to hostthis resource manager. Log in to that machine (if necessary) to complete the installation,5 and change your working directory to be the e-l-distribution directory.

Installation. Issue the command:3 $ ./install-e-I ./configuration-script

This starts an Epoch session and displays messages about the progress of the installation.If everything goes normally, Epoch exits when installation is complete. In any case, theprogress log is saved in a file called progress in the e-l-distribution directory. Glanceover that file to be sure no errors have occurred.5 The next step is to add e-l to the command directory (or directories, if there are differentfile servers for different hosts) from which it will be executable by your E-L user community.A typical choice is /usr/local/bin/. You may need root (super-user) privileges do this.Create a symbolic link called e-l in the command directory to a shell script of the samename in /usr/local/e-l/bin/scripts.

3

$ in -s /usr/local/e-l/bin/scripts/e-l /usr/local/bin/e-I

Finally, you should add e-l-lock-server to the set of daemons started at reboot time onthe host you have chosen to run the resource manager.4 Typically, this is done (again, withsuper-user privileges) by adding the following lines to the end of the script /etc/rc. localon that host:

2That is, one instance per installation of E-L. As will be discussed below under "Creating a branchrepository", it is sometimes desirable to have multiple instances of the artifacts system at a site, withindependent repositories for each. There should be one lock server process (but only one) for each repository.

3 Because symbolic links are used, however, it is only necessary to have rights to change the commanddirectory when initially installing E-L, or when changing the location of the bin directory, in which case youwill need to re-link e-1 in the obvious way."4While this step is highly desirable to support regular use of E-L, you can omit it if you're prepared to

restart the lock server manually whenever its host machine is rebooted. The command to do so requiresno special privileges: e-1 -do e-l-start-lock-server. (The -do switch is explained in section C.3.) Itis also a very good idea to stop the lock server gracefully before a planned shutdown of its host: e-1 -do

3e-l-stop-lock-server.

C-5I

Users* ManualU8

# Lock server for E-L#if C -f /usr/local/bin/e-i ]; thenf (/usr/local/bin/e-1 -do e-2-start-lock-server) >/dev/console

At this point, E-L is ready to run. Under the C shell, you may need to rehash if youhave just finished installing E-L, so that the e-l command will be recognized. To t:y it out,start E-L in the background (so as not to tie up your shell window); it will create its ownwindows:

$ rehash! $ e-l &

Updating an existing installation. The installation procedure above creates a freshartifacts repository, completely empty. If the distribution you received is an update foryour existing installation, the procedure is slightly different, so that the information in yourrepository will not be destroyed.

Begin by shutting down all E-L-related processes on your network. To shutdown anyexisting job servers, use the M-x stop-job-server command. Terminate any E-L (Epoch)sessions. Shutdown the resource manager (lock server) using the command

3 $ e-1 -do e-l-stop-lock-server

Next, compare your old configuration script with the new configure-e-1. sample. Merge5 and edit if necessary to create a new configuration script for your site. Use the same reposi-tory, bin, and lib directory paths as in your existing installation. Then follow the instructionsin the paragraph above on "Building the E-L executables". Finally, perform the update usingthe command

$ ./update-e-1 ./configuration-script &

Creating a branch repository. Occasionally, it is useful to create a secondary artifactsrepository, one that shares the basic functionality of the primary installation, but that hasseparate artifacts and plexes, and may even have some different (perhaps experimental) arti-fact types and derivative classes. We call such a secondary repository a "branch" system-byanalogy with a branch office, such as a bank branch. A branch is quick to set up, given thedistribution directory and the results of a primary installation, and doesn't use much addi-tional disk space (less than a megabyte, independent of the number of machine architecturesaccommodated). Use one to test extensions of E-L if you need to be certain of not interferingwith production use of the system. 5

To set up a branch repository, set your working directory to be the distribution directory.5 If you haven't kept the directory used to perform the original installation on disk, you should

51n a future version of E-L, there will be other ways of isolating experimental extensions, so the need fori a separate repository will not arise.

C-6I

Users' ManualIrecover it and be sure that the configuration script is as you modified it originally. You donot need to repeat the compile-e-1 step, however, because a branch repository shares thecompiled C executables and makes copies of the Emacs Lisp and shell-script executables ofthe original installation.

Now edit the configuration script to define and export the new environment variablesBRANCH-REPOSITORY, BRANCH-BIN, and BRANCH-LIB in the same way as for the variablesCONFIGREPOSITORY, CONFIG-BIN, and CONFIGLIB, but using directory paths chosen for3 your branch system. For example

BRANCHREPOSITORY="/usr/local/e-l-branch/repository"BRANCHBIN-"/usr/local/e-l-branch/bin"BRANCHLIB="/usr/local/e-l-branch/lib"

3 export BRANCH-REPOSITORY BRANCH-BIN BRANCHLIB

Again, there is no requirement that these three directories have a common root. You shouldcreate each of them before starting branch installation. If any of them is not empty whenbranch installation begins, you'll be asked whether it is all right to delete the contents.

The command to install a branch E-L is just like that for primary installation, except3 that branch-e-I replaces install-e-l:

$ ./branch-e-1 ./configuration-script &

3 The bin and lib directories share the C-code executables and libraries of the initial installa-tion. However, the subdirectories containing Emacs Lisp code and shell scripts are separatefor the branch system, as is the whole repository directory.

Example artifacts. In addition to the artifacts of type universal mentioned earlier, theinitial installation creates some example artifacts for use in understanding how programs anddocuments are constructed and interconnected in E-L. These are rooted in an artifact namedLife, whose creator is the pseudo-user e-l. This is the source of a document called A LittrateImplementation in the Artifacts System of the Game of Life. To view this document on line.you'll need to start a job server (see the next section), then issue the M-x derive-fromcommand, giving the artifact Life and derivative kind latex-directory as arguments.When derivation has completed successfully, use the M-x preview and/or M-x hardcopycommands to preview or print the document. To try the example program that it describes,issue derive-from again, with artifact Life-C and kind Unix-program. The M-x execute3 and M-x dbx commands allow you to run it, once derivation is complete.

3 C.3 Artifacts System Administration

E-L includes a number of commands for querying and altering the state of associated pro-cesses, such as the lock server and the job servers that manage derivations. Among the mostuseful are start-job-server, stop-job-server, show-locks, grab-locks, start-lock-server, stop-lock-server, and ping. Use M-x describe-function within E-L to see theon-line documentation of any of these commands.

C-7I

Users' ManualIAll of the above commands can also be issued outside E-L, i.e., directly from a shell, using

the -do argument to e-l. For example, the shell-level equivalent of the M-x show-lockscommand with option -p would be

$ e-l -do e-l-show-locks -p

Instead of starting an E-L session, this prints a summary of pending lock requests. In general,the appearance of -do as the first argument of e-l causes it to set environment variables,including PATH, appropriately for starting E-L, but then evaluate its remaining argumentsas a shell command line instead of starting a session. The file named e-l-show-locksimplements the M-x show-locks function of E-L, and since e-1 -do causes it to be foundon a search through $PATH, the above shell command behaves like the corresponding M-xshow-locks would in a session.

Incidentally, another very useful show-locks option is -s, which gives the status of allE-L-related processes (on all hosts) known to the lock server. Information about the lockserver itself is obtained with the -i option.

CA.4 Obtaining Assistance

If you have problems, please contact, Glenn Holloway (glennosoi. corn) at Software Options(617-497-5054). There is also a mailbox for bug reports about E-L: e-l-bugs'Dsoi. corn. Weencourage you to send problem reports or questions to that address to ensure the fastest

3 response.

IIIIIIII

C-8

I

111 Index

*merge*, 4-6 M-c, 3-1S~ M-C-s, 4-4

abandon-draft, 4-5 M-D, 4-2

abandoned draft, 5-4 M-d, 4-2

abort-job, 6-1, 6-1 M-n, 2-4activation server, 6-1 M-s, 4-4alarm-clock (plex), 6-1 M-x, 4-3almost out-of-date, 4-4 u, 4-6append-artifact-to-draft, 4-2 x, 3-1artifact arguments, 4-1 in E-L commands, 2-1

artifacts, 1-1 caption (kind), 3-2, A-1artifacts (plex), 4-2, 4-3, 5-2-5-4, 5-6, change-active-user, 5-7

5-7, 6-1, B-2 commit-draft-and-references, 4-4

I bad (kind), 4-3, 4-5, 6-1 commit-draft-and-references-and-

bibliography, 3-2 referencers,

5 bibliography (kind), 3-3 4-4

bibtex-log, 3-3 commit-one-draft, 2-2, 3-1

buffer-documentation, 5-2 committed, 1-2configuration, 1-2

C-1, 5-3 copy-as-kill, 3-1, 4-1

C-u, 2-2, 4-3; 4-4, 4-6, 5-1 create-draft, 2-1, 4-2

C-x C-c, 2-1 create-draft-and-reference, 3-1

C-z creator (universal attribute), 5-2-5-4, 5-7<, 4-6 delete-artifact-and-references, 4-2

?, 5-2 delete-artifacts-in-region, 4-2

"-, 2-3, 4-6 delete-derivative, 4-3

I C-a, 4-5 delete-draft, 4-4, 6-2

C-c, 2-1 delete-future-jobs, 5-6

C-d, 4-2 delete-host, 5-7

C-e, 2-4 delete-notice, 2-4

C-h, 4-8 delete-one-artifact, 4-2SC-i, 5-1 delete-user, 5-7

C-n, 2-4 derivative, 1-2

C-o, 5-1 derive-from, 4-3

C-s, 2-2 diff, 4-6C-v 5-1 diff-artifacts, 4-6, 4-6C-x, 4-2 diff-artifacts-recursively, 4-6

d, 4-3 dilf-buffers, 4-6, 4-6e, 4-5 display-notice, 2-4M- , 2-3 draft, 1-2, 2-1

I

Users' ManualIdraft arguments, 4-1 latex-log, 2-3, 2-4, 3-3, 3-4drafts (plex), 4-5, 5-4, 6-2 latex-log (kind), 3-4dvi-fiile, 2-3, 3-4 latex-piece (type), 3-1-3-3

latex-root (type), 2-1, 2-2, 2-4, 3-1-3-6,Se-l-lock-server, C-5 4-3, A-i, A-2

edit-artifact, 2-4, 4-2 latex-summary-file, 3-3

electric menu, 5-2 lock server, 6-1

error, 4-5

errorlatex-directory (kind), 4-3, 4-5 M-], 5-4examine-artifact, 4-2 M-C-I, 5-4examine-derivative, 4-3, 4-3 makeindex-log, 3-3examine-problems, 2-4, 3-4, 4-3, 4-5 manuscript (kind), 3-2, 3-3, 3-6, A-i, A-2

filter, 1-3 message server, 6-1

find-missing-draft, 6-2 name (universal attribute), 5-2-5-4find-successor-draft, 4-5 navigation, 4-1follow-link, 2-3, 3-4, 4-5, 4-6 new-host, 5-7follow-link-reverse, 2-3 new-user, 5-7format, 1-4 next-diff-button-pair, 4-63 future (plex), 5-5, 5-6 normal draft, 5-4

note (type), 4-8, B-1goodbye-hostport, 6-2, 6-2 notice, 2-33 gnotices (plex), 2-4, 5-7

hardcopy, 2-2, 3-4 opportunistic scheduling, 1-1hardcopy-command, 3-4 opportnite d 4-1highlight-region, 4-8 out-of-date, 4-4hostport, 6-i past (plex), 5-5, 5-6, 6-1hosts (plex), 5-7 ping, C-7

index, 3-2 plex, 1-3

insert-artifact-into-draft, 3-1 plexesinsert-draft-into-draft, 3-1 alarm-clock, 6-1

artifacts, 4-2, 4-3, 5-2-5-4, 5-6, 5-7,

job server, 5-5, 6-1 6-1, B-2

job-done-notice, 2-3, 5-5 drafts, 4-5, 5-4, 6-2future, 5-5, 5-6

kinds, 1-2 hosts, 5-7bad, 4-3, 4-5, 6-1 notices, 2-4, 5-7bibliography, 3-3 past, 5-5, 5-6, 6-1caption, 3-2, A-i plexes, 5-1

errorlatex-directory, 4-3, 4-5 present, 5-5, 5-6, 6-1latex-log, 3-4 schedule, 5-6manuscript, 3-2, 3-3, 3-6, A-1, A-2 users, 5-7

latex-aux, 2-3, 3-4 plexes (plex), 5-1

latex-bib (type), 3-2, 3-3 pop-to-artifact, 4-2

2I

IUsers' ManualI

postscript (type), 3-6, 3-7 latex-root, 2-1, 2-2, 2-4, 3-1-3-6,present (plex), 5-5, 5-6, 6-1 4-3, A-1, A-2preview, 2-2, 3-3 note, 4-8, B-1preview-command, 3-4 postscript, 3-6, 3-7previous-diff-button-pair, 4-6 unix-program, A-2printbibliography, 3-3 unbutton,4-6printindex, 3-2 unbutto, 4Sps-file, 2-3, 3-nose, -ps-preview, 2-2, 3-4 universal attributes, 5-2ps-preview-command, 3-4 creator, 5-2-5-4, 5-7S3-name,

5-2-5-4re-search-artifacts-recursively,4-7 tImestamp, 5-2-5-4, 5-6re-search-artifacts-recursively- type, 5-2-5-4

continue, up-to-date, 5-2-5-4

4-7 unix-program (type), A-2read-archive, 4-3 up-to-date, 1-2reference, 1-2 up-to-date (universal attribute), 5-2-5-4ref ilter, 5-1, 5-3 users (plex), 5-7reformat, 5-1 utility server, 6-1regular expressions, 5-2rename-draft, 4-4 version, 1-1

revert-buffer, 4-5 view-doomed-artifacts, B-2view-plex, 5-1, 5-3

schedule (plex), 5-6 write-archive,4-3scheduling, 4-4server, 6-1set-diff-button-colors, 4-6set-diff-reference-colors, 4-6show-locks, 6-2, C-7start-job-server, 6-1, C-7start-lock-server, C-7starting draft, 5-4stop-job-server, 6-1, C-73 stop-lock-server, C-7system draft, 5-4

takeover-draft, 4-5, 6-2timestamp (universal attribute), 5-2-5-4,

5-63 type, 1-1type (universal attribute), 5-2-5-4types

latex-bib, 3-2, 3-3latex-piece, 3-1-3-3I

I