Introduction

FrameMaker® software from Frame Technology® includes support for a markup language called MML (Maker Markup Language). You can use any standard text editor to create an MML file. Later, you can open the MML file as a FrameMaker document or import it into a FrameMaker template. In a department where different people are responsible for writing and formatting documents, writers can use MML statements to mark up manuals in progress; at the same time, graphic designers can create the formatting specifications in FrameMaker templates.

This manual documents a number of enhancements to the MML syntax that were developed by Softline International Inc. The extensions were developed for two reasons:

To keep the MML syntax current with changes that were added in Release 3.0 of FrameMaker.
To provide extensions to the MML language that would facilitate its use by developers of filters.

MML supports many formatting and layout features of FrameMaker. For example, you can use MML to specify:

Document page size and column layout (including options available with the Custom Document command).
Header and footer layouts.
Paragraph Format Catalog (including all options available in the Paragraph Format window).
Font definitions (including all options available in the Character Format
window).
Table Format Catalog (including all options available in the Table Format window).
Rule Definitions
Document text with varying character and paragraph formats.
Anchored frames containing textflows and graphics.
Markers (including all options available in the Marker window).
Cross-references.
Footnotes.
Variables.
Tables
Specify external files which contain page defintions, paragraph catalogs, font catalogs, cross-reference formats, and variable definitions in MIF format. These files are automatically merged as the document is opened in FrameMaker for the first time.

MML cannot define the following (you can add them after you open or import the MML file with FrameMaker):

Unanchored frames and graphics.
Irregular column layouts (unless the external definition file is used).
Column layouts that vary from page to page (unless the external definition file is used).
Multiple-line or multiple-font headers and footers (unless the external definition file is used).
Multiple master pages (unless the external definition file is used).

This manual contains:

General instructions for creating and using MML files.
A complete description of each MML statement.
Sample MML files.
MML error messages.

MML files

An MML file is a standard ASCII text file containing MML statements and document text. You can create the file with any standard text editor.

Important: If you use FrameMaker to create or edit an MML file, save the file as Text Only using the Save As command.

An MML filename must end with .mml. This suffix alerts FrameMaker that the file is an MML file and needs to be interpreted (by the mmltomif program) before it is imported into, or opened as, a FrameMaker document. For more information on how MML files are processed, see Appendix D of FrameMaker Reference.

After you open or import an MML file, you can modify, print, and save it using FrameMaker commands. However, any changes you make in FrameMaker are not reflected in the original MML file. Thus, if you want the MML file to serve as the master source for the document, you must make the changes to the MML file.

Using MML to create FrameMaker documents

You can use MML to:

Specify the content of a document for which formatting information is stored in a FrameMaker template.

You use a small subset of MML instructions to specify when to use paragraph formats and when to change the character format for words and phrases. You create the paragraph formats and set up the document layout in a FrameMaker template.
Specify both the content and format of a document.
You use more complex MML statements to define formatting and layout specifications in the MML file.

When you use MML to create FrameMaker documents, use two MML files to describe a document; an MML include file contains formatting information, and an MML document content file contains document text. Using two files makes it easier to correct errors. In addition, you can use one include file to create several documents with the same formatting.

If you use a FrameMaker template to specify formatting, your include file can be very brief. It lists the paragraph formats in the template's Paragraph Format Catalog and any character formats and MML macros you want to use.

If you want to keep formatting information and document content in one file, the file should contain the information that would appear in an include file followed by the information that would appear in a document content file.

Specifying document format with a FrameMaker template

The easiest way to use MML is to specify formatting information in a FrameMaker template. In addition to the template, you use a simplified include file and a document content file to specify the document text.

For a complete description of the sections in an MML file, see MML file structure. For a sample FrameMaker document created from a template, an include file, and a document content file, see Specifying document format with a FrameMaker template.

Setting up the template
In the FrameMaker template, set up the document layout and create paragraph formats.

Creating the include file
Use a standard text editor to create the include file. It should contain:

An MML identification line.
A Macro Definition section.
A <DefineTag> statement for each paragraph tag in the template. (See Paragraph statements.)
Font definitions for character format changes to be used for words or phrases in the document content file.

Creating the MML document content file
Use a standard text editor to create the document content file. It should contain:

An MML identification line.
An <Include> statement that names the MML include file. (See Control and macro statements.)
A Document Text section.

Importing the MML file into the template
To create a FrameMaker document from the MML file, use the FrameMaker New command to create a new document from a template. Then use the Import command to import the MML document content file into the document. Use the Save As command to save the resulting document under a new filename.

Specifying document format with MML

When you use an include file and a document content file to create a FrameMaker document, the include file describes document formatting; the document content file contains the document text.

For a complete description of the sections in an MML file, see MML file structure.

Creating an include file
Use a standard text editor to create an include file describing document formatting. It should contain the following sections:

An MML identification line.
Macro Definition section.
Font Definition section.
Paragraph Format Definition section.
Document Layout Description section.

Creating a document content file
Use a text editor to create the document content file. It should contain:

An MML identification line.
An <Include> statement that names the MML include file. (See Control and macro statements.)
A Document Text section.

Opening the document content file
To create a FrameMaker document from the include and document content files, open the document content file with FrameMaker.

Relative Merits of Each Approach

Users are often unclear as to when to use which approach. If you are doing relatively small documents or only have a few documents to import into FrameMaker either approach will do.

However, if have large numbers of documents to convert to FrameMaker the approach you use can save considerable manual effort during the conversion. If you can fully define your document using the MML syntax then you should use the second approach. The intial opening and saving of documents should be done using the FMBatch utility since opening and saving relatively large (more than 50 pages) can consume at least five minutes even on the fastest of processors. Setting up a batch job to open MML files and save them in FrameMaker allows you to put your time to better use while your documents are being converted.

If your documents are not fully definable in MML or you want to the document to take on a differrent format when it is opened in FrameMaker then you must prepare a template and import the document into the template. This process is even more time consuming than opening an MML document directly. FMBatch should always be used in this situation to process your files in batch mode.

Unfortunately not all platforms which support FrameMaker also support the FMBatch utility (the Apple MacIntosh for example). To increase your productivity in these situations, Softline has provided a number of MML statements which allow you to automatically include format files which you have seperately prepared in MIF format.

MML As An Automated Conversion Tool

Most FrameMaker documentation which discusses the writing of filter software encourages developers to write their filter programs to produce output in MIF format. If you are developing filter software there are a number of reasons why you should consider developing your filter to produce MML instead of MIF:

The MIF syntax is very awkward to use and requires very precise formatting of your output file. For example each line of text must be enclosed in a ``stirng'' statement.
MML allows you to output your document in a natural sequence. Various document components are in the same order that they would normally appear on the printed page. MIF requires document components to be in a special sequence that often requires extensive sorting as a part of the filter process.