Document 421

Using shells and typesetting specifications from outside sources

Version: 3.x, 4.x, 5.x - Scientific WorkPlace & Scientific Word

Although we provide many shells and typesetting specifications with SWP and SW, you may need to add specifications that you obtain from a publisher or from some other source for TeX and LaTeX files, such as the Comprehensive TeX Archive Network (CTAN). The CTAN directory on your program CD contains the typesetting specifications and files as distributed on CTAN, but only those files needed for typesetting are installed with the program.

NoteWe have tested the shells and specifications provided with our products, but we can't guarantee that other specifications will work with our products, nor can we guarantee that the documents you create with those specifications will behave as the specifications advertise. Further, we don't support documents created with specifications not provided with our products.

Nonetheless, if you do add typesetting specifications, it's important to install them correctly. Please don't attempt to add specifications if you aren't familiar with TeX and LaTeX.

NoteWe do not provide Technical Support services for shells and documents created with typesetting specifications obtained from other sources.

Adding LaTeX typesetting specifications to your installation involves these steps:

  1. Place the specification files in an appropriate directory.

  2. Complete any required installation steps.

  3. Test the specifications.

  4. Open the sample documents, if any.

  5. Create or modifying a style (.cst) file, if necessary.

  6. Create a shell for the typesetting specifications.

  7. Modify the program interface (optional)

  8. Create a new document with the shell.

We illustrate these instructions by showing how to install the specifications contained in \CTAN\macros\latex\contrib\supported\uaclasses on your program CD. These files adhere to the typesetting requirements for theses and dissertations at the University of Arizona. These instructions assume you have installed SWP in the directory c:\swp55. If you're using SW, a different directory, or a different version, substitute the correct directory path in the instructions.

Step One: Place the typesetting specification files in an appropriate directory

A set of LaTeX specifications can involve several files: cls, .clo, and .sty files as well as installation files (.ins), sample documents, and readme files, which often contain installation instructions.

To ensure the new specifications are available to TrueTeX, place the files anywhere in the TCITeX\TeX directory of your SWP or SW program directory. We suggest that for each set of specifications you create a new subdirectory within TCITeX\TeX. If you obtained the files from CTAN, follow the directory structure used there.

  1. Search your installation to make certain an older version of the specifications is not installed. If you find an older version, rename it.

  2. Create a new subdirectory for the specifications within TCITeX\TeX.

    For this example, create a new subdirectory called uaclasses in the existing directory c:\swp50\TCITeX\tex\latex\contrib\supported.

  3. Move all the typesetting specification files to the new directory.

Step Two: Complete any required installation steps

  1. Follow the instructions in the accompanying readme file, if any.

  2. If you must process any files through LaTeX, use the TrueTeX Formatter outside SWP or SW:

    1. From the Windows Start menu, select the SWP or SW program submenu and then select TrueTeX Formatter.

    2. In the Open TeX File dialog box, specify the directory containing the specification files.

    3. In the File name box, type *.* to display all files in the directory.

    4. Select the file you want to process and choose OK.

Processing the files often creates additional files required by the specifications. In the example, the readme file says to run LaTeX on two files: ua-classes.dtx and ua-classes.ins.

Step Three: Test the specifications

Specifications can have associated sample documents. Test the sample documents by running them through LaTeX before you try to open them in SWP or SW.

  1. If a sample document is provided as a .tex file, process it through the TrueTeX Formatter outside SWP or SW to create a DVI file.

    In the example, both ua-example.tex and ua-example.dvi are available. To make sure the installation is working, copy and rename ua-example.tex as newua-example.tex, and then process the renamed file through the TrueTeX Formatter to create a new DVI file.

  2. Preview the DVI file with the TrueTeX previewer:

    1. From the Windows Start menu, select the SWP or SW program submenu and then select TrueTeX Previewer.

    2. From the File menu, choose Open.

    3. In the Open DVI File dialog box, specify the directory containing the specification files.

    4. Select the file you want to process and choose OK.

Step Four: Open the sample documents in SWP or SW

Opening sample documents created with native LaTeX can have unpredictable results in SWP and SW. The program may not handle the documents correctly and might even crash while it tries to load the file. Make a copy of the .tex files for the sample documents before you attempt to open them.

  1. Make a copy of the .tex file.

  2. Choose fileopen.wmf or, from the File menu, choose Open.

  3. Select the subdirectory created in Step One.

  4. Select the copy of the sample document and choose OK.

  5. If the program displays a message indicating that an appropriate .cst file was not found, choose Yes to load the document using a default .cst file.

    The program chooses a default style from the appropriate Styles directory.

  6. Typeset preview the document and compare the results to those obtained when you previewed the DVI file in Step Three.

    Similar results indicate a successful installation. If the document fails to compile, isolate and resolve the LaTeX errors.

Step Five: Create and modify a new .cst file

When you open a document, the program uses the associated .cst file to display the document on the screen and to reflect the available environments, objects, and tags. (The .cst file has no effect on the document's typeset appearance.)

Create a .cst file for the new specifications. You can probably copy and modify an appropriate existing file successfully. If the new specifications are similar to an existing document class and include no new objects, you can probably use any .cst file for a similar document class. The .cst files are installed in the Styles directory of your program installation or in one of its subdirectories. However, if the new specifications implement a new base document class, you need a new .cst file so that the program can display documents created with the new specifications. The process of creating and modifying the .cst file differs for earlier versions of the program

In the example, the uaclasses specifications represent a new base document class called ua-thesis, so a new .cst file is required. Save it in a new subdirectory in the Styles directory and then modify it so that the screen display reflects the new document elements, objects, and environments implemented by the typesetting specifications. Finally, modify the sample document to reflect the new .cst file so that it can be opened successfully in SWP.

Creating and modifying the .cst file in Version 4 and later

  1. Use an ASCII editor to open the .cls file associated with the new typesetting specification.

  2. Search for a statement that indicates the base document class for the new specifications.

  3. In the Styles directory of your program installation, find a .cst file that corresponds to the document class basis.

  4. Rename the file using the same name as the document class name and save it in the Styles directory, either in a new subdirectory or in the [Special] subdirectory.

  5. If the new specifications have an environment that isn't contained in the .cst file, search for another .cst file that contains a similar object and copy the object to the new .cst file.

  6. When you have added all necessary environments, save the new .cst file.

    NoteIf the new subdirectory contains only one .cst file, you don't have to change the name of the .cst file in the sample document.

Creating and modifying the .cst file in Version 3.5 and earlier

Look in the .cls file for new environments, theorem objects, and front matter elements. These objects are often signalled with \def or \newcommand statements. If you can find another .cst file that reflects the object, you can copy the object to the new .cst file.

In the example, the ua-thesis specifications add an abstract to the standard LaTeX report class, so the .cst file must reflect the new object. We searched other .cst files were searched to find an abstract object, copy it, and add it to ua-thesis.cst. The resulting .cst file is Styles\ua-thesis\ua-thesis.cst, on the program CD.

  1. Use an ASCII editor to open the .cls file associated with the new typesetting specification.

  2. Search for a statement that indicates the base document class for the new specifications.

    In the example, the .cls file indicates that the ua-thesis document class derives from the standard LaTeX report document class.

  3. In the Styles directory of your program installation, find a .cst file that corresponds to the document class basis.

    In the example, use report.cst in the Styles\report directory.

  4. Rename the file appropriately and save it in a new directory.

    In the example, rename the copy as Styles\ua-thesis\ua-thesis.cst.

Changing the sample document so that it will use the new .cst file

  1. Change the name of the .cst file:

    1. Open the file in SWP or SW.

    2. From the File menu, choose Style.

    3. Choose Advanced.

    4. In the Style File box, browse to the directory containing the new .cst file.

    5. Select the file and choose OK.

  2. Change the appearance of the tag environments in the document window, if necessary:

    • In Version 4 or later, use the Appearance command on the Tag menu to change the tag attributes.

      or

    • In earlier versions, use an ASCII editor to modify the tag attributes.

    RememberModifications to the .cst file have no effect on the typeset appearance of your document.

Step Six: Create a new shell document for the typesetting specifications

Use the sample document as the shell document, modifying it as you wish.

  1. Open the .tex file for the sample document.

  2. Make any changes you want to the file.

  3. Save the file as a shell:

    1. If you're using Version 4 or later, from the File menu, choose Export Document.

      or

      If you're using Version 3.5 or earlier, from the File menu, choose Save As.

    2. In the Save in box, specify the directory for the shell.

      Choose an appropriate subdirectory within the Shells directory of your program installation. In the example, the shell was saved as Thesis - University of Arizona Thesis.shl in the Shells\Other Documents directory.

    3. In the File name box, type the name of the shell.

    4. In the Save as type box, select Shell (*.shl).

    5. Choose Save.

Step Seven: Modify the program interface (optional)

So you can work with the new specifications from the Options and Packages dialog box, you can modify the interface in two steps:

Step Eight: Create a new document

  1. Create a new document with the shell:

    1. From the File menu, choose New.

    2. Choose the new shell file and choose OK.

      The program creates a new file based on the new shell document and its style and typesetting specifications. It gives the file the temporary name of Untitled. I

See also

Last revised 08/18/05

This document was created with Scientific WorkPlace.