CIFTEX/PROOF - TOOLS FOR TYPESETTING A JOURNAL PAPER FROM A CRYSTALLOGRAPHIC INFORMATION FILE This is a beta test release of the ciftex package for translating a CIF submission to Acta Crystallographica into print. This distribution is for Unix systems. ============================================================================== CONTENTS OF THE DISTRIBUTION You should have received a tar file containing: - C source code for the program ciftex, to translate a CIF file into TeX - C source for proof, a driver program to preprocess an arbitrary CIF into the form necessary for translation to Acta paper format - Fortran source for the general CIF handling program QUASAR, which is called from within proof - request files used by QUASAR to sort the CIF into Acta order - map and format files used by ciftex to set papers in different styles - TeX macro files - an example CIF and the TeX file resulting after it is processed by proof - a blank CIF template, for use if you have no CIF-generating software - manual pages for these programs and the CIF and STAR file formats - a shell script "makedict" for typesetting CIF dictionaries - a Makefile ============================================================================== INSTALLATION *STEP1* If necessary, edit the Makefile to supply the correct names for your C and Fortran compilers. They are assumed by default to be "cc" and "f77". Ideally, you should have write permission in the directories /usr/local and /usr/local/bin. If you have, make a new directory /usr/local/lib/cif. Otherwise you should edit the Makefile to give the correct values to LIBDIR, TEXDIR and BINDIR, where BINDIR is the installation directory for executables, TEXDIR is where the TeX macro files should live, and LIBDIR is a directory which will hold the supplementary files that ciftex and QUASAR need to use. In the present distribution Makefile, LIBDIR and TEXDIR have the same values. You may also choose to put the TeX macro files (*.tex) in a different place, such as your usual TEXINPUTS directory. If you need to do this, you should edit the path names in main.c, proof.c, the *format files, and the file actacif.tex. (Sorry - we'll try to make this easier in the next distribution.) *STEP2* You may need to change the date formatting routine in utility.c. If your system doesn't support strftime, delete the line that refers to it and use the commented-out sprintf statement. If you have trouble with that, scrub the getdate() subroutine and its single call from main.c altogether. *STEP3* If you already have a working version of QUASAR on your system, type "make". Otherwise, type "make all". This should make the executables in the current directory. *STEP4* Test the compiled executables by doing "proof -r . -map map -format format example" This should create a file called "example.tex". Compare this with the file "example.tex.dist". Only the date line should differ. *STEP5* If all looks OK at this stage, type "make install". If it doesn't, let us know. ============================================================================== HOW DOES IT WORK? If everything is set up properly, "proof xxxx" will look in the current directory for a file called xxxx.cif (or, if no such name occurs, just xxxx). It scans the CIF for data block names, and puts together a request list of the items from each data block that are required for an Acta paper. This request list is passed to QUASAR, which reorders the data in the CIF in an appropriate way, and the QUASAR output is filtered through ciftex to produce the TeX file. ciftex takes each CIF (data name, value) pair and rewrites it as a TeX macro call; so the input _cell_length_a 9.876(5) is translated to a line of TeX something like \cella{9.876 (5)} The translations between data names and TeX macro names are determined by the mappings listed in the map file; since this is read in at runtime, different translations can be applied for different purposes. The format file includes blocks of verbatim TeX code that are inserted at appropriate positions in the TeX output file. This is also read at runtime. Different map and format files can be passed to proof and ciftex by setting the environment variables CIFTEX_MAP and CIFTEX_FORMAT to the full path names of the files to be used, or by using the "-map" and "-format" command-line options. "proof -F" and "proof -G" are intended to supply the relevant map and format files for papers in French and German, respectively. The "-r" option to proof designates a directory which holds the standard request list files, if it is not possible to install these in the default directory. Further details are given in the man(1) pages supplied. The small shell script "makedict" is a wrapper to supply the correct translation files to ciftex for formatting CIF data dictionaries. If you have the Star_Base program sb installed, this will be used to modify the order of fields in each entry; otherwise the order is as in the input dictionary. The dictionary setting macros are particularly fragile at the moment, and are undergoing development - this utility is primarily for the benefit of developers of CIF dictionaries. ============================================================================== TeX It will not have escaped your notice that you need the typesetting program TeX to make full use of this package! If you need to install TeX, and do not know where to begin, you could start by reading the list of TeX 'Frequently Asked Questions'. This may be obtained by sending an e-mail message containing only the line send tex.faq to the address sendcif@iucr.ac.uk. We are not in a position to provide support for TeX, which is a large and complex package (but will try to answer your questions if you are absolutely desparate.) NB: The galley proof version of the paper (generated by the option "proof -p") requires PostScript font support as provided by the output filter dvitps, which is shipped as standard on the Washington Unix tape. If you haven't got this, use the default preprint option with proof to create files that should be printable with any standard TeX output driver. ============================================================================== BUG REPORTS Bug reports, as well as general feedback on the usefulness or otherwise of these programs, should be sent to Brian McMahon or Mike Hoyland at International Union of Crystallography, 5 Abbey Square, Chester CH1 2HU, England (e-mail: bm@iucr.ac.uk or mh@iucr.ac.uk).