Document 685

The non-SWP/SW LaTeX filter

Version: 5.5 - Scientific WorkPlace & Scientific Word

The Non-SWP/SW LaTeX filter can read many TeX and LaTeX macro definitions not created with SWP or SW. Using the filter, you can successfully import many documents that were created in LaTeX, even if previously you have been unable to open them directly in SWP or SW.

The filter works on files written in LaTeX2e, but not LaTeX209 or Plain TeX.

Understanding how the filter works

The filter works by reading a .tex file in much the same way that TeX does. However, instead of translating the .tex file to a DVI file, as TeX does when you typeset a document, the filter translates the .tex file to another .tex file. The resulting file is one in which macros and certain primitive constructs have been expanded so that SWP and SW can understand them.

The filter copies the content of the original .tex file to the output .tex file, breaking it into tokens and expanding the macros until they produce text. For example, if a file contains these lines:

\def\m{xxx}
This is a test \m.

the filter will produce

This is a test XXX.

The filter can expand all tokens defined as macros, \csname, \expandafter, \noexpand, \the, \number, \if, and various other primitive constructs. Although the filter can read many macro definitions, the program may not be able to recognize every possible TeX and LaTeX construct that results. If it is unable to understand a construct, the program places the expanded macro in a gray box labeled unrecognized. You must then try to reconstruct the commands. If the original file contains macros that expand to complex constructs that the program doesn't understand, you may prefer to leave the original macro in place and unexpanded, so that you have one gray box instead of many.

The filter doesn't expand macros that SWP and SW already understand. These include letters, digits, and other characters, such as \alpha, \def, \toks, \catcode, \showboxbreadth, \kern, and many others. The filter ignores other TeX commands that aren't involved with generating output for SWP and SW, including those macros that SWP and SW already understand.

Using the filter to import a non-SWP/SW LaTeX document

You can invoke the filter from the program window or from a command prompt.

Working from the program window

  1. Place the file you want to open in a writable directory so that the program can create the necessary temporary files.

  2. From the File menu, choose Import Non-SWP/SW LaTeX.

  3. Select the file and choose Open.

    The program imports as much of the file as possible into a new document, and gives the document a name using the format filename-tmp000.tex, where 000 is a number. Thus, the first attempt to import a given file will result in a file named filename-tmp0.tex; the second attempt will yield filename-tmp1.tex; and so on.

Working from a command prompt

If you are an experienced TeX and LaTeX user, you can also invoke the filter from a command prompt. The executable (pretex.exe) is in the main program directory.

CautionUnless you are very familiar with TeX and LaTeX, do not run the non-SWP/SW LaTeX filter from a command prompt.

The command line invocation is:

pretex -i<input directory> -f<format> <input file> <output file>

where

  • The -i option specifies a directory containing macro definition files (e.g., .sty, .cls). When the filter is invoked from SWP or SW, this directory is ptdata in the program directory.

  • The -f option specifies a format file, so called because it partially mimics the functionality of the usual TeX format file. The available format is latex2swp.tex. This sets up definitions of various macros to enable the filter to convert non-SWP/SW LaTeX documents to a form that the program has a better chance of reading.

  • <input file> and <output file> are the names of the file you want to convert and the name of the converted file, respectively. Whenever the filter needs to read a file because of an \input{filename} or \usepackage{filename} command, it first looks for a file called msi-filename (that is, the filename with the prefix msi- added). If it is not found, it looks for a file with the name given, first in the directory containing the input file and then in the directory specified by the -i option. That process keeps the official LaTeX style and class files separate from those created during the filtering process. The LaTeX replacement files such as msi-article.cls are called cover files.

The command line responses list macros that the filter encounters but that are not defined.

Modifying the behavior of the filter

If you are an experienced writer of TeX and LaTeX macros, you can modify the behavior of the filter with \msi@hook commands in the cover files that prevent the filter from discarding specified constructs. If there is a construct in the original file that isn't handled by the cover files, you can add the primitive to handle it.

NoteUnless you are very familiar with TeX and LaTeX, do not attempt to program the non-SWP/SW LaTeX filter.

The filter includes several added TeX primitives. Among the most important are these:

  • \msitag(...)—The command copies the parameter to the output without further expansion.

    If you write your own format file, instead of using the latex2swp.tex file provided, you can use the command to define constructs that you don't want the filter to expand. Thus, you might write in your format file \def\alpha{\msitag{\alpha}}, which will cause \alpha to be copied to the output whenever it occurs.

    Note that this example is a common operation, and one that is already handled by the filter. The macro \msi@pass, also defined in the latex2swp.tex format file, also passes the parameter to the output file without expansion. Thus, writing \msi@pass\alpha has the same effect.

  • \msi@output—This counter controls output when recursing into included files. When the counter is set to 0, output occurs. When it is set to 1 or more, output is suppressed.

  • \msi@dollar—This counter is usually be set to zero, to suppress the output of dollar signs. Setting the counter to the ASCII value of the dollar sign (\msi@dollar='\$) can be useful when the file contains implicit dollar signs.

  • \msi@everypar—This token list parameter inserts tokens at the start of every paragraph before any that are inserted by the TeX primitive \everypar. This parameter controls the paragraph breaks without affecting the content of \everypar that may already exist.

  • \msi@everyhbox—This token list parameter inserts tokens at the start of every \hbox.

  • \msi@hook@xxxx—This macro preserves TeX primitives (xxxx) that might otherwise be discarded by the filter.

    To make the filter generate output for TeX primitives, you can write commands such as \def\msi@hook@hss{\msitag{\hss}}.

You can find examples of these primitives in use in the files in the ptdata directory in the program installation.

Last revised 06/29/06