PyCIFRW Readme
                          --------------

Introduction
------------

PyCIFRW provides support for reading and writing CIF (Crystallographic
Information Format) files using Python.  It was developed at the
Australian National Beamline Facility (ANBF), run by the Australian
Synchrotron Research Program (ASRP), as part of a larger project to
provide CIF input/output capabilities for data collection.  It is
currently (Nov 2004) under active development and testing.

Conformance
-----------

The CIF 1.1 working specification was used as a reference, and in most
cases the grammar and character sets specified there were copied
directly.

PyCifRW has been tested on the IUCr sample CIF trip files located at
http://www.iucr.org/iucr-top/cif/developers/trip and fails or 
successfully reads as it is supposed to (note that ciftest5 contains
characters now forbidden in CIFs).    Attempts to add an overlength  
dataname to a CIF file currently resident in memory will result in an error.
Output lines do not exceed 2048 characters. 

Supported Platforms
-------------------

PyCIFRW is written entirely in Python.  While this makes parsing of large
CIF files rather slow, it will run wherever Python runs.  It has been
tested on Unix (Linux,Solaris) and Windows 95/98 under Python 1.5.2 and
Python 2.0.  Macintoshes may have trouble with the Unix-style line 
termination of the .py files.

Files
-----

PyCiFRW consists of the following files:

Original files:

CifFile.py                     Defines the CifFile module for Python
CifFile.nw                     Noweb file from which CifFile.py is obtained
CifFile.html                   Programming notes for CifFile derived also from
                               CifFile.nw
YappsCifParser.py              Cif parser automatically generated by Yapps2 
YappsCifParser.g               Grammar specifications for input to Yapps2
YappsCifParser.html            Programming notes for the grammar
YappsCifParser.nw              Literate format grammar notes
Makefile                       How to derive .html, .py and .g files from .nw files

Files derived from other programs:

yappsrt.py                     Yapps2 runtime support (Scanner etc.).  Part of the
                               Yapps2 distribution 

Installation
------------

All .py files should be placed in a directory where python can find them, for
example .../lib/python/site-packages/PyCifRW under Unix-type systems, and in
C:/Python20/Lib/PyCifRW for Windows.  Unix users should note that they will
need to create a file named 'PyCifRW.pth' in the site-packages directory 
containing the single word 'PyCifRW'.

Use
---

See the text in CifFile.html for details of the interface.  Essentially,
cif files look like python dictionaries, with each entry in the dictionary
corresponding to a data block.  The blocks themselves are also dictionaries,
with each data name being a single entry in the dictionary, so for example,
cf['si_std']['_diffrn_meas_wavelength'] will return the value of 
_diffrn_meas_wavelength in the data block named si_std of the Cif file object
cf.


Example
-------

To read in a CIF:
>> from PyCifRW.CifFile import *
>> cf = CifFile('jun_01_2.cif')

to access information in a CIF

>> wav = cf['si_std']['_diffrn_meas_wavelength']

to set a value

>> cf['si_std']['_diffrn_meas_wavelength'] = 1.54