.HELP:
(1) Dialogue and plot setup:
---------------------------
By default, C3DCON searches initially for a run file named C3DCON.PAR
in the users directory to set up the plot, and keeps updating it every 
time the user exits from the setup menu. If the run file is not found, 
a set of program-internal default parameters are used to set up the plot
and a new run file will be created initially. An auxiliary dialogue 
command SAVE will save the current setup into or LOAD will read from 
a different run file. The run file is written as a keyword-oriented 
ASCII file the user may edit, and it contains all the information 
necessary to re-generate the same plot.

To edit run parameters on screen, enter "MN=parameters" where MN is the 
two letter mnemonic assigned to the parameters (e.g. GT=graph title). 
To get more help, use the following help command line options:

   (1) just type "HELP" and you get an overview of how to run C3DCON and
       its functionality.

   (2) type "HELP MN" to get a single line definition for a parameter 
       menu item, where MN is the mnemonics of the item.
       examples: HELP RO, HELP SR

   (3) type "HELP MN/ALL" or "HELP command-name" and you get a complete 
       description of a mnemonic or a dialogue command listed at the
       bottom of the menu.
       examples: HELP SL/ALL, HELP INCLUDE

Enter "GO" to start plotting on screen.

(2) Atomic model drawing:
--------------------------
The structure model can be constructed in either a sphere or a triclinic
box of enclosure with a dimension independent of that of the contour box,
but located at the same center of the display used for contouring. A 3d
rectangular clipping box (mn SL) with the desired orientation can then 
be applied to the enclosure of the display to visualize such models as a 
chain or a sheet through the structure. C3DCON can essentially read any 
ASCII atom file by user specifying the column format of its atom line 
(refer to mnemonics FI,FX,FY,FZ,FT,FC,FS for more information). Provision 
is made to handle input atom files in both fractional and angstrom (mn AN),
orthogonal and non-orthogonal (mn OR) coordinates. The unit cell (mn CP) 
and the column format of the atom line need to be specified before reading 
the atom file. They can be set from the dialogue menu or in the atom file. 
C3DCON always attempts to read the unit cell and the column format by looking 
for the two keywords among the top five lines of the atom file:

      %CP= a, b, c, alpha, beta, gamma
      %FM= I1,I2, X1,X2, Y1,Y2, Z1,Z2, T1,T2, C1, C2, S1, S2

where a,b,c,alpha,beta,gamma are unit cell parameters in angstroms and
degrees, and I#,...S# are the column delimiters that go to the mnemonics
FI,FX,FY,FZ,FT,FC,FS on the dialogue menu. The % sign must be on the 1st 
column. C3DCON treats any line containing a % or a ! in the 1st column as 
comments when reading the atom file. Also notice that the unit cell is also 
read from the 1st map file entered.

Only space-group unique symmetry operators are required and they are read 
from a symmetry file (mn F1). C3DCON will optionally search for all possible 
translation symmetries to fill the enclosure of the display from the 
asymmetric unit. Provision is also made to generate symmetry-related atoms 
from any atom(s) in the asymmetric unit using a subset of symmetry operators. 
This may be necessary in visualizing a sublattice or a superlattice. 
The format of symmetry file is

                  x1,y1,z1,t1, x2,y2,z2,t2, x3,y3,z3,t3

one line per operator (e.g. -1 0 0 0  0 1 0 0.5  0 0 -1 0 for P21) and for
technical reason, identity operator should be always listed FIRST in the file.
 
Model connectivity is controlled in a hierarchical way, i.e. hierarchical 
connection classes and groups with their individual bonding distance cutoffs 
and bond types are used to accomplish a variety of bonding requirements from 
simple high symmetry lattices to macromolecules, to disorder models, and 
to multi-model overlay. The current bond types include solid line and 3d 
dash line of different colors and thickness. 

Stick-ball rendering of the model is supported with simulated lighting 
and removal of hidden bonds and surfaces. Nine types of balls are 
implemented for a maximum of nine types of atom species. Multiple 
unit cell outline within the enclosure of the display can be included 
with a simple yes or no.
 
An atom ID label can be offset in 3d from the location of the atom to 
improve perspective viewing. In situ 3d bond distance labeling is also 
provided for selected bonds in the display. The design of C3DCON also 
renders itself as a structure model drawing routine independent of the 
presence of an electron density file.
 
(3) Contouring:
----------------
To prepare a 3D electron density file for C3DCON, enter the following
DCL command line at the system command prompt:

                  $ RUN GRAFIT$EXE:MAPACK.EXE

MAPACK converts your floating value density file into a file that is 
readable by C3DCON. Type "HELP MAPACK" on-line to see what file format 
MAPACK expects your density file to have.

The 3d density cage contours are accomplished by 2d contouring layer after 
layer along the crystallographic a,b,c axes of the unit cell. The 3d cage 
contours are then parallel-projected to the 2d viewing plane after optional 
3d clipping. Up to four contour levels from a single file or four different 
density files are allowed to be displayed on the same viewing screen. They 
can be rendered with four different colors, line types and line thicknesses. 
The desired contour region is specified by a triclinic box whose faces are 
parallel to the crystallographic axes with the center of the display located 
either by arbitrary physical coordinates or on an atom of interest in the 
structure model. The input map grid can be of a complete or an incomplete 
unit cell, but is expected to in a-across, b-down, and c-section. Given a 
complete grid cell, C3DCON will allow for continuous contouring across the 
cell boundaries together with structure model overlay using crystallographic 
translation symmetries. This makes it particularly convenient to examine 
the structure model in the vicinity of the cell boundaries without 
specifically computing the Fourier synthesis at the region.

(4) On-line Graphics Editing:
------------------------------ 
On-line interactive graphics editing of the display is implemented on
a Tek4100 with segment graphics capability. The editing session, when 
invoked upon a completed display, uses a crosshair cursor and a set of 
function keys and optionally a mouse to manipulate the display. The 
current version of C3DCON supports such manipulations as zoom, rotation, 
hiding toggle, stereo/mono display toggle, atom ID labeling, bond connect 
and break, as well as display of bond distance, angle, torsion for the 
selected atoms. The edited display is saved and can be sent for hardcopy.
.T1:
Ball color, type, and size in angstrom for atom species 1.
Following ball types are available:

      0> Nothing except for bonding.
      1> 3d cross.
      2> Solid white ball.
      3> Solid gray ball.
      4> Solid black ball.
      5> Solid write ball with dash outline.
      6> White ball with gray shade.
      7> Gray  ball with white spot.
      8> Black ball with white spot.
      9> Solid white ball with dash outline and gray shade.
  10-14> Solid lighting balls with simulated front-light sources.
  15-18> Solid lighting balls with simulated side-light sources.

A negative ball type signals the type of atoms to be connected in no way. 
Note: screen display shows the colored solid balls only in order to speed 
up drawing. The designated types of balls are shown only on the hardcopy,
which is currently supported on a postscript laser printer.
.T2:
Ball color, type, and size in angstrom for atom species 2.
See T1 for the complete information on the types of balls available.
.T3:
Ball color, type, and size in angstrom for atom species 3.
See T1 for the complete information on the types of balls available.
.T4:
Ball color, type, and size in angstrom for atom species 4.
See T1 for the complete information on the types of balls available.
.T5:
Ball color, type, and size in angstrom for atom species 5.
See T1 for the complete information on the types of balls available.
.T6:
Ball color, type, and size in angstrom for atom species 6.
See T1 for the complete information on the types of balls available.
.T7:
Ball color, type, and size in angstrom for atom species 7.
See T1 for the complete information on the types of balls available.
.T8:
Ball color, type, and size in angstrom for atom species 8.
See T1 for the complete information on the types of balls available.
.T9:
Ball color, type, and size in angstrom for atom species 9.
See T1 for the complete information on the types of balls available.
.F0:
Current run setup or parameter file which saves and restores the plot.
To save the current plot into a new run file, use the SAVE command.
To restore a plot from a run file, use the LOAD command.

The run file is written as a keyword-oriented ASCII file the user may edit, 
and it contains all the information necessary to re-generate the same plot. 
.M1:
The 1st electron density file from which cell parameters are used.
Enter HELP MAPACK to get information on the required file format.
When a valid density file is entered, C3DCON displays its grid definition,
minimum and maximum density values and sigma at the same menu line after
the filename. Maximum length of filename is 32 chars although only the 1st
10 chars are displayed.
.M2:
2nd electron density file which may have a different grid definition.
Enter HELP M1/ALL for more information.
.M3:
3rd electron density file which may have a different grid definition.
Enter HELP M1/ALL for more information.
.M4:
4th electron density file which may have a different grid definition.
Enter HELP M1/ALL for more information.
.F1:
Symmetry file. Maximum length of filename is 32 chars although only the
1st 10 chars are displayed. Only space-group unique symmetry operators 
are required. C3DCON will optionally search for all possible translation 
symmetries to fill the enclosure of the display from the asymmetric unit.
The translation search can be disabled with SY=NO.
The format of symmetry file is

                  x1,y1,z1,t1, x2,y2,z2,t2, x3,y3,z3,t3

one line per operator (e.g. -1 0 0 0  0 1 0 0.5  0 0 -1 0 for P21) and for
technical reason, identity operator should be always listed FIRST in the file.

Selective symmetry-related atoms can also be generated from any atom(s) 
in the asymmetric unit using a subset of symmetry operators. This is done 
by entering a symmetry inclusive range for each of the desired atoms in the 
atom file. Refer to mnemonic FS for more information (identity operator is 
required for this reason). This may be necessary in visualizing a sublattice 
or a superlattice. 
.F2:
Model atom file with 1 atom/line. Max length of filename is 32 chars although 
only the 1st 10 chars are displayed. C3DCON can essentially read any ASCII 
atom file by user specifying the column format of its atom line (refer to 
mnemonics FI,FX,FY,FZ,FT,FC,FS for more information). Provision is made to 
handle input atom files in both fractional and angstrom (mn AN), orthogonal 
and non-orthogonal (mn OR) coordinates. The unit cell (mn CP) and the column 
format of the atom line need to be specified before reading the atom file. 
They can be set from the dialogue menu or in the atom file. C3DCON always 
attempts to read the unit cell and the column format by looking for the 
two keywords among the top five lines of the atom file:

      %CP= a, b, c, alpha, beta, gamma
      %FM= I1,I2, X1,X2, Y1,Y2, Z1,Z2, T1,T2, C1, C2, S1, S2

where a,b,c,alpha,beta,gamma are unit cell parameters in angstroms and 
degrees, and I#,...S# are the column delimiters that go to mnemonics 
FI,FX,FY,FZ,FT,FC,FS on the dialogue menu. The % sign must be on the 1st 
column. C3DCON treats any line containing a % or a ! in the 1st column as 
comments when reading the atom file. Also notice that the unit cell is also 
read from the 1st map file entered. "%CP" and "%FM" from atom file override
existing cell parameters and column format.
.F3:
Auxiliary layout file to save and restore the layout if invoked.
Maximum length of filename is 32 chars although only the 1st 10 chars
are displayed. For more information on auxiliary layout, invoke layout
from local command menu and type HELP.
.AT:
Atom ID at which the display center (mn CD) is located, where the ID is 
tested against the string of line delimited by mn FI. Refer to mn CD for 
alternative way of locating center of display.
.CD:
Center of the display in fractional coordinates along crystallographic
a,b,c axes. Refer to mn AT for alternative way of locating center of 
display. CD and AT are mutually exclusive.
.AX:
Length of the orientation axes in angstrom (0.0=skip drawing them).
The orientation axes made of crystallographic a,b,c axes are shown 
at the display center in the current rotation angles.
.FI:
Starting & ending columns in atom file for reading atom id label.
The column position can be anywhere in the line. No sequence or order
is assumed by C3DCON as compared to other column delimiters. They can
even overlap with one another. The only requirement for column delimiters
are that they are less than 132. To skip reading atom id label, enter
zero values for the delimiters.
.FX:
Starting & ending columns in atom file for reading the x-coordinate.
The column position can be anywhere in the line. No sequence or order
is assumed by C3DCON as compared to other column delimiters. They can
even overlap with one another. The only requirement for column delimiters
are that they are less than 132. These delimiters can not be skipped.
.FY:
Starting & ending columns in atom file for reading the y-coordinate.
The column position can be anywhere in the line. No sequence or order
is assumed by C3DCON as compared to other column delimiters. They can
even overlap with one another. The only requirement for column delimiters
are that they are less than 132. These delimiters can not be skipped.
.FZ:
Starting & ending columns in atom file for reading the z-coordinate.
The column position can be anywhere in the line. No sequence or order
is assumed by C3DCON as compared to other column delimiters. They can
even overlap with one another. The only requirement for column delimiters
are that they are less than 132. These delimiters can not be skipped.
.FT:
Starting & ending columns in atom file for reading atom type or species
number. The column position can be anywhere in the line. No sequence or 
order is assumed by C3DCON as compared to other column delimiters. They 
can even overlap with one another. The only requirement for column 
delimiters are that they are less than 132.

Atom type should be an integer in the range of 1-9. If it is off by
setting "FT=0 0", all atoms are assumed to be of type 1. If it is on,
an atom type will remain effective for subsequent atoms read until it
is overriden. This means that there is no need to specify atom type for
every atom line if this is done from the editor.
.FC:
Starting & ending columns in atom file for reading atom connection class.
The column position can be anywhere in the line. No sequence or order is 
assumed by C3DCON as compared to other column delimiters. They can even 
overlap with one another. The only requirement for column delimiters are 
that they are less than 132.

The connection class an atom belongs to could be any positive integer. 
If it is off by setting "FC=0 0", all atoms are assumed to belong to
connection class 1. If it is on, the class flag of an atom will remain 
effective for subsequent atoms read until it is overriden. This means that 
there is no need to specify the class flag for every atom line if this 
is done from the editor. C3DCON will only connect atoms with the same
connection class flag. To overlay two models, for example, you can assign
class 1 for all the atoms in model 1 and class 2 in model 2. Notice that
the connection class is used as additional or alternative way to accomplish
the the desired model connectivity when the distance cutoff criteria fail.
.FS:
Starting & ending columns in atom file for reading symmetry flags.
The flags are two positive integers that serve as the inclusive pointers
to the input list of symmetry operators to signal C3DCON to generate
symmetry-related ones of this atom using this or these symmetry operators.
Unlike FT and FC, FS is effective only for the atom containing the flags.
If it is skipped by setting "FS=0 0" or as blanks in the atom file, all
symmetry operators will be used to generate the symmetry-related atoms.
.SL:
Slab/clipping rectangular box along x,y,z axes in angstroms in semi-dimensions
about the center of display. A zero value in a direction signals no clipping
in that direction. The 3d clipping box can be applied in two ways, i.e. before
and after reading the atom file. If the clipping box is on before reading the
atom file, the model is clipped according the active plot orientation and the
clipping box can be removed afterward. This may be necessary if a different 
shape of display model other than spherical or triclinic enclosure is desired.
The clipping box also applies to contouring and atom id labeling.
.SA:
Total stereo angle in degrees. A zero angle signals a mono-display. 
A positive angle (e.g. 6.0) generates a stereo pair for stereoscope glass 
viewing. A negative angle (e.g. -6.0) produces a stereo pair for cross-eyes.

By default, C3DCON aligns the crystallographic a,b-axes of the display 
with the horizontal(x) and vertical(y) axes of the viewing screen. The 
c,z-axes thus point out of the screen using the right-hand rule. On the 
mapped 10x8 inch viewing screen of a Tek4100, stereo pairs are displayed 
together but separated by 5-inch with the left and right eye views rotated 
around the y-axis. The same arrangement is conveniently sent to the 
supported hardcopy devices when requested.  If a larger plot of a stereo 
pair or a stereo view around other axis are needed, two mono-displays of 
the pair can be constructed separately with the desired orientations and 
the stereo pair is thus obtained.
.NN:
Range of atoms in sequence, i.e. beginning and ending line numbers
to read in atoms from the atom file. When the range is off (0,0), whole
atom file will be read. Refer to INCLUDE and EXCLUDE commands for other
ways to include or exclude atoms from the atom file. 
If NN is on, INCLUDE and EXCLUDE commands work only in the NN range.
.UC:
Parameters controlling the outline of the unit cell within the enclosure
of the display. Parameter #1 sets the pen/color code of the outline, 
a zero value signals no unit cell outline. Parameter #2 sets the line 
width of the outline while the third the line type of the outline.  
When signaled on, C3DCON outlines as many unit cells as there are in 
the enclosure of the display.
.BN:
Model connection setup group.
Parameter #1,#2 are the origin atom species run for all connection classes.
Parameter #3,#4 are the target atom species run for all connection classes.
Parameter #5,#6,#7 are bond color, line width and line type.
A zero value for parameter #1 eliminates the active connection setup.
Use the DOWN/PF1 or UP/PF3 to scan and set the active pointer of the
connection group.
.LB:
Atom type ball labeling consisting of a ball and a label from mn LT for 
the nine types of balls. Parameter #1 sets the labeling path:

      0: signal no ball type label.
      1: ball label on, horizontal path to the right.
     -1: ball label on, horizontal path to the left.
      2: ball label on, vertical path downwards.
     -2: ball label on, vertical path upwards.

Parameter #2 sets the initial labeling path position (x,y) in inches 
relative to the center of the screen. Parameter #3 sets the character
size of the labels.
.LT:
Ball labels for the nine types of balls (max 4 chars each).
Use space(s) or comma(s) in the input line to separate or skip the labels.
These labels are displayed on the right side of the balls. If other position
of labeling or longer labels are desired, resort to the auxiliary layout.
.COMMANDS:
Defined dialogue commands for C3DCON:

EXIT/QUIT  : Exit from C3DCON.
GO/PF1     : Start plotting on screen.
HELP/PF2   : Invoke on-line help utility.
REFRESH/PF3: Refresh the dialogue menu if necessary.
DCL/VMS/PF4: Spawn a system sub-process.
UP/DOWN    : Set active model connection group.
LOAD       : Read a new run setup file (*.PAR), same as F0=filename.
READ       : Read a new model file (*.XYZ), same as F2=filename.
SAVE       : Save the current plot into a new run setup file.
LOCATE     : Locate an atom as the contour box center.
TIME       : Display the system clock.
DISTANCE   : Compute distances among loaded atoms.
ANGLE      : Compute 3 atom angles among loaded atoms
RESET      : Initialize all setup parameters.
INCLUDE    : Set up atom inclusive entry list.
EXCLUDE    : Set up atom exclusive entry list.
.EXIT:
Exit from C3DCON. If a hardcopy metal file exists, C3DCON exits to the 
local command menu so that you can still make a hardcopy from the
previous plot session, or else, it exits to the system command prompt.
    
.REFRESH:
Refresh the dialogue menu if necessary.
.DCL:
Spawn a system sub-process (i.e. go to system command prompt so that you can
do other things without exiting from C3DCON. You can execute a DCL command
line directly from C3DCON by entering "DCL command-line".
.UP:
Step active model connection group up by one (BN=) so that you can read and 
edit it.
.DOWN:
Step active model connection group down by one so that you can read and edit it.
.LOAD:
Load a new run setup file (*.PAR), same as F0=filename.

Command syntax: LOAD setup-filename

The current plot will be erased. Use the SAVE command to save it if desired.
.READ:
Read a new atom file (*.XYZ), same as F2=filename.

Command syntax: READ setup-filename

The current model will be erased. Use the SAVE command to save it if desired.
.SAVE:
Save the current plot into a new run setup file.

Command syntax: SAVE setup-filename

To recall a saved plot, use the LOAD command.
.LOCATE:
Locate an atom in the atom file as the center of the display.

Command syntax: LOCATE atom-id

where atom-id is tested against the string delimited by "FI=".
.TIME:
Display the current system time on the top-right corner of screen.
.DISTANCE:
Compute distances among loaded atoms.

Command syntax: DISTance d1,d2,i1,i2,i3,i4/OUTPUT=filename 

where "/OUTPUT=filename" is the listing-output redirect and the default
channel is to the on-line screen; d1,d2 are the distance cutoffs, i1,i2
optional origin atom-type number run; i3,i4 optional target atom-type
number run (the default is that all atom-types are included).
.MAPACK:
Input electron density file is expected to be of binary, its 3d grid 
to be in a-across, b-down, c-section, and its format as follows 
(excerpt from the read section of MAPACK code):

      READ(1) TITLE*64, CELL(6), MX,MY,MZ,IXI,IXF,IYI,IYF,IZI,IZF
      DO I= IZI, IZF
         DO J= IYI, IYF
             READ(1) (RHO(K),K=1,IXF-IXI+1)
         ENDDO
      ENDDO

where TITLE is a title of 64 characters, MX,MY,MZ are grid size
of the unit cell, and IXI,IXF,IYI,IYF,IZI,IZF the initial and
final points of the density grid calculated. The density grid
are stored as rows along a-axis in one row per record.

Note: MAPACK is not a defined dialogue command.
.RESET:
Initialize all setup parameters (program defaults are used).
.INCLUDE:
Set up atom inclusive entry list.

Command syntax: INCLUDE string c1 c2

where "string" is a max 8-character string from the atom line,
and c1,c2 are optional string column delimiters. If c1,c2 are
omitted, any atom line containing the "string" is included.
You can enter as many inclusive entries as you wish and the
exclusive entries if any will be discarded (they are mutually
exclusive). An INCLUDE command without any parameter clears 
the inclusive/exclusive entry list. The inclusive list is only
effective before reading the atom file. Re-read the atom file
if necessary.
.EXCLUDE:
Set up atom exclusive entry list.

Command syntax: EXCLUDE string c1 c2

where "string" is a max 8-character string from the atom line,
and c1,c2 are optional string column delimiters. If c1,c2 are
omitted, any atom line containing the "string" is excluded.
You can enter as many exclusive entries as you wish and the
inclusive entries if any will be discarded (they are mutually
exclusive). An EXCLUDE command without any parameter clears 
the inclusive/exclusive entry list. The exclusive list is only
effective before reading the atom file. Re-read the atom file
if necessary.
.MENU:
0: Exit to the main menu.
1: Invoke hardcopy making utility.
   If you just get back from auxiliary layout and would like
   to have the changes just made in the layout to show up on
   the hardcopy, redraw the plot before invoking the hardcopy.
2: Invoke auxiliary layout utility.
3: Invoke the dialogue menu.
4: Toggle components of graph between visible and invisible.
5: Zoom the graph.
6: Redraw the plot.
7: Toggle graph between mono plot and stereo pair.
8: Edit atom ID and bonds, etc...
9: Rotate the plot and the prompt for delta angles will follow.
$: Spawn a system subprocess.
PF1: Invoke hardcopy making utility without the page setup menu.
PF2: Invoke this help menu.
PF3: Invoke the dialogue menu.
PF4: Spawn a system subprocess.
.EDIT:
To edit the plot, move the crosshair cursor to touch an atom or a bond,
then press one of the following defined function keys:

SPACEBAR: Select atoms for function keys F1,F2,F3,F5,F6,F7. The selected
          atoms are pushed into a 4-atom stack with the latest atom on
          top of the stack. When the 5th atom is selected, the 1st atom
          is discarded.
 F1     : Show distance between the two atoms on top of the atom stack.
 F2     : Show angle among the three atoms on top of the atom stack.
 F3     : Show torsion among the four atoms on the atom stack.
 F4     : Toggle atom ID label.
 F5     : Draw a bond between the two atoms on top of the atom stack.
 F6     : Delete a bond touched by the cursor or between the two atoms touched.
 F7     : Draw distance label between the two atoms on top of the atom stack.
 F8     : Delete a distance label touched by the cursor.

If you have a mouse attached to the keyboard, following definitions apply:

      Mouse_unshift_left   ==== SPACEBAR
      Mouse___shift_left   ==== F1
      Mouse_unshift_middle ==== F4
      Mouse___shift_middle ==== F2
      Mouse_unshift_right  ==== F5
      Mouse___shift_right  ==== F6
