Table of Contents * Previous Chapter * Next Chapter

Miftran Users Guide: 2 Usage

2 Usage

This chapter describes how to run miftran.

2.1 Requirements

In order to run miftran, you will need two things (other than miftran itself):

  1. A MIF file to use as input. This is normally specified in the rc file, but can also be given on the command line
  2. An rc file to control the translation. The default is `miftran.rc' in the current directory, or you can use the MIFTRANRC environment variable, or the -rc command line option. See Chapter 3, `The RC File' on page 6.

You make your MIF file from Frame using the Save As command. You create your rc file using your favorite text editor.

Miftran is designed to accept a single MIF file as input, but it can produce multiple output files. Thus you can create a separate output file for each chapter of your document (or each section, or whatever else you select). This is appropriate for hypertext browsers, where each chunk is typically considerably smaller than what goes into a MIF file (such as this entire document).

If your document is saved in multiple MIF files, you can concatenate them all together into one bug MIF file and run that through miftran. This may or may not work, depending on your MIF files. You'll just have to try it to find out.

The simplest way to use miftran is to create a directory in which to produce the output files, and to place your rc file into that directory. You can put a simple makefile into the directory so that you don't have to remember how to run miftran; then you can simply cd into that directory and type `make' in order to update your HTML files.

2.2 Command Line Options

Miftran includes only a few command line options, mainly for debugging. The debugging command line options (-cmd, -fmt, -lex, -sub, -tran) allow you to control which phases of the translation are performed by miftran (see Section 1.1, `The Translation Process' on page 2). Other options are:

An additional argument not starting with `-' is assumed to be an input filename. A single `-' specifies that input is to come from stdin. Input will also be taken from stdin if no input file is specified (either on the command line or in the rc file).

There are no command line options to specify output files. The output file or files are normally specified in the rc file (see Chapter 3, `The RC File' on page 6), and are processed during the fmt stage of the translation (see Section 1.1, `The Translation Process' on page 2). Thus if you use one of the debugging command line options to get early output, it will always come to stdout.

2.3 Environment

Miftran uses the following environment variables:

2.4 Postprocessing

Miftran makes a single pass through the document and produces one or more output files. In order to properly handle forward cross references, a second pass of some sort needs to be made. This is handled by an external script, called fixref, which uses a data file produced by miftran in order to update the cross references in the HTML files. Control over production of the data file is contained in the miftran rc file.

The fixref script is normally included as part of the make procedure as defined in the Makefile for the HTML documents.

2.5 The Include Directory

Miftran comes with a set of rc files that can be included by reference in your rc file. This makes it simpler to create your customized rc file, and makes it easier to incorporate bug fixes and enhancements to the rc files when a new version of miftran is released.

The standard miftran include directory is miftran/mtinc, where miftran is the directory in which the miftran kit has been installed. You can reference this directory in the miftran command line by using the -I command line option. Then you can use the <include> command in your rc file to reference any of the standard rc files from the include directory.

Table of Contents * Previous Chapter * Next Chapter