Instructions for authoring molecular structure tutorials in the Jmol Tutorial-Authoring Template (JTAT). Introduction & Overview What skills do you need to author a tutorial in JTAT? Organization of files and folders in JTAT.

JTAT, the Jmol Tutorial-Authoring Template, facilitates authoring tutorials about three-dimensional (3D) macromolecular structures. JTAT tutorials operate in standard web browsers, such as Firefox, Internet Explorer, and Safari. The molecules can be rotated and zoomed with the mouse. A tutorial consists of a series of molecular views designed by the author, each with descriptions and color keys, and may be organized into chapters. For an example, see the JTAT Demonstration Tutorial.

JTAT displays molecules in a web browser, using the Jmol java applet, a free, open-source molecular display program that requires no installation. JTAT tutorials work from disk files (off line) or from servers (on line). They work in Windows (in Internet Explorer, Mozilla Firefox), in Mac OS X (in Safari or Firefox), and in linux (in Firefox).

JTAT enables authors of macromolecular structure tutorials to concentrate on the scientific content, rather than on web page programming. Authors choose molecules, design molecular views, and explain them. JTAT provides a template or "shell" that sets up the molecular display, a scrolling panel of view buttons and descriptions, ready-made style sheets, and many other amenities that improve usability and make your tutorials look classy. Typically, most molecular views show a single molecule, but JTAT can show two, three, or four molecules for side by side comparisons. The best way to see JTAT's range of capabilities is to run through the JTAT Demonstration Tutorial.

In brief, after getting familiar with these instructions, you download JTAT. It includes an empty template, which is a working tutorial, except without any molecular content. You view the template in your favorite web browser. Then, following the instructions below, you insert molecular content into the template. The content consists primarily of customized molecular views, with descriptions of the views, which include color keys: text colored to match the colors of the molecule. After each change to your tutorial's content, you reload it in the browser to see the change.

Biochemistry. We assume that you know about, or are learning about, a molecular structure -- and that you wish to present a series of informative views of this molecule, explaining its salient structural features, and how they support its function.

Text Editing. First, you'll need to be able to edit plain text files, using a text editing program. Plain text editors include Notepad, a simple but adequate text editor that comes with Windows, and BBEdit, a superb and sophisticated commercial program for Macs. You can also use word processors (such as Wordpad in Windows, Textedit on Macs, or Microsoft Word) but then you must be careful to save the file as plain ("ASCII" or "DOS") text. If you inadvertantly save it as a document file, it won't work -- but then you can simply re-save it as plain text.

You'll need to edit plain text files that contain the text descriptions for your molecular views, and the Jmol script (.spt) files that specify those views.

Windows Notepad: Start, (All) Programs, Accessories, Notepad.

Mac OSX: BBEdit is the supreme Mac text editor. 30 day free demo from barebonessoftware.com

HTML (HyperText Markup Language). Second, you'll need to be familiar with just a little HTML, in order to color your text to match colors in the molecular view, and to insert links and images into your tutorials. Quick references are provided for HTML and coloring text.

Jmol scripting. Third, you'll need some familiarity with the Jmol molecular view command scripting language. This is a superset of the RasMol and Chime command languages. Command scripts, or scripts for short, will be saved in plain text files whose names end ".spt".

It is very important that you understand the organization of files and folders within JTAT. This will enable you to avoid inadvertently breaking JTAT, and to place your new tutorials and alterations correctly. It will greatly facilitate moving your tutorials to new versions of JTAT, should new versions become available.

The jtat folder. JTAT is contained in a folder (directory) named jtat. When you download JTAT, the main folder may include its release date in its name. For example, jtat_2008_02_15 would signify a release date of February (02) 15, 2008. You can leave the release date in the folder name, or rename it to simply jtat if you prefer. However, you may well end up with several versions of JTAT side by side (see next paragraph), in which case leaving the release dates of each in their folder names will be helpful. The release date of each version of JTAT is displayed at the bottom of the control panel in every tutorial. Below, we'll refer to the folder generically as jtat.

JTAT versions. You can have multiple versions of JTAT side by side, as long as the main jtat folder has a distinct name for each version. In some cases, it might be simpler to leave a well-functioning tutorial in an older version, particularly when it would need extensive revisions to make it compatible with a newer version of JTAT.

Tutorial folders. Multiple tutorials can be contained in jtat, each in its own folder. For example, the JTAT Demonstration Tutorial is in a folder named jtatdemo. Were you to create a new tutorial on acetylcholinesterase, an appropriate folder name for it would be acetylcholinesterase. This folder will contain all text, molecular view scripts, images, and other content that is specific to this tutorial.

All tutorials in jtat share the JTAT shell, that is, the code that sets up and operates the tutorial. The folders common to all tutorials are named as follows:

• jtat/_cssutil contains cascading style sheets (*.css).
• jtat/_docs contains the JTAT documentation (mostlyh *.htm).
• jtat/_drums contains scripts (*.spt) for the DRuMS Standard Color Schemes, as well as drums.css for coloring matching text color keys.
• jtat/_jsutil contains javascript (*.js).
• jtat/_imgutil contains images (*.jpg, *.gif, *.png).
• jtat/_sptutil contains Jmol command scripts (*.spt).


• jtat/jtatdemo contains the JTAT Demonstration Tutorial.

Each tutorial that you create will add another folder to the above list.

In addition to the above folders, the following are the only files that should be present in jtat:

• jtat/index.htm is where you start your browser. Typically, this file would contain links to each of your tutorials, and a link to the JTAT Documentation (jtat/_docs/index.htm).
• jtat/Jmol.js is javascript that supports the Jmol applet. The version of Jmol.js must match the version of the applet. DO NOT EDIT THIS FILE.
• jtat/jmolApplet0.jar and jmolApplet0_*.jar files (where * represents various words) make up the Jmol applet. DO NOT TOUCH THESE FILES.

JTAT files you can edit. For the most part, you should not alter the jtat files or folders that are outside your tutorial's folder. There are a few exceptions listed below. However, most authors will never need to touch any of these files.

• jtat/index.htm can be edited to have any style and contents that you like. Typically, this file would contain links to each of your tutorials, and a link to the JTAT Documentation (jtat/_docs/index.htm).
• jtat/config.js, jtat/config2.js may be edited judiciously to change settings that will affect all tutorials in the current jtat folder. If you wish to change one of these settings in one or a subset of the tutorials in the current jtat folder, you should change or add these settings in the relevant file(s) in jtat/tutorialName/js4all.
• jtat/_cssutil files may be edited judiciously to change the styles of elements in all the tutorials in the current jtat folder. Styles specific to one or a subset of the tutorials belong in jtat/tutorialName/css4all.
• jtat/_imgutil is a place to add any images that you plan to use in more than one of your tutorials. Images specific to one tutorial belong in jtat/tutorialName/imgs4all.
• jtat/_sptutil is a place to add any Jmol command scripts that you plan to use more than one of your tutorials. Scripts specific to one tutorial belong in jtat/tutorialName/spts4all.

Files and folders making up a tutorial. To create a new tutorial in a folder named acetylcholinesterase, copy (duplicate) the folder named template, including all the folders and files it contains, and then simply rename Copy of template to, for example, acetylcholinesterase. Then you can begin adding scientific content. Every tutorial folder must contain the following:

• jtat/tutorialname/chapter01 One folder for each chapter in this tutorial.

Lower case for all filenames! Nearly all file and folder names in JTAT are entirely in lower case letters. (The exceptions are Jmol.js and jmolApplet.jar.) We strongly recommend that you use only lower case letters (a, b, c, ...) and no upper case letters (NOT A, B, C, ...) in file and folder names. Case mismatches in file or folder references are harmless in Windows and Macs, but when your tutorial is moved to a server, they can be tedious to fix!