File formats

There are several types of files which may be added to the whole set of VMD working files. This section describes how to format them, and where to put them.

Many types of files (particularly, C/C++/Fortran source code or header files, Latex documentation files, and shell script files) require an RCS header at the beginning of the file. This header should be placed at the very beginning, before any other text in the file. It consists of a set of comment lines which describe the name, purpose, and history of revisions to the file. This is done by using RCS keywords embedded in the comments, which are replaced by the proper values when the file is checked out, and by having a section in the comments for a basic description of the purpose of the file. Templates of RCS headers for each of the different file types which require them are provided in the directory RCS. When a new file is created, a copy of the relevant header template should be placed at the top of the file, and the file description inserted as comments in the section of the template provided for this purpose. The descriptions below of how to format each file also describe the name of the RCS template to use.

• Documentation text files
  The documentation for VMD is in Latex, and files should have a .tex extension. The files should all be placed in the doc directory, be put in the RCS, and have the RCS header RCS/RCSheader.tex prepended.

• Documentation image files
  Image files for the documentation should be placed in the directory doc/pictures, which should be a link to a directory writable by all people working on VMD. These files are NOT to be placed in the RCS, due to the problems with how RCS stores files.

• Source code files
  All source code files, either C, C++, or Fortran, should be placed in the src directory, along with all header files. These files should be entered into the RCS; a copy of the RCS template RCS/RCSheader.h should go at the start of header files, and a copy of RCS/RCSheader.c should be placed at the start of C and C++ source files. Fortran files should begin with a copy of the file RCS/RCSheader.f.

  All header files should bracket their text between a #ifndef ... #endif pair, and define a macro to indicate the header file has been processed. For example, right after the RCS header should come the text

  #ifndef DISPLAYDEVICE_H
  #define DISPLAYDEVICE_H
  $\vdots$
  #endif

• Shell script files
  Files which are sh or csh scripts should be placed, most likely, in either the main working directory or the bin directory. These should be entered into the RCS, and have the RCS header RCS/RCSheader.make placed at the beginning. When adding such files to the RCS, care must be taken to have the comment leader for the RCS file set properly. This is done by using the command-line switch

  -c"# "

  added to the options to the rcs program (described in section 10).

• Data files
  Files which contain data or configuration parameters needed by VMD should be placed in the data directory, and be put in the RCS. In most cases, the "#" symbol is the comment character, and so they can have the same type of RCS header as used for shell scripts. This is true, for example, for the file data/.vmdrc, which is in the RCS.