&nxtranslate is designed to be the anything to NeXus converter. To this end it is built in a modular fashion so the types of files that can be read from can vary between different installations. The reason for this is to minimize the size of the executable. In line with this modularity is the author's desire to work with users of &nxtranslate to add abilities, clarify documentation, and fix bugs. &nxtranslate operates by parsing a translation file to create a NeXus file. The translation file contains the organization of the resulting NeXus file, data, and instructions on other how to obtain data using retrievers. This book is organized into chapters with an increasingly sophisticated user in mind. The chapter you are reading is a general overview on how to use &nxtranslate with an existing installation and existing translation files. Chapter 2 is aimed at writing translation files and chapter 3 will discuss in more detail what retrievers are and how to write them. This section will explain the various command line arguments to &nxtranslate . For all of the examples here the name of the translation file is test.xml. nxtranslate --help -o outputfile --hdf4 --hdf5 -D macro translationfile --append outputfile First to get the easy arguments out of the way. Typing just nxtranslate will give a usage statement similar to what is above. nxtranslate --help will print the full help message. Generally speaking this is not what you are interested in. The minimum argument list for &nxtranslate to do anything other than print the usage message is to supply a translation file. The cannonical example is bash$ nxtranslate test.xml This tells &nxtranslate to parse the file test.xml and produce a NeXus file called test.nxs using the default base format (base format is discussed below). To change the name of the output file use the "-o" switch. bash$ nxtranslate test.xml -o my_file.nxs The only difference with the previous example is that the resulting NeXus file is my_file.nxs. The switches "--hdf4" and "--hdf5" are mutually exclusive and take no arguments. These are used to select the base format for the output file. NeXus is actually written using the Hierarchical Data Format (HDF) which is produced by the National Center for Supercomputer Applications (NCSA). There are two (incompatible) versions of HDF that have widespread use that are commonly referred to as HDF4 and HDF5. Part of the purpose of the NeXus API is to hide the difference between the different bases. In this spirit &nxtranslate only exposes the bases with these switches. To create two files with the same structure and diffent bases is easy. bash$ nxtranslate --hdf4 test.xml -o my_hdf4.nxs bash$ nxtranslate --hdf5 test.xml -o my_hdf5.nxs The last command line argument is the "-D" switch. This switch allows for substituting strings in the the translation file for the &mime-type , &source , and &location attributes in the translation file. To get a better understanding of what this means see Chapter 2. For now it is enough to show an example. bash$ nxtranslate test.xml -DFILE1=old_nexus.nxs This example assumes that there is a macro FILE1 in the translation file. &nxtranslate will convert the string FILE1 into old_nexus.nxs before creating the resulting NeXus file. This allows for a script to convert an entire directory of files to look like (using python) listing=glob.glob("*.nxs") for file in listing: os.system("nxtranslate converter.xml -DFILE1=%s -o new_%s" % (file,file)) This bit of code (plus the proper import statements) would use the translation file converter.xml to translate all *.nxs in the current working directory.