Requirements for Publishing RasMol Scripts

Eric Martz, April 1997

Thank you for considering to make your RasMol script available from the RasMol Classic Main Page. I am enthusiastic about making more scripts available. I'm sure you recognize, though, that a sloppily done product will result in frustration to hundreds or thousands of people who attempt to use your script, and to me as I receive email from them. Therefore publishing a script satisfactorily requires more effort than just getting it to run on your own computer.

RasMol scripts to be made publically available via the RasMol Classic Main Page must meet the following requirements. I hope these do not deter you from publishing your script -- but failure to meet these requirements inevitably leads to dissatisfaction to all involved.

1. RasMol or Chime? The RasMol "movie" script is, in my opinion, an obsolete form of presentation. This is only because, beginning in early 1996, Chime offered a much better mechanism for chemical structure presentations. Consider porting your script to Chime (see www.umass.edu/microbio/chime for reasons and help). We recognize that creating a presentation in Chime is considerably more effort that in RasMol, since you must provide HTML as well as chemical (RasMol) scripts, and perhaps javascript as well. RasMol scripts will still be accepted, therefore, because they are far better than nothing if you do not have the time/resources to port to Chime.

2. Server. It is best if the script can be distributed from your own ftp or web server, using a hypertext link to the RasMol Classic Main Page. This avoids having to ask me to change the file on my server when updates or bug fixes occur. However, if no server is available to you, the script can be delivered from the UMass server. If you request that the file be changed after it is installed on the UMass server, there may be (despite my best efforts) months of delay before I can get around to doing it due to high demand for this sort of thing. Therefore, the script should be in 'final' form before asking me to put it on the UMass server.

3. Multi-platform performance. The script should run equally well on Windows 3.1(DOS), Windows 95/NT, Macintosh PPC, and unix systems. This requires attention to the following. All 'script' and 'load' filenames must be quoted, and all filenames must be DOS compatible, e.g. 8 character max plus 3 characters extension after a period. Contrary to other suggestions including some on my own web site (which need to be updated) all script file extensions must be '.spt' (for web MIME delivery reasons in the future, e.g. with Chime). All filenames must be named and referred to in scripts in all lower case (else they fail to work in unix or DOS). (Filenames may be shown in upper case by DOS -- just make sure you refer to them in lower case in your scripts.) Here are examples:

Good:

Unacceptable:

We of course recognize that not all scripts on the server presently conform to these rules as we have learned many of the rules subsequently. We are working to change that but time and resources are limited.

We find a grep tool very useful during script development. For example, under DOS, the command 'sgrep -i script *.spt' lists all script commands in all script files. This facilitates checking for quotes. Sgrep is available as part of a package called DOSNIX; a similar fgrep is part of a package called DANIX. These can be obtained from any shareware web site (e.g. www.filepile.com, www.shareware.com). Another handy tool is WC (word count), which counts lines, words, and characters in multiple files. With WC you can easily find out how many lines are in your script files if you are curious. WC's come with DOSNIX and DANIX but a nicer WC comes with UZNIX (it labels the columns).

4. Use instructions. We strongly recommend that you include the files 00sptdoc.htm and macsig.htm (as is) in your script, which provide generic use instructions, and the file 0sptspec.htm, whose contents must be customized to give specific details about your script. These files can be obtained by downloading any recently Martz-authored script. See www.umass.edu/microbio/rasmol/scrip_mz.htm

5. Attribution of sources. Your script must clearly identify the authors, their institutions and email addresses, and any copyright or use limitations imposed on the script. It must also fully credit the references or authors of the structural studies which produced the atomic coordinate files employed.

6. Content. Care must be taken to avoid sloppy or ambiguous descriptions in the legends. Have an unbiased colleague proofread your legends critically for punctuation and clarity. The script must be internally consistent. For example, if the startup screens and/or file 0sptspec.htm say to have exactly 6 lines of legend text showing, then all your legends must make sense in a 6-line display.

7. Script names. Please name your script with 7 or fewer characters plus U (if unpaused) or P (if paused). For example, DNA3P. The top level script file should have the same name as the script, e.g. dna3p.spt.

8. Test! Be sure to test your script carefully, preferably on multiple operating systems. Run it once with a large command line window (20 or so lines visible) so you can watch for "file not found" error messages which tend to scroll by too fast to see when only 6 lines are visible.

9. Packaging. The minimum way to deliver a script is "raw", that is as a group of dozens of separate files, ready to run. All operating systems can download and use such files via ASCII ftp, though it may be slow and inconvenient. Ideally, you can also package your script files in some or all of these ways:

Such packaging greatly speeds downloading, reduces unnecessary loading of the Internet, and makes installation less error-prone. Sorry, we do NOT have the time to package up scripts for you.

*Mac: Before packaging up the files, it would be best if you set their signatures and icon colors. Download dna3p.sea.hqx and use this as an example. There are many good signature management shareware programs; we use FileBuddy.

10. Description for link. Please provide a short paragraph describing the contents of your script. This will go on the RasMol Classic Main Page next to the link(s) to your script so that people can decide whether to download the script.


Feedback to Eric Martz.