openSUSE Build Service

Overview Repositories Revisions Requests Users Attributes Meta

File README_FIRST of Package rasmol

==========================================================================
PLEASE READE THIS DOCUMENT CAREFULLY.  IT CONTAINS IMPORTANT UPDATES TO
THE RASMOL 2.7.3 DOCUMENTATION ON OBTAINING, INSTALLING AND USING RASMOL.
==========================================================================
                        _ R E A D M E . F I R S T
                     R a s M o l   v 2 . 7 . 3 . 1 _ R U
                    Molecular Graphics Visualisation Tool
                             29 December 2006

Based on RasMol 2.6 by Roger Sayle
    Biomolecular Structures Group, Glaxo Wellcome Research & Development,
                        Stevenage, Hertfordshire, UK
           Version 2.6, August 1995, Version 2.6.4, December 1998
                    Copyright (C) Roger Sayle 1992-1999

and Based on Mods by

Author             Version, Date             Copyright

Arne Mueller       RasMol 2.6x1      May 98   (C) Arne Mueller 1998

Gary Grossman and  RasMol 2.5-ucb    Nov 95   (C) UC Regents/ModularCHEM
   Marco Molinaro     RasMol 2.5-ucb    Nov 96       Consortium 1995, 1996

Philippe Valadon   RasTop 1.3        Aug 00   (C) Philippe Valadon 2000

Herbert J.         RasMol 2.7.0      Mar 99   (C) Herbert J. Bernstein
   Bernstein          RasMol 2.7.1      Jun 99       1998-2006
                      RasMol 2.7.1.1    Jan 01
                      RasMol 2.7.2      Aug 00
                      RasMol 2.7.2.1    Apr 01
                      RasMol 2.7.2.1.1  Jan 04
                      RasMol 2.7.3      Feb 05
                      RasMol 2.7.3.1    Apr 06
                      RasMol 2.7.3.1_RU Dec 06

with RasMol 2.7.3 incorporating changes by Clarice Chigbo, Ricky Chachra,
   and Mamoru Yamanishi.  Work on RasMol 2.7.3 supported in part by
   grants DBI-0203064, DBI-0315281 and EF-0312612 from the U.S. National
   Science Foundation and grant DE-FG02-03ER63601 from the U.S. Department
   of Energy.

and Incorporating Translations by

Author                               Item                     Language

Isabel Servan Martinez,              2.6 Manual               Spanish
   Jose Miguel Fernandez Fernandez
   Jose Miguel Fernandez Fernandez      2.7.1 Manual             Spanish
   Fernando Gabriel Ranea               2.7.1 menus and messages Spanish

Jean-Pierre Demailly                 2.7.1 menus and messages French

Giuseppe Martini, Giovanni Paolella, 2.7.1 menus and messages Italian
   A. Davassi, M. Masullo, C. Liotto    2.7.1 help file

G. Pozhvanov                         2.7.3 menus and messages Russian

This Release by
   Herbert J. Bernstein, Bernstein + Sons, P.O. Box 177, Bellport, NY, USA
                        yaya@bernstein-plus-sons.com
                Copyright (C) Herbert J. Bernstein 1998-2006

The original RasMol manual was created by Roger Sayle.  In July 1996,
   Dr. Margaret Wong of the Chemistry Department, Swinburne University
   of Technology, Australia, made extensive revisions to the RasMol 2.5
   manual to accurately reflect the operation of RasMol 2.6.  Eric Martz
   of the University of Massachusetts made further revisions.  In May
   1997, William McClure of Carnegie Mellon University reorganized the
   HTML version of the manual into multiple sections which could be
   downloaded quickly and added use of frames.   Portions of the 2.7.1
   version of the RasMol manual were derived with permission from
   William McClure's version using Roger Sayle's rasmol.doc for
   version 2.6.4 as the primary source. Changes were made in August 2000 for
   RasMol version 2.7.2, January 2001 for RasMol version 2.7.1.1, April 2001
   for RasMol version 2.7.2.1 and February 2005 for RasMol version 2.7.3.

Documentation Last Updated 19 April 2005
            Edited by Herbert J. Bernstein and Frances C. Bernstein

Translations

Thanks to the efforts of Jose Miguel Fernandez Fernandez (Departamento
   de Bioquimica y Biologia Molecular. Universidad de Granada. Espana
   (jmfernan@ugr.es)) a translation of the Manual for Rasmol version
   2.7.1 into Spanish is now available. La traduccion espanola del manual
   de la version de la Dra. Wong revisada por Eric Martz fue realizada
   por Isabel Servan Martinez y Jose Miguel Fernandez Fernandez. La
   actual traduccion del Manual de RasMol 2.7.1 ha sido realizada usando
   como base la anterior de RasMol 2.6 por  Jose Miguel Fernandez
   Fernandez.

Thanks to translations by Fernando Gabriel Ranea in late 2000 and
   early 2001, RasMol is now capable of rendering most menu items and
   messages in Spanish. Jean-Pierre Demailly provided French translations
   of menus and messages in January 2001. Giuseppe Martini and Giovanni
   Paolella with contributions by A. Davassi, M. Masullo and C. Liotto
   provided Italian translation of menus and messages in March 2001.

===========================================================================
          THIS IS A PRELIMINARY RELEASE INVOLVING EXTENSIVE MODIFICATIONS
                           ***** USE WITH CAUTION ******
 ===========================================================================
 
                                 IMPORTANT

This version is based in directly on RasMol version 2.7.2.1.1, on RasMol 
   version 2.7.2, on RasMol version 2.7.1, on RasMol version 2.6_CIF.2, on 
   RasMol version 2.6x1, on RasMol version 2.6.4, and RasMol 2.5-ucb and 2.6-ucb.

Please read the file NOTICE for important notices which apply to this 
   package and for license terms (GPL  or RASLIC).
 ===========================================================================

The source kit for this version of RasMol is available at

http://www.RasMol.org/RasMol_2.7.4_pending/RasMol_2_7_3_1_RU_29Dec06.tar.gz

Binaries releases may include files from external packages covered
  by other licenses.  See

http://www.RasMol.org/external_packages.shtml
 ===========================================================================

RasMol_2_7_3_1_RU is an pre-release of RasMol 2.7.4 incorporating the 
  following modifications:

* Correction to mouse handling to avoid run away rotation in the X-windows 
  versions.    The bug was isolated in careful testing by Niroshan Egodawatte.  
  The proposed  fix is by H. J. Bernstein. This is a revised version of the 
  patch of 15 December 2005,  which had problems with window resizing 
  discovered by Isaac Awuah Asiamah.  See

http://www.RasMol.org/RasMol_2.7.4_pending/mouserun2.patch

* Correction to trailing bits of Z-coordinate when writing out PDB files.  
  The problem was reported by Senn Hans Martin.  The proposed fix is by H. J.
  Bernstein and  was tested by Senn Hans Martin.  See

http://www.RasMol.org/RasMol_2.7.4_pending/ztrl.patch

* Correction to handling of distance monitors for atoms more than 170 
  Angstroms apart.  The problem was reported by Dan Bolster in trying 
  distance monitors to measure viruses.  The proposed fix is by H. J. 
  Bernstein.  See

http://www.RasMol.org/RasMol_2.7.4_pending/distfix.patch

* Release 2.7.3.1.  As part of the development of 2.7.4, the patches
  above and a new patch to update the versions in rasmol.h, etc.  See

http://www.RasMol.org/RasMol_2.7.4_pending/version_2.7.3.1.patch

* Release_2.7.3.1_ru.  The changes to Release 2.7.3.1 to incorporate 
  Russian language messages and menus have been combined with several 
  other changes in one large (1MB) patch, RasMol_2.7.3.1_ru_29Dec06.patch. 
  After applying the patch,  all symlinks should be manually removed, and 
  the new icons raswin.ico, raswin_doc.ico, raswin_scr.ico should be placed 
  in src/mswin.  Finally the new pattern of symlinks should be created 
  from the top level by executing

./.symlinks

A sample script for applying the patches and doing this cleanup is 
  provided.

The changes are as follows:

* Russian language messages and were translated by Gregory A. 
  Pozhvanov (pozhvanov at gmail dot com) of Saint-Petersburg State 
  University.

* An MS windows installer was proposed by G. A. Pozhvanov, and 
  reimplemented on the open source base of NSIS-2.21.

* A unix installer script, rasmol_install.sh, and a matching script 
  to select an appropropriate binary version to run under unix, 
  rasmol_run.sh have been added by H. J. Bernstein

* Language selections have been made "sticky".

* The "About" dialog has been made uniform among platforms and 
  "Register" and "Donate" buttons have been added to the "About" 
  dialog screen and to the menus.

* In response to a bug report from Steve Shaw (shaws at mail 
  dot nih dot gov) at the NIH, two new options have been added for 
  export of VRML images:  "rotate"  and "mirror".

write vrml mirror <filename>

will write a vrml file with all axes mirrored (x -> -x, y -> -y 
  and z -> -z) and

write vrml rotate <filename>

will write a vrml file rotated 180 degrees around the x-axis 
  (x - > x, y -> -y, z-> -z)

* Code from 2003 by Vencislav Stanev to export Raster3D scripts 
  from RasMol was  integrated with this release, and support for 
  ribbons was added.

* In order to support builds on newer 64-bit unix systems, Nikolay 
  Darakev added code to the build scripts to check the length of long 
  integers and to adjust the builds.

See

http://www.RasMol.org/RasMol_2.7.4_pending/RasMol_2_7_3_1_RU_29Dec06.patch
  http://www.RasMol.org/RasMol_2.7.4_pending/patch_RasMol_2.7.3_to_RasMol_2.7.3.1_ru_29Dec06.sh
  http://www.RasMol.org/RasMol_2.7.4_pending/raswin.ico
  http://www.RasMol.org/RasMol_2.7.4_pending/raswin_doc.ico
  http://www.RasMol.org/RasMol_2.7.4_pending/raswin_src.ico

===========================================================================
   CHANGES TO THE RASMOL 2.7.3 INSTALL INSTRUCTIONS for RASMOL 2.7.3.1_RU
 ===========================================================================

INSTALLATION FROM A BINARY KIT:

For MS Windows, download

http://www.RasMol.org/RasWin_2_7_3_1_RU_Install.exe

to your desktop and run it.

For a unix system (including Mac OS X), if there is a binary kit for your
 system, download the tarball, unpack it and check for the file
 _README_FIRST (the version of this file for that system) and follow
 the instructions given there.  In general, all that is required
 is:

1.  If planning a system install, do the following steps
    as root or using sudo.

2.  Either unset RASMOLPATH or check that it is set to
    the appropriate path for your rasmol installtion.  For most
    systems, it is best to unset RASMOLPATH.  This is especially
    important if you have installed CCP4, which sets RASMOLPATH
    to a value appropriate to the version of rasmol in the
    CCP4 kit.

3.  If you wish to force installation of the font kits that come
    with rasmol, you should also unset DISPLAY before doing the
    install, so that rasmol_install.sh will be unable to find
    any existing fonts.

4.  If your system does not provide a Bourne-style shell
    as /bin/sh, change the first line of rasmol_install.sh
    to refer to an appropriate Bourne-style shell, e.g.
         #/usr/local/bin/bash
    and add the option --shell=shellpath (e.g.
    --shell=/usr/local/bin/bash) to any invocation of
    rasmol_install.sh

5.  If you are doing a system install, add the option --system
    to any invocation of rasmol_install.sh

6.  Invoke ./rasmol_install.sh with the options noted above.
    For an ordinary user install
        ./rasmol_install.sh
    should suffice.  When the script runs it will ask for
    confirmation of the chosen installation directories.
    To perform the installation, you must answer "y" or "Y".
    The default is no.
    
 INSTALLATION FROM SOURCE:

All versions need unix style utilities to work with the source.  Builds
 for MS Windows and Mac Classic are done with CodeWarrior.  Builds in
 a unix environment (including Mac OS X) need xmkmf and gcc.  Builds
 with visual studio are not supported at this time.

The source of RasMol 2.7.3.1_RU can be downloaded as a complete tarball
 from

http://www.RasMol.org/RasMol_2.7.4_pending/RasMol_2_7_3_1_RU_29Dec06.tar.gz

This tarball should be placed in the directory in which the build is to be
 done and unpacked with the command:

gunzip < RasMol_2_7_3_1_RU_29Dec06.tar.gz | tar xvf -

(Alternatively, if you have been making your own modifications to RasMol
 2.7.3, you may wish to start with a copy of your modified RasMol_2.7.3
 directory, apply the patches listed in the prior section using
 patch_RasMol_2.7.3_to_RasMol_2.7.3.1_ru_29Dec06.sh, and then rename the
 patched directory RasMol_2_7_3_1_RU_29Dec06.  If you are doing an
 MS Windows build be certain to pick up the new icons).

This will create a directory

RasMol_2_7_3_1_RU_29Dec06

with the following subdirectory structure

Binaries may then be build according to the instructions for RasMol
  2.7.3.  In unix systems, including Mac OS X, a complete set of
  binaries for 32- 16- and 8-bit visuals should be build with
  on of the scripts included in the src directory:  build_all.sh
  for most unix systems, and build_MACOSX.sh for OS X.  The scripts
  may need to be edited to adapt to local conventions, especially
  to pick up the xforms library, if available.

At this point, under MS Windows, the next step would be to build an
  NSIS windows installer using the src/mswin/raswin_install.nsi
  script.  You will need to install NSIS in a windows system to
  create the installer.

See http://www.RasMol.org/external_packages.shtml

Under unix or Mac OS X, if you are not certain you have all the
  appropriate X11 fonts, you will need to add font kits in
  a directory named external_packages at the same level as
  the src directory using the kits at

http://www.RasMol.org/cyr-rfx-windows-1251-1.1.tar.gz
  http://www.RasMol.org/jmk-x11-fonts-3.0.tar.gz

The modified directory structure would then be

Under unix and Mac OS X, once the binaries have been build and
  the fonts from external_packages have been added, return to the
  src directory and execute the command

sh rasmol_install.sh

to install the rasmol binaries, the rasmol.hlp file and the fonts.
  The install can be controlled by both options and environment
  variables.  For more details, see the changes to the RasMol
  manual, below.

===========================================================================
        CHANGES TO THE RASMOL 2.7.3 MANUAL for RASMOL 2.7.3.1_RU
 ===========================================================================

In general, the manual for RasMol 2.7.3 may be used for RASMOL 2.7.3.1_RU

These are the major differences:

1.  Starting RasMol

Under MS Windows, RasMol can be started from the command line in an MSDOS or 
 CMD window or by double-clicking the RasMol icon.  In addition, starting with 
 RasMol 2.7.3.1 RU, RasMol can be installed so that is can be selected from
 the program list in the start menu.

Under Unix, RasMol can be started from a terminal window as in the past.
 However, in that case it is the responsibility of the user or system 
 administrator to ensure that the environment variable RASMOLPATH has
 been set to the path leading to the file rasmol.hlp and that the
 necessary fonts have been loaded for use by the X server and that
 the correct font and encoding has been selected for use by the 
 terminal window.  In addition, the user has to select a rasmol
 binary that corresponds to the pixel bit depth supported by the
 X server.  Two new scripts, rasmol_install.sh and rasmol_run.sh
 have been provided to simplify and partially automate this process.

If rasmol is installed by used of rasmol_run.sh, the binaries for
 all pixel bit depths, the rasmol help file, rasmol.hlp, and the
 script rasmol_run.sh will all be installed in a common directory,
 usually /usr/lib/RasMol_2_7_3_1 for a system install or 
 $HOME/lib/RasMol_2_7_3_1 for a user install.  At the same time,
 a special wrapper script that sets RASMOLPATH to the path to
 rasmol installation directory and then executes rasmol_run.sh is 
 installed in an appropriate binary directory, usually as 
 /usr/bin/rasmol for a system install or $HOME/bin/rasmol for a
 user install.

The configuration of the install can be controlled by the
 following options:

rasmol_install.sh usage:
        rasmol_run.sh [--help] |
          [--prefix=installdir] |
          [--compilefonts] |
          [--system] | [--local] "

--help prints out rasmol_install.sh usage

--prefix=installdir
        specifies the directory within which the installation will
        be done.  This is not the RASMOLPATH path, but the path
        intended to contain lib/RasMol_2_7_3_1 and bin/rasmol

--compilefonts
        asks that rasmol_install.sh recompile the bdf versions
        of the fonts that it installs to pcf versions.  This
        should not be necessary on newer machines, but on some
        older systems, e.g. a Solaris 2.5 system, fonts compiled 
        in one endian format cannot be handled by an X-server
        expecting the other format and must be recompiled with
        the version of bdf2pdf native to that system.

--shell=shellpath
        specifies the path of a Bourne-style shell to use in place
        of /bin/sh, e.g. --shell=/usr/local/bin/bash

--system
        if not otherwise specified by --prefix or by the
        RASMOTHPATH environment variable, try to install
        in the binaries and help file in /usr/lib/RasMol_2_7_3_1

--local
        if not otherwise specified by --prefix or by the
        RASMOTHPATH environment variable, try to install
        in the binaries and help file in $HOME/lib/RasMol_2_7_3_1

The following environment variables are used in the install:

RASMOLPATH       This is the path to the rasmol directory containing
  the rasmol help file, rasmol.hlp, and other relevant files.  If no
  --prefix option is specified, the target installation directory is
  specified by this variable.  If the --prefix option is specified, it
  overrides any existing setting of RASMOLPATH.  If the original
  RASMOLPATH or the RASMOLPATH constructed from the --prefix option by
  appending "/lib/RASMOL_2_7_3_1", has "lib" as its second to last path
  component, the rasmol wrapper script is installed in a path
  constructed by stripping the last two path components of RASMOLPATH
  and then appending /bin/rasmol.  If "lib" is not such a component,
  the wrapper is installed in a path contructed by stripping only
  the last component of RASMOLPATH and then appending only rasmol.

RASMOL_LANTIN1FDIR   This is the path to the X11 ISO 8859-1 font 
  directory to be used if the rasmol_install.sh does not find the font
  -*-*-bold-o-normal-*-14-*-iso8859-1 already installed.  If 
  RASMOL_LATIN1FDIR is not specified, a limited search is make for
  the jmk font collection.

RASMOL_CP1251FDIR    This is the path to the X11 Cyrillic code page
  1251 font directory to be used if rasmol_install.sh does not find the
  font -*-*-bold-o-normal-*-14-*-*1251 already installed.  If
  RASMOL_CP1251FDIR is not specified, or if the specified path does
  not contain misc and 75dpi subdirectories a limited search is made
  for the cry-rfx windows 1251 font collection.

RASMOL_DEBUG         If this environment variable is non-empty,
  rasmol_install.sh provides debugging information.

Note that rasmol_install.sh specifies /bin/sh for its execution.
  If /bin/sh is not available or is not a Bourne-style shell, then
  some Bourne-style shell, such as bash, should be substituted.
  The copy of script rasmol_run.sh in the installation directory
  should also be setup to use a Bourne-style shell, as should
  the rasmol wrapper script.  The option --shell=shellpath can
  be used to do the rest of the changes once the first line
  of rasmol_install.sh has been changed.

Once the install has been done, the path to the wrapper rasmol
  script should be added to the user PATH, if not already there.

Then rasmol can be executed by the command "rasmol", which will
  set RASMOLPATH and run rasmol_run.sh.  The options for rasmol_run.sh
  are "--help" and the command line options of rasmol.  Except for
  "--help" all the options are passed on the rasmol.   A set of
  language specification option are processed by rasmol_run.sh
  as well as being passed on to rasmol.  If no language is specified,
  the environment variable RASMOL_LANG and then the file 
  $HOME/.rasmol/RasMol.flg are checked for a language specifier.
  If no language is specifed, English is assumed.  At this time
  rasmol supports English, French, Italian, Russian and Spanish.
  If the language chosen is English, French, Italian or Spanish,
  rasmol_run.sh checks for the availability of the font
  -*-*-bold-o-normal-*-14-*-iso8859-1.  If the language chosen
  is Russian, rasmol_run.sh checks for the availability of
  the font -*-*-bold-o-normal-*-14-*-*1251.  If the font
  is not found, and the jmk or cyr-rfx-windows-1251 font
  directories have been set up, rasmol_run.sh uses xset to
  add those font directories to the X server font path.  If using
  a remote X-server, it is important to have added those fonts
  to the font server before calling rasmol_run.sh.  rasmol_run.sh
  then tries to find an appropriate terminal window font to
  support the selected language and normally will spawn an
  xterm using that font as the terminal font and invoking
  a rasmol binary matching the available pixel bit depth.

The spawned xterm, however, does not report start-up errors
  back to the originating window.  If rasmol does not start,
  the problem can be debugged by setting the environment
  variable RASMOL_NOSPAWN of a non-empty value.  This will
  cause rasmol to be run in the original window, making start-up
  errors visible.  However, the font selection will not be made,
  and should be made manually by the user if relevant to debugging
  the problem.  Normally RASMOL_NOSPAWN is not needed again once a
  satisfactory installation has been made and tested.  The list of
  environment variables supported by rasmol_run.sh is:

RASMOL_LANG         the name of the language to be used
      RASMOLPATH          path to the directory containing rasmol_run.sh
      RASMOL_LIBSFORMPATH path to xforms library directory"
      RASMOL_LANTIN1FDIR  path to X11 ISO 8859-1 font directory"
      RASMOL_CP1251FDIR   path to X11 ISO CP 1251 font directory"
      RASMOL_DEBUG        if non-empty, report settings"
      RASMOL_NOSPAWN      if non-empty, do not spawn an intermediary xterm"

Note that the locale variables, LANG, LC_ALL, etc. are not used in
  this release and should not be set.  They can cause the spawned
  xterm to use an encoding that does not support the fonts used
  by this release of rasmol.
 
  2.  New Menu Options

For all platforms, the list of export formats in menus has been
  updated to correspond to all the formats listed for the save and
  write commands.  The "About" dialog has been made uniform across
  platforms and not includes buttons for "Register", "OK", "Donate"
  and a checkbox for "Do not show this dialog at startup".  The
  Help menu (or the top of the Apple menu under Mac Classic) has 
  been extended to list "About RasMol", "User Manual", "Register"
  and "Donate".

3.  Changes to Commands

3.1.  The language to be used for messages and menus may be selected
  with the commands "English", "French", "Italian", "Russian" or 
  "Spanish".  Appropriate fonts must be installed before using
  a language.  In most cases the fonts for "English", "French",
  "Italian" and "Spanish" are already present.  For MS Windows
  and most unix systems, for support of Russian in this release,
  Code Page 1251 fonts need to be installed.  For Mac Classic
  systems, the ER Kurier Macintosh fonts need to be installed.

3.2.  Two new options have been added for export of VRML images:  
  "rotate"  and "mirror".