-------------------------------------------------------------------------------

			Chemtool Version 1.4

-------------------------------------------------------------------------------

Chemtool is a program for drawing organic molecules easily and store them as
a X bitmap file. It runs under the X Window System using the GTK widget set.
An older version (1.1.8) that requires only the standard Athena Widget Set
(Xlib) is still available for situations where GTK cannot be installed for
some reason. In principle, all features added since 1.1.8 could be
back-ported to the Xlib-based version if necessary. 



----------------------> Usage:

This program is intended to be very simple to use. Please contact the authors
if you encounter problems, or would like to offer suggestions or patches.

Drawing of bonds:

Bonds can be drawn in 4 different angle settings (hexagon with 30deg. intervals,
two pentagons with 72deg. intervals (different orientation), and a 45deg. i
octagon). (Intermediate angles are possible in all of these modes as well - 
just ignore the marker points in this case). Pressing the mouse button 1
sets the starting point of a bond and also displays a set of markers at the
appropriate angular positions. Dragging the mouse while holding down the
button draws a line in the desired direction.

All bonds are initially drawn as single lines (or the linetype that is 
preselected from the menubar) that can be converted to other types later.

Pressing the middle mousebutton on a bond increments its type code (see below),
while pressing the third (usually the right) button deletes the bond next
to the cursor position.

Shortcuts for labeling:

In the drawing modes, several keyboard keys function as shortcuts that insert
a label at the current cursor position. These are:
b,c,h,d,n,o,s,p,f,i,r - for B, C, H, D, N, O, S, P, F, I, and R
l - for Cl
1,2,3 - for CH, CH_2, and CH_3
* - for drawing a centered dot (for cumulenes, or bridge positions in
bicyclic compounds).

Semiautomatic drawing of rings:

Rings of 3 to 12 members can be drawn easily by holding down the Ctrl key
while drawing a line. This line will then become the first segment of a ring
that is automatically drawn in clockwise direction. The size of the ring 
defaults to that appropriate for the selected drawing mode (i.e. 5, 6 or 8 
sides), but it can be set on a per-ring basis by pressing Ctrl-<number> 
before drawing the ring, where numbers 3-9 correspond to 3 to 9-membered 
rings, while 0 to 2 select 10, 11 and 12-membered rings, respectively. 
Newly drawn rings can be deleted by pressing Ctrl and mouse button 3 together.

Drawing of curved lines:

Curved lines for objects like arrows or orbital lobes can be drawn in spline
curve mode by specifing four control points that form a bounding polygon
(startpoint, two points on either side of the peak, endpoint). Of the regular
bondtypes available in the Style menu, the 'single line', 'semiarrow', arrow
and 'dashed line' retain their usual function, while the 'wide line' type
is used to denote a filled polygon. The control points are only visible in
'Move' mode, where they can be dragged around to change the form of a curve 
after it is drawn. 

Setting bond style:

In bond style mode, clicking on any bond in the diagram cycles its representation
through the sequence
- double bond 
- double bond (shorter line on the other side)
- centered double bond
- triple bond
- wedge-shaped bond
- dashed wedge-shaped bond
- wavy line
- half arrow 
- arrow
- wide bond
- circle
- dotted line
- single bond that 'cuts out' a segment from any bond it crosses
- partial double bond 
- partial double bond (dashed line on opposite side)
- dashed line

The additional bond type available in the pulldown menu,
- curved arrow 
is only available for drawing. It is actually a shortcut for one of 
the curve drawing functions described above, with the second and third
control points automatically generated. As such, it can not be converted 
to or from any of the conventional bond types. 
(One can, however, convert it to any of the other curve types, e.g. to change
the type of arrowhead). The shape of the arrow will usually need to be 
adjusted by shifting the control point that appears alongside it in 'Move' 
mode.

Pressing the middle mousebutton on a bond when in 'Bondtype' mode reverses 
the direction of that bond.

Inserting text:

Text written into the text box (to the right of the menu area) can be 
positioned with the cursor and may appear left, middle or right-aligned 
in the drawing. 
There are two special characters to be used for sub- and superscripting
the following character: 

		'^' to shift up 	(e.g. N^+)
		'_' to shift down	(e.g. CH_3) 

The control character '|' is used to itializise the following character,
as in |t-Bu.

The special character '@' switches to symbol mode, which uses the standard
X11 symbol font. All alphabetic keys produce the corresponding greek 
characters in this mode, and several other symbols are available if their
standard latin1 equivalents are already mapped onto the keyboard:
yen -> infinity
hyphen -> uparrow
macron -> downarrow 

The symbols 'plusminus' and 'registered' (trademark) are already in the
standard font, although they are not normally available on the keyboard.
Use the following commands (or add the declarations to your .xmodmaprc )
to make them available via <AltGr>+<Key> (<RightAlt>+<Key>):
 
         xmodmap -e 'keysym r = r R registered'  \
         -e 'keysym o = o O yen' \
         -e 'keysym p = p P plusminus' \
         -e 'keysym u = u U hyphen' \
         -e 'keysym d = d D macron'

(this leads to AltGr-P = plusminus, AltGr-R = registered in normal mode and
AltGr-O = infinity, AltGr-U = uparrow, AltGr-D = downarrow in symbol font).

For 'dots-and-crosses' diagrams, the following mappings to the symbol
font might be useful:
acute -> cross  (e.g. keysym x = x X acute)
middle dot -> filled dot (e.g. keysym d = d D periodcentered)    
(using the degree sign for the open dot).

When you want to use symbols as sub- or superscripts, place the sub- or 
superscripting character before the '@' character, e.g. K_@a . 

Clicking the middle mousebutton on a label in the drawing
copies its contents into the text box for editing.

The right mousebutton can be used to delete text anchored at the cursor
position.

Centering:

If there is not enough space for your molecule you can
put it in the middle of the sheet with the center button.

Exporting to foreign formats:

You can export your molecules as an X bitmap, an encapsulated postscript file, 
an input file for Brian Smith' XFig program or in the PicTeX format. 
The PicTeX and Postscript output functions rely on the fig2dev program from the 
transfig package.
You can create the outputs in different sizes according to the current zoom
scale. The PicTeX and Postscript modes additionally allow scaling to an 
arbitrary percentage selectable on the export menu .

To include the PicTeX-file in your LaTeX document, you will need the pictex 
macro package. Depending on the versions you use, you might also have to load 
the 'color' package in the preamble of your LaTeX file.
If you encounter 'TeX capacity exceeded' error messages, increase the 
extra_mem_bot parameter in your texmf.cnf file (usually located in 
/usr/share/texmf/web2c, /usr/local/texmf or /etc/texmf). 
Pictex is known for its unusual (by tex standards) memory requirements, and 
the default settings often do not account for this (although you may find a 
comment like 'change this if you use pictex' in the texmf.cnf file already).

Something like extra_mem_bot=400000 should not hurt on any moderately modern 
system.

Selecting all or parts of a drawing for transformations:

Using the 'Mark' button, you can easily select parts of the current drawing
by enclosing them with a 'rubberband' rectangle. The selected parts will 
appear highlighted in blue and are immediately available for 

- moving: simply drag the fragment to the desired position with the mouse
	while holding down the left mouse button

- rotating: horizontal movement of the mouse translates to smooth rotation
            of the selected fragment around its center

- flipping (mirroring) the fragment about a horizontal or vertical mirror
  plane through its center: this is performed by clicking on the appropriate
  the menu button

- copying : clicking on the 'Copy' menu button creates an exact copy of the
            selected fragment slightly offset to the original. The mark is
            automatically transfered to the new copy.

- rescaling: horizontal mouse movement is translated into a smooth
	     increase or decrease of size of the marked fragment. Holding
	     the Shift key during movement limits the change to the vertical
             dimension, thereby flattening the object to achive a pseudo-3d
             perspective 
         
- deleting : to delete the marked fragment, simply click the third
	    (usually the right) mouse button after it is highlighted.

- bracketing : to draw a rectangular bracket around the selected molecule
               or fragment, simply click this button. The position and
             size of the bracket drawn is determined by the corners of the
             selection box

- optimizing: clicking on the 'bucket and broom' symbol invokes a function
             that removes overlapping (duplicate) bonds and labels from
	     the drawing.
 
Adding previously saved figures:

To add another molecule from a previously saved chemtool drawing, select its 
filename in the dialog window that comes up when you press the 'Add' button.
The newly added molecule is automatically made active so that it can be 
repositioned as desired.

Adding one of the predefined templates:

Pressing the 'Templates' button opens a second window with a small collection
of predefined structures. Simply click on the preview of the desired molecule
to add it to your drawing. The Template window can be kept open throughout a
chemtool session - if it is hidden by another window, you can move it to the
front by clicking the 'Template' button in chemtool again.
The data in the template system differ from normal chemtool drawings only by
the fact that they are stored within the program, and in a slightly awkward
format (x and y coordinates listed separately in the source file templates.h).
These are meant to provide a convenient basis set available to all users, but
not individually extendable (you can use the 'Add' function for your own 
structures). Please let us know if you want specific molecules added to the
templates - their name or ideally a regular chemtool drawing file is all we 
need. (send email to martin@ruby.chemie.uni-freiburg.de)

Determining sum formula and molecular weight:

Since development version 1.3a7, the distribution contains a helper program,
cht, by Radek Liboska (Prague) to calculate sum formula and (exact) molecular
weight from a chemtool drawing file. It is also available from within chemtool
to calculate these data for the current structure or a marked fragment of
it. Cht can be misled by duplicate bonds ( chemtool does not remove overlapping
bonds, such as they might result from fusing ring systems, automatically) and
by the 'aromatic ring' symbol, so you should avoid these and check the 
plausibility of the generated sum formula where possible.


Drawing functions not available within Chemtool:

For features not currently supported by chemtool, like color or 
general line-drawing functions, getting Brian Smith's XFig 
drawing package from www-epb.lbl.gov/xfig is highly recommended.
About the only thing it does not offer is support for 'chemical' linetypes
and drawing angles - which is why chemtool was written as a sort of
companion program. (There will probably be more of the most sorely needed
drawing options added to chemtool over time, but duplicating the more 
general-purpose features of xfig seems rather pointless.)


----------------------> Early history (T.Volk):

15.Feb.1998 	I fixed a bug that sometimes crashed the program,
		when one use the center or zoom function.

27.Feb.1998	Another (crash) bug was fixed.


28.Feb.1998	Adding new features :
					export to xfig and PicTeX;
					moving of objects;

12.Mar.1998	The LaTeX and xfig-output works with 3 different
		zoom factors.

for later changes see the file ChangeLog

----------------------> Licensing :

For license information see the file 'COPYING' in this package, i.e. the
GNU General Public License.  This software comes with ABSOLUTELY NO WARRANTY.


----------------------> Primary Authors:

Thomas Volk      (program creator, maintainer up to 1.1.1)
Hauffstrasse 12
89077 Ulm
Germany
E-Mail:		Thomas.Volk@student.uni-ulm.de

Dr. Martin Kroeker (primary developer since 1.1.2)
Zum Markwald 6
63165 Muehlheim
Germany
martin@ruby.chemie.uni-freiburg.de or mk@daveg.com      

Webpage:	http://www.uni-ulm.de/~s_tvolk
Alternative site and Development versions: 
http://ruby.chemie.uni-freiburg.de/~martin/chemtool/chemtool.html