Return to README.txt CVS log

Up to [LON-CAPA] / loncom / html / adm / jmol

- Jmol version 14.2.4

    1: ==============================================================================
    2: ===                                  Jmol                                  ===
    3: ==============================================================================
    4:       Jmol: an open-source Java viewer for chemical structures in 3D, 
    5:      with features for chemicals, crystals, materials and biomolecules.
    6: ==============================================================================
    7: 
    8: Jmol is an open-source molecule viewer and editor written in Java.
    9: 
   10: Full information is available at http://www.jmol.org/
   11: 
   12: Usage questions and comments should be posted to jmol-users@lists.sourceforge.net
   13: 
   14: Development questions, suggestions and comments should be posted
   15: to jmol-developers@lists.sf.net
   16: 
   17: 
   18: List of files included:
   19: -------------------
   20: 
   21: 
   22: 1 == Files with information ==
   23: 
   24: 1.1 === README.txt ===
   25: This file.
   26: 
   27: 1.2 === LEAME.txt ===
   28: The Spanish version of README.txt
   29: 
   30: 1.3 === COPYRIGHT.txt ===
   31: The copyright explanations regarding Jmol and its 3rd-party components.
   32: 
   33: 1.4 === LICENSE.txt ===
   34: The GNU Lesser General Public License, under which Jmol is released.
   35: 
   36: 1.5 === CHANGES.txt ===
   37: A list with a history of the feature additions in each version of Jmol.
   38: 
   39: 1.6 === README-CHEMDOODLE.txt ===
   40: Instructions about using the ChemDoodle plug-in together with Jmol applets, 
   41: and about the license for ChemDoodle (which is different from the Jmol license).
   42: 
   43: 
   44: 2 == Batch and shell files ==
   45: These can be used to start Jmol application from a command line and, 
   46: particularly, to impose a certain combination of parameters 
   47: (see http://wiki.jmol.org/index.php/Jmol_Application#Command_line_options).
   48: 
   49: 2.1 === jmol ===
   50: ???? (Some kind of batch file)
   51: 
   52: 2.2 === jmol.bat ===
   53: A batch file to start Jmol application under Windows.
   54: 
   55: 2.3 === jmol.mac ===
   56: ??? (Some kind of batch file, for the MacOS)
   57: 
   58: 2.4 === jmol.sh ===
   59: A shell script to start Jmol application under Unix-like systems, like Linux, 
   60: BSD, Solaris and Cygwin for Windows.
   61: 
   62: 
   63: 3 == Files of Jmol application ==
   64: This is used as a standalone program.
   65: 
   66: 3.1 === Jmol.jar ===
   67: The application executable file (a program written in Java). This works as any 
   68: other program: opens in its own window, can be resized or minimized, admits 
   69: drag-and-drop of files over it, has a top menu bar, can open and save files, 
   70: etc. It can be open from the command line (particulary, using the shell or batch
   71: files described above), but if Java is properly configured in your system, it's
   72: usually enough to double-click on the file 
   73: (see http://wiki.jmol.org/index.php/Jmol_Application#Starting_Jmol_Application 
   74: for more details).
   75: 
   76: 3.2 === JmolData.jar ===
   77: This is a slimmed down version of Jmol.jar that lacks all visualization 
   78: capabilities. So, it betrays the whole (classic) concept of what Jmol is, but 
   79: with JmolData and some clever scripting you can get just about any information 
   80: you want out of a model and output it any way you want.
   81: 
   82: It operates only from the command line, designed for extracting data from a 
   83: model or set of models. You are limited to commands that don't have to do with 
   84: visualization: there are bonds but no "sticks", atoms but no "dots", helices but
   85: no "cartoons".
   86: 
   87: 
   88: 4 == Files of Jmol applet ==
   89: These are used inside web pages, and include:
   90:   Applet files  |  Core Javascript libraries  |  Optional Javascript libraries
   91: 
   92: 4.1 === Applet files ===
   93: 
   94: 4.1.1 ==== JmolApplet0.jar, JmolApplet0(severalSuffixes).jar ====
   95: The applet, i.e. a version of the program that will only run when embedded in 
   96: a web page.
   97: 
   98: The applet is divided up into several pieces according to their function, so 
   99: that if a page does not require a component, that component is not downloaded 
  100: from the server. 
  101: It is still recommended that you put all JmolApplet0*.jar files on your server 
  102: even if your page does not use the capabilities provided by some of the files, 
  103: because the pop-up menu and Jmol console both allow users to access parts of 
  104: Jmol you might not have considered.
  105: 
  106: This split version is the one that will be used by default if you use Jmol.js 
  107: (which is the recommended method).
  108: For that, use the simplest form of jmolInitialize(), just indicating the 
  109: directory or folder containing the set of jar files:
  110:  jmolInitialize("directory-containing-jar-files")
  111: for example,
  112:  jmolInitialize(".")  
  113:      (if jar files are in the same folder as the web page)
  114:  jmolInitialize("../jmol") 
  115:      (if jar files are in a parallel folder, named 'jmol')
  116: 
  117: 4.1.2 ==== JmolAppletSigned0.jar, JmolAppletSigned0(severalSuffixes).jar ====
  118: An equivalent version of the applet, but this is a "signed" applet (a term in 
  119: Java security language). This means it must be authorized by the web 
  120: page visitor for it to run, but then it will have less security restrictions for
  121:  file access. For example, it can access files on any part of the user's hard 
  122:  disk or from any other web server.
  123: 
  124: Typically users get a message asking if they want to accept the "certificate" or
  125:  if they "trust" the applet (''see notes below''). JmolAppletSigned.jar should 
  126:  be used with this in mind. Other than reading files, Jmol does not currently 
  127:  use other capabilities of signed applets, such as accessing the system 
  128:  clipboard or writing files. Use only if you know what you are doing and have 
  129:  considered the security issues.
  130: 
  131: To use this with Jmol.js, use the form:
  132:  jmolInitialize("directory-containing-jar-files", true)
  133: or
  134:  jmolInitialize("directory-containing-jar-files", "JmolAppletSigned0.jar")
  135: 
  136: Notes:
  137: * The security feature requesting to trust the applet may not always be enabled 
  138:   on users' systems. 
  139: * The message requesting permission will be displayed for each of the 14 (or 
  140:   more) loadable files. 
  141: * The user may have the option to trust the applet permanently and so avoid 
  142:   having to give permission every time (s)he visits a page that uses Jmol.
  143: 
  144: 4.1.3 ==== JmolApplet.jar ====
  145: This is an all-in-one or monolithic file, kept mainly for compatibility with old
  146: pages that call it explicitly. 
  147: This single file is equivalent to the whole set of JmolApplet0*.jar files, 
  148: explained above.
  149: The recommended procedure is not to use this monolithic file, but the split 
  150: version (JmolApplet0.jar etc.). In particular, Jmol.js uses the split version 
  151: by default.
  152: 
  153: You may wish to use this if you want to keep your website simple or you just 
  154: want to upload a single jar file whenever new versions are released. 
  155: However, this will load Jmol slower than the split versions (described above), 
  156: as all the modules (adding up to 2.4 MB), needed or not, must get loaded onto a 
  157: user's machine before any structure is displayed.
  158: 
  159: To invoke JmolApplet.jar from Jmol.js, either:
  160: 
  161: a) put it in the directory containing the HTML page requiring it and do not use 
  162:    jmolInitialize(), 
  163: 
  164: or 
  165: 
  166: b) identify it explicitly in jmolInitialize(), for example:
  167:  jmolInitialize("directory-containing-jar-files", "JmolApplet.jar")
  168: 
  169: 4.1.4 ==== JmolAppletSigned.jar ====
  170: An equivalent version of the monolithic applet, but this is a "signed" applet 
  171: (a term in Java security language). This means it must be authorized by the web 
  172: page visitor for it to run, but then it will have less security restrictions for
  173:  file access. For example, it can access files on any part of the user's hard 
  174:  disk or from any other web server.
  175: 
  176: Typically users get a message asking if they want to accept the "certificate" or
  177: if they "trust" the applet, but this security feature is not always enabled.
  178: JmolAppletSigned.jar should be used with this in mind. Other than reading files,
  179: Jmol does not currently utilize other capabilities of signed applets, such as 
  180: accessing the System clipboard or writing files. Use only if you know what you 
  181: are doing and have considered the security issues.
  182: 
  183: To invoke JmolAppletSigned.jar from Jmol.js, use:
  184:  jmolInitialize("directory-containing-jar-files", "JmolAppletSigned.jar")
  185: 
  186: 4.1.5 ==== Notes ====
  187: # Given the descriptions, you will realize that the distribution package 
  188:   contains 4 full copies of the applet (signed or unsigned, split or not).
  189: 
  190:   
  191: 4.2 === Core Javascript libraries ===  
  192: 
  193: 4.2.1 ==== Jmol.js ====
  194: The classic library, written in JavaScript language, that assists in the 
  195: programming of web pages that use Jmol applet, without the need to know and 
  196: write detailed JmolApplet code.
  197: 
  198: This library uses by default the split version of the applet (unsigned or 
  199: signed).
  200: 
  201: Fully documented at http://jmol.org/jslibrary/
  202: 
  203: Jmol.js is phased out in Jmol v13, in favour of the object-oriented method 
  204: and set of .js files (described next).
  205: 
  206: 4.2.2 ==== JmolApplet.js ====
  207: Creates the object for a Jmol applet.
  208:  
  209: 4.2.3 ==== JmolCore.js ====
  210: Contains functions that make the Jmol applets work but are not to be used by 
  211: the webpage author (private functions). 
  212: 
  213: 4.2.4 ==== JmolControls.js ====
  214: Support for user-interface controls like buttons, links, checkboxes, etc. 
  215: 
  216: 4.2.5 ==== JmolApi.js ====
  217: Contains the Application Programming Interface, that is, functions that may be 
  218: used by the webpage author to interface with the Jmol applets.
  219: 
  220: 
  221: 4.3 === Optional Javascript libraries ===
  222: 
  223: 4.3.1 ==== JmolCD.js ====
  224: The ChemDoodle extension: provides the means for using ChemDoodle Web Components 
  225: (that uses JavaScript + HTML5 canvas or WebGL) instead of the
  226: Jmol applets, for systems where Java is not available.
  227: 
  228: 4.3.2 ==== JmolGLmol.js ====
  229: The GLmol extension: provides the means for using GLmol (that uses WebGL + 
  230: JavaScript) instead of the Jmol applets, for systems where Java is not available.
  231: 
  232: 4.3.3 ==== JmolJME.js ====
  233: Provides the means for adding a JME applet in the webpage (drawing of 2D chemical 
  234: formulas) and communicate with Jmol applets.
  235: 
  236: 4.3.4 ==== JmolJSV.js ====
  237: Provides the means for adding a JSpecView applet (viewer for spectral data) in 
  238: the webpage and communicate with Jmol applets.
  239: 
  240: 
  241: 5 == Accessory apps and applets ==
  242: 
  243: 5.1 === ChimeToJmol.jar ===
  244: Undocumented and experimental.
  245: An application to convert Chime-using html pages into pages with JmolApplets. 
  246: 
  247: 5.2 === JSpecViewApplet, JSpecViewAppletSigned ===
  248: Unsigned and signed versions of the JSpecView applet, a viewer for spectral data 
  249: that may be intercommunicated with Jmol applets. 
  250: (See supporting .js file above) 
  251: 
  252: 5.3 === JmolSmilesApplet.jar ===
  253: This is currently not included in the distribution, but may be obtained from the
  254: development site.
  255: 
  256: This is a lightweight applet, with no visible interface, that allows to check 
  257: SMILES strings. This is particularly useful for comparison of stereochemistry, 
  258: for example from structures drawn using the JME applet.
  259: 
  260: The same functionality is included in the regular JmolApplet.