MANUAL

Chapter 1: Do not read this manual


Introduction

Didn't you read the chapter title? Do not read this manual!

You're not the kind to follow directions, are you?

Well, that's okay. The primary goal of Elves is to be so easy to use that you won't need any directions. In fact, I hightly recommend you try running, and talking to the Elves before you read any documentation. If you have any problems understanding what they say to you, or if they have any problems understanding what you say to them, please describe what happened in an email to James Holton. Elves is, after all, an interface between you and your programs, so any communication problems you have using Elves constitute a bug in the Elves interface. Please report bugs to James Holton, he will teach the Elves how to understand you.


Elves Philosophy

The Elves were founded on the principle that made the internet possible: "Be strict about what you send, and forgiving about what you recieve." Elves are the result of the "discovery" that ease of use is not just a luxury in x-ray crystallography, but vital for the correct, systematic, and rapid solution of macromolecular crystal structures.

Elves accept an unprecedentedly wide range of input from almost every possible source. Most common x-ray data file formats are supported, scripts for CCP4 programs can be read directly, or even plain-old English sentences and text files can be used as input to Elves. The "strict" part comes when Elves check with you about what they believe you want them to do. They will write a short, English paragraph about the procedure they intend to execute, and ask you for your approval. This "conversational user interface" was developed to acheive the absolute minimum number of keystrokes input by the user. This minimizes mistakes because human beings are much better at recognizing incorrect information that is presented to them than they are in conceiving and correctly entering all the information that x-ray data processing programs need.

Elves lack a graphical user interface, but, remarkably, they do not need one. GUIs still, unfortunately, require users to come up with all the correct parameter values for their experiment, and, in most cases, need to be "babysat", tying up a terminal while the program is running. Even the best GUIs still require a certain amount of training to learn how to use, and they are still not portable from platform-to-platform. The only "interface" that requires no training, but is flexible enough to describe any x-ray experiment is the user's native language (usually English). A great deal of effort has been put into "porting" English, as an interface in the context of x-ray crystallography into Elves. In the future, Elves may be made to understand spoken English as well.

Elves are also intended to be as widely available as possible. For this reason, they were implementted entirely in csh, which, although an incredibly slow "language" is still (along with its big brother: tcsh) the most popular login shell used by x-ray crystallographers. The slow speed of csh has almost no impact on the speed of Elves, since they spend more than 99% of their time running third-party, compiled binary programs (which are mostly written in FORTRAN, and can't get much faster). The advantage of being written in csh is that Elves are trans-portable to, conceivably, every unix platform. without even the need for a compiler, as a single, universal text file. The Elves "source code" is, therefore, openly readable. Also, because the Elves script is self-configuring, there is no set-up required to use Elves. The script is simply run with plain-English instructions on the command line.

Also for reasons of availability, the third-party software required by Elves are, themselves, widely available and free of charge to academic and not-for-profit users. CCP4 and mosflm are the only programs required to be installed for Elves to work. CCP4 can be difficult for a novice user to configure and compile, but is such a staple of x-ray crystallographers everywhere, that it is, hopefully, not too much to ask of Elves users to have a working copy of CCP4. Elves can also take advantage of shelx, wARP, and the "not free" programs denzo, and solve, but they do not need them.


Elves Credo: The rules that Elves live by

  1. Do not waste the user's time.
  2. Don't ask stupid questions.
  3. Don't babble.
  4. Never give up.
  5. When in doubt, guess.
  6. Bring your own lunch
  7. Don't say you're done unless you really are.


Back to the Elves Manual Table of Contents.


This page is not finished. It will never be finished, and neither will yours. Admit it.

James Holton <jamesh@ucxray.berkeley.edu>