Macromedia FrameMaker - 12.0 User Guide

ADOBE® FRAMEMAKER® 12

STRUCTURED APPLICATION DEVELOPER REFERENCE

© 2014 Adobe Systems Incorporated and its licensors. All rights reserved.

Structured Application Developer Reference Online Manual

If this guide is distributed with software that includes an end-user agreement, this guide, as well as the software
described in it, is furnished under license and may be used or copied only in accordance with the terms of such license.
Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or
transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written
permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law
even if it is not distributed with software that includes an end-user license agreement.

The content of this guide is furnished for informational use only, is subject to change without notice, and should not be
construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility
or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

Please remember that existing artwork or images that you may want to include in your project may be protected under
copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of
the copyright owner. Please be sure to obtain any permission required from the copyright owner.

Any references to company names in sample templates are for demonstration purposes only and are not intended to
refer to any actual organization.

Adobe, the Adobe logo, Acrobat, Distiller, Flash, FrameMaker, Illustrator, PageMaker, Photoshop, PostScript, Reader,
Garamond, Kozuka Mincho, Kozuka Gothic, MinionPro, and MyriadPro are trademarks of Adobe Systems Incorporated.

Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries. Solaris is a trademark or registered trademark of Sun Microsystems, Inc. in the
United States and other countries. UNIX is a trademark in the United States and other countries, licensed exclusively
through X/Open Company, Ltd. SVG is a trademark of the World Wide Web Consortium; marks of the W3C are
registered and held by its host institutions MIT, INRIA, and Keio. All other trademarks are the property of their respective
owners.

This product contains either BISAFE and/or TIPEM software by RSA Data Security, Inc.

This product contains color data and/or the Licensed Trademark of The Focoltone Colour System.

PANTONE® Colors displayed in the software application or in the user documentation may not match PANTONE­identified standards. Consult current PANTONE Color Publications for accurate color. PANTONE® and other Pantone, Inc.
trademarks are property of Pantone, Inc. © Pantone, Inc. 2003. Pantone, Inc. is the copyright owner of color data and/or
software which are licensed to Adobe Systems Incorporated to distribute for use only in combination with Adobe
Illustrator. PANTONE Color Data and/or Software shall not be copied onto another disk or into memory unless as part of
the execution of Adobe Illustrator software.

Software is produced under Dainippon Ink and Chemicals Inc.'s copyrights of color-data-base derived from Sample
Books.

This product contains ImageStream® Graphics and Presentation Filters Copyright ©1991-1996 Inso Corporation and/or
Outside In® Viewer Technology ©1992-1996 Inso Corporation. All Rights Reserved.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Certain Spelling portions of this product is based on Proximity Linguistic Technology. ©Copyright 1990 Merriam­Webster Inc. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc.
Burlington, New Jersey USA. ©Copyright 2003 Franklin Electronic Publishers Inc.©Copyright 2003 All rights reserved.
Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. Legal Supplement
©Copyright 1990/1994 Merriam-Webster Inc./Franklin Electronic Publishers Inc. ©Copyright 1994 All rights reserved.
Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990/
1994 Merriam- Webster Inc./Franklin Electronic Publishers Inc. ©Copyright 1997All rights reserved. Proximity
Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA ©Copyright 1990 Merriam­Webster Inc. ©Copyright 1993 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc.
Burlington, New Jersey USA. ©Copyright 2004 Franklin Electronic Publishers Inc. ©Copyright 2004 All rights reserved.

Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1991 Dr.
Lluis de Yzaguirre I Maura ©Copyright 1991 All rights reserved. Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Munksgaard International Publishers Ltd. ©Copyright
1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey
USA. ©Copyright 1990 Van Dale Lexicografie bv ©Copyright 1990 All rights reserved. Proximity Technology A Division
of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1995 Van Dale Lexicografie bv
©Copyright 1996 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington,
New Jersey USA. ©Copyright 1990 IDE a.s. ©Copyright 1990 All rights reserved. Proximity Technology A Division of
Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1992 Hachette/Franklin Electronic
Publishers Inc. ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers,
Inc. Burlington, New Jersey USA. ©Copyright 1991 Text & Satz Datentechnik ©Copyright 1991 All rights reserved.
Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2004
Bertelsmann Lexikon Verlag ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2004 MorphoLogic Inc. ©Copyright 2004 All rights reserved.
Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990
William Collins Sons & Co. Ltd. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin
Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1993-95 Russicon Company Ltd. ©Copyright 1995
All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA.
©Copyright 2004 IDE a.s. ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA. The Hyphenation portion of this product is based on Proximity Linguistic
Technology. ©Copyright 2003 Franklin Electronic Publishers Inc.©Copyright 2003 All rights reserved. Proximity
Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1984 William
Collins Sons & Co. Ltd. ©Copyright 1988 All rights reserved. Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Munksgaard International Publishers Ltd. ©Copyright
1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey
USA. ©Copyright 1997 Van Dale Lexicografie bv ©Copyright 1997 All rights reserved. Proximity Technology A Division
of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1984 Editions Fernand Nathan
©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington,
New Jersey USA. ©Copyright 1983 S Fischer Verlag ©Copyright 1997 All rights reserved. Proximity Technology A
Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1989 Zanichelli ©Copyright 1989
All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA.
©Copyright 1989 IDE a.s. ©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Espasa-Calpe ©Copyright 1990 All rights reserved.
Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1989
C.A. Stromberg AB. ©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA.

Portions of Adobe Acrobat include technology used under license from Autonomy, and are copyrighted.

Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Notice to U.S. government end users. The software and documentation are “Commercial Items,” as that term is defined
at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software
Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48
C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and
Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as
Commercial items and (b) with only those rights as are granted to all other end users pursuant to the terms and
conditions herein. Unpublished-rights reserved under the copyright laws of the United States. For U.S. Government End
Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of
Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38
USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1
through 60-60, 60-250, and 60- 741. The affirmative action clause and regulations contained in the preceding sentence
shall be incorporated by reference.

Contents

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 1 Structure Application Definition Reference . . . . . . . . . . . 9

Contents of an application definition file . . . . .9

Define an application . . . . . . . . . . .9

Providing default information . . . . . . . 11

Specifying the character encoding for SGML files . 11

Specifying conditional text output . . . . . . 13

Specifying a DOCTYPE element . . . . . . . 13

Specifying a DTD . . . . . . . . . . . 14

Specifying entities . . . . . . . . . . . 14

Specifying entities through an entity catalog . 15

Specifying the location of individual entities . 16

Specifying names for external entity files. . . 17

Specifying public identifiers . . . . . . . 18

Specifying a search path for external entity files 19

Specifying external cross reference behavior . . 20

Change file extension to .XML . . . . . . 20

Try alternative extensions . . . . . . . . 21

Specifying filename extensions . . . . . . . 21

Enabling namespaces . . . . . . . . . . 22

Specifying a read/write rules document . . . . 22

Specifying a search path for included files in rules

documents . . . . . . . . . . . . . 22

How FrameMaker searches for rules files. . . 23

Specifying a Schema for XML . . . . . . . 23

Specifying an SGML declaration . . . . . . 24

Managing CSS import/export and XSL transformation
24

How the Stylesheets element affects CSS

generation. . . . . . . . . . . . . 24

How the Stylesheets element affects CSS import 25

How the Stylesheets element affects XSL

transformation . . . . . . . . . . . 25

Specifying a FrameMaker template . . . . . 26

Specifying a structure API client. . . . . . . 27

Specifying the character encoding for XML files . 27

Display encoding . . . . . . . . . . 28

Encoding of CSS files . . . . . . . . . 29

Exporting XML . . . . . . . . . . . . 29

Limiting the length of a log file . . . . . . . 30

Mapping graphic notations to file types . . . . 30

Chapter 2 Read/Write Rules Summary . . . . . . . . . . . . . . . . . 31

All Elements . . . . . . . . . . . . . 31

Attributes . . . . . . . . . . . . . . 32

Books . . . . . . . . . . . . . . . 33

Cross-references . . . . . . . . . . . . 33

Entities . . . . . . . . . . . . . . . 34

Equations . . . . . . . . . . . . . . 34

Structured Application Developer Reference 1

Footnotes . . . . . . . . . . . . . . 35

Graphics . . . . . . . . . . . . . . 35

Markers . . . . . . . . . . . . . . . 36

Processing instructions . . . . . . . . . 37

Markup documents . . . . . . . . . . . 37

Tables . . . . . . . . . . . . . . . 38

Text . . . . . . . . . . . . . . . . 39

Text insets . . . . . . . . . . . . . . 39

Variables . . . . . . . . . . . . . . 39

Chapter 3 Read/Write Rules Reference . . . . . . . . . . . . . . . . . 41

anchored frame . . . . . . . . . . . . 41

attribute . . . . . . . . . . . . . . 44

character map. . . . . . . . . . . . . 47

convert referenced graphics . . . . . . . . 49

do not include dtd . . . . . . . . . . . 50

do not include sgml declaration. . . . . . . 51

do not output book processing instructions. . . 51

drop . . . . . . . . . . . . . . . . 51

drop content . . . . . . . . . . . . . 53

element . . . . . . . . . . . . . . . 54

end vertical straddle . . . . . . . . . . 57

entity. . . . . . . . . . . . . . . . 59

entity name is . . . . . . . . . . . . . 61

equation . . . . . . . . . . . . . . 63

export dpi is . . . . . . . . . . . . . 64

export to file . . . . . . . . . . . . . 67

external data entity reference . . . . . . . 69

include sgml declaration . . . . . . . . . 97

insert table part element . . . . . . . . . 98

is fm attribute. . . . . . . . . . . . . 101

is fm char . . . . . . . . . . . . . . 105

is fm cross-reference element . . . . . . . 107

is fm element . . . . . . . . . . . . . 108

is fm equation element . . . . . . . . . 109

is fm footnote element. . . . . . . . . . 110

is fm graphic element . . . . . . . . . . 111

is fm marker element . . . . . . . . . . 112

is fm property. . . . . . . . . . . . . 114

is fm property value. . . . . . . . . . . 122

is fm reference element . . . . . . . . . 125

is fm rubi element . . . . . . . . . . . 127

is fm rubi group element . . . . . . . . . 128

is fm system variable element . . . . . . . 129

is fm table element . . . . . . . . . . . 130

external dtd . . . . . . . . . . . . . 70

facet . . . . . . . . . . . . . . . . 72

fm attribute . . . . . . . . . . . . . 74

fm element. . . . . . . . . . . . . . 75

fm marker . . . . . . . . . . . . . . 76

fm property . . . . . . . . . . . . . 78

fm variable . . . . . . . . . . . . . . 89

fm version . . . . . . . . . . . . . . 90

generate book . . . . . . . . . . . . 91

implied value is . . . . . . . . . . . . 94

include dtd. . . . . . . . . . . . . . 96

is fm table part element . . . . . . . . . 132

is fm text inset . . . . . . . . . . . . 133

is fm value . . . . . . . . . . . . . . 135

is fm variable . . . . . . . . . . . . . 137

is processing instruction . . . . . . . . . 138

line break . . . . . . . . . . . . . . 138

marker text is . . . . . . . . . . . . . 140

notation is . . . . . . . . . . . . . . 141

output book processing instructions . . . . . 143

preserve fm element definition . . . . . . . 144

preserve line breaks . . . . . . . . . . 145

2

processing instruction . . . . . . . . . . 147

table ruling style is . . . . . . . . . . . 157

proportional width resolution is. . . . . . . 148

put element . . . . . . . . . . . . . 149

reader . . . . . . . . . . . . . . . 149

reformat as plain text . . . . . . . . . . 150

reformat using target document catalogs . . . 151

retain source document formatting . . . . . 152

specify size in . . . . . . . . . . . . . 153

start new row . . . . . . . . . . . . . 155

start vertical straddle . . . . . . . . . . 156

unwrap . . . . . . . . . . . . . . . 158

use processing instructions . . . . . . . . 160

use proportional widths . . . . . . . . . 160

value . . . . . . . . . . . . . . . 161

value is . . . . . . . . . . . . . . . 163

write structured document . . . . . . . . 163

write structured document instance only . . . 163

writer . . . . . . . . . . . . . . . 164

Chapter 4 Conversion Tables for Adding Structure to Documents . . . . . .167

How a conversion table works . . . . . . . 167

Setting up a conversion table . . . . . . . 168

Generating an initial conversion table. . . . 169

Setting up a conversion table from scratch . . 170

Updating a conversion table . . . . . . . 170

Adding or modifying rules in a conversion table . 171

About tags in a conversion table . . . . . 171

Specifying the root element for a structured

document . . . . . . . . . . . . . 172

Identifying a document object to wrap . . . 173

Identifying an element to wrap . . . . . . 174

Identifying a sequence to wrap . . . . . . 175

Providing an attribute for an element. . . . 177

Using a qualifier with an element . . . . . 177

Handling special cases . . . . . . . . . . 179

Promoting an anchored object . . . . . . 179

Flagging format overrides . . . . . . . 180

Wrapping untagged formatted text . . . . 180

Nesting object elements . . . . . . . . 181

Building table structure from paragraph format tags
182

Testing and correcting a conversion table . . . 182

Chapter 5 CSS to EDD Mapping . . . . . . . . . . . . . . . . . . . .185

CSS Font Properties . . . . . . . . . . . 185

CSS text properties . . . . . . . . . . . 188

CSS color and backgrounds properties . . . . 189

CSS Formatting Model . . . . . . . . . . 190

CSS Pagination Properties . . . . . . . . 193

CSS generated content, automatic numbering, and

lists . . . . . . . . . . . . . . . . 194

CSS Tables . . . . . . . . . . . . . . 196

CSS Selectors . . . . . . . . . . . . . 197

Chapter 6 XML Schema to DTD Mapping . . . . . . . . . . . . . . . .199

Schema location . . . . . . . . . . . . 199

Namespace and Schema location attributes. . 200

Simple type mapping . . . . . . . . . . 200

Structured Application Developer Reference 3

Attributes of simple type elements . . . . 201

Complex type mapping . . . . . . . . . 202

Group . . . . . . . . . . . . . . 202

Sequence . . . . . . . . . . . . . 202

Choice . . . . . . . . . . . . . . 203

All . . . . . . . . . . . . . . . . 204

Named complex types . . . . . . . . . 204

Named attribute groups . . . . . . . . 205

Abstract elements . . . . . . . . . . 206

Mixed content models . . . . . . . . . 207

Supported Schema features . . . . . . . . 208

Defaults. . . . . . . . . . . . . . 208

Any . . . . . . . . . . . . . . . 208

Extension and restriction of complex types . . 209

Include, import, and redefine . . . . . . 209

Unsupported Schema features . . . . . . . 211

Chapter 7 The CALS/OASIS Table Model. . . . . . . . . . . . . . . . .213

FrameMaker properties that DO NOT have

corresponding CALS attributes . . . . . . . 213

Element and attribute definition list declarations . 214

Element structure . . . . . . . . . . . 216

Attribute structure . . . . . . . . . . . 217

Inheriting attribute values . . . . . . . 217

Orient attribute . . . . . . . . . . . 217

Straddling attributes . . . . . . . . . 217

Chapter 8 Read/Write Rules for the CALS/OASIS Table Model . . . . . . . .219

Chapter 9 SGML Declaration . . . . . . . . . . . . . . . . . . . . .223

Text of the default SGML declaration . . . . . 223

SGML concrete syntax variants . . . . . . . 225

Unsupported optional SGML features. . . . . 226

Chapter 10 ISO Public Entities . . . . . . . . . . . . . . . . . . . .227

What you need to use ISO public entities. . . . 228

Entity declaration files . . . . . . . . . 229

Entity read/write rules files . . . . . . . 229

What happens with the declarations and rules. . 232

Chapter 11 Character Set Mapping . . . . . . . . . . . . . . . . . .235

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

4

Before You Begin

This developer reference and its associated developer guide are for anybody who develops
structured FrameMaker® templates and XML or SGML applications. They are not written for end
users who author structured documents that use such templates and applications.

XML and SGML

FrameMaker can read and write XML (Extensible Markup Language) and SGML (Standard
Generalized Markup Language) documents. XML and SGML are both document markup
languages, and FrameMaker handles these markup languages in similar ways. However, there are
differences between the two, and this manual covers these differences whenever necessary.

When discussing the similarities between them, this manual refers to XML and SGML data as
markup data or markup documents. Otherwise, the manual refers to XML and SGML specifically to
draw attention to the differences between these markup languages. The majority of new
structured documentation projects are XML based, therefore XML now takes precedence over
SGML where necessary.

Developing structured FrameMaker templates

End users of FrameMaker can read, edit, format, and write structured documents—the structure
is represented by a hierarchical tree of elements. Each structured document is based on a
template that contains a catalog of element definitions. Each element definition can describe the
valid contexts for an element instance, and the formatting of element instances in various
contexts.

To support these end users, you create the catalog and accompanying structured template.

Developing XML and SGML applications

When FrameMaker reads markup data, it displays that data as a formatted, structured document.
When the software saves a structured FrameMaker document, the software can write the
document as XML or SGML.

For the end user, this process of translation between FrameMaker documents and markup data is
transparent and automatic. However, for most XML or SGML document types the translation
requires an XML or SGML application to manage the translation. You develop this application to
correspond with specific document types. When your end user opens a markup document with a
matching document type, FrameMaker invokes the appropriate structure application. If there is no

Structured Application Developer Reference 5

match for a document type, the user can choose the application to use, or open the markup
document with no structure application.

A structure application primarily consists of:

• A structured template

• DTD or schema

• Read/Write rules (described in this manual)

• XSLT style sheets for pre and post process transformations (if necessary)

• An XML and SGML API client (if necessary) developed with the Frame® Developer’s Kit (FDK).

Prerequisites

The following topics, which are outside the scope of this manual, are important for you to
understand before you try to create a structured template or structure application:

• Structured document authoring in FrameMaker

• XML or SGML concepts and syntax, including how to work with a document type definition

• FrameMaker end-user concepts and command syntax

• FrameMaker template design.

In creating some XML or SGML applications, you may also need to understand the following:

• XSLT 1.0

• C programming

• FDK API usage.

If your application requires only the special rules described in this manual to modify the default
behavior of FrameMaker, you do not need programming skills. However, if you need to create an
XML and SGML API client to modify this behavior further, you need to program the client in C,
using the FDK. This manual does not discuss the creation of XML and SGML API clients. For this
information, see the Structure Import/Export API Programmer’s Guide.

Using FrameMaker documentation

FrameMaker comes with a complete set of end-user and developer documentation with which
you should be familiar. You can access the FrameMaker guides from the FrameMaker help and
support page, http://www.adobe.com/support/framemaker/.

If you use the Frame Developer’s Kit in creating your structure application, you’ll also need to be
familiar with the FDK documentation set.

Before You Begin 6

Using this manual

This manual provides detailed reference information for application rules and properties. It can be
used in conjunction with the Structure Application Developer Guide. It does not currently include
EDD reference information. All EDD descriptive and reference information will be found in the
Developer Guide.

Typographical conventions

Monospaced font Literal values and code, such as XML, SGML, read/write

Italics Variables or placeholders in code. For example, in

Blue text A hyperlink you can click to go to a related section in this

Sans-serif bold The names of FrameMaker User Interface objects (menus,

rules, filenames, and pathnames.

name="myName", the text myName represents a value you
are expected to supply. Also indicates the first occurrence
of a new term.

book or to a URL in your web browser.

menu items, and buttons). The > symbol is used as
shorthand notation for navigating to menu items and sub
menus. For example, Element > Validate... refers to the

Validate... item in the Element menu.

Using other FrameMaker documentation

The Using FrameMaker makes up the primary end-user documentation for this product. It explains
how to use the FrameMaker authoring environment for both structured and unstructured
documents. It also explains how to create templates for your documents.

In creating a structured template, you can refer to this manual for information on how your end
user interacts with the product and how to create a formatted template.

New features and changes in release 12(including those for structure applications and structured
documents) are listed and briefly described in the FrameMaker Getting Started Guide.

You will also find a range of other online documents from the FrameMaker help and support page,
http://www.adobe.com/support/framemaker/.

Structured Application Developer Reference 7

Using FDK manuals

If you create an XML and SGML API client for your XML or SGML application, you’ll need to be
familiar with the FDK. FDK documentation is written for developers with C programming
experience.

• FDK Programmer’s Guide is your manual for understanding FDK basics. This manual describes

how to use the FDK to enhance the functionality of FrameMaker and describes how to use the
FDK to work with structured documents. To make advanced modifications to the software’s
default translation behavior, refer to the Structure Import/Export API Programmer’s Guide.)

• FDK Programmer’s Reference is a reference for the functions and objects described in the FDK

Programmer’s Guide.

• Structure Import/Export API Programmer’s Guide explains how to use the FDK to make advanced

modifications to the software’s default behavior for translation between markup documents
and FrameMaker documents. This manual contains both descriptive and reference information.

For information on other FDK manuals, see “Using Frame Developer Tools” in the FDK

Programmer’s Guide.

Before You Begin 8

1

Structure Application Definition Reference 1

This chapter provides a comprehensive reference for all application properties that can be defined
in a structure application definition file.

Contents of an application definition file

The highest-level element in an structapps.fm file is StructuredSetup. That element’s
first child must be Version, to indicate the FrameMaker version. The Version element is
followed by zero or more SGMLApplication or XMLApplication elements, each of which
defines the pieces of a structure application. Finally, there can be an optional Defaults element,
which specifies information used unless overridden for a particular application.

The following table lists the main elements allowed in structapps.fm as children of the
StructuredSetup element. The table identifies the sections that discuss each of those
elements and the elements they may contain.

Element Discussed in

ApplicationName “Define an application,” next
SGMLApplication “Define an application” on page 9
XMLApplication “Define an application” on page 9
Defaults “Providing default information” on page 11

Define an application

FrameMaker collects all information pertaining to the set-up of a structured application into an
SGMLApplication or XMLApplication element. These elements have one required child
element and several optional child elements.

The first child of a parent SGMLApplication or XMLApplication element must be
ApplicationName and gives the name of the application. It looks like:

Application name: name

where name is a string used to identify your application in the Set Structure Application and Use
Structure Application dialog boxes. You cannot use the same name for multiple structure

applications.

Structured Application Developer Reference 9

Define an application

If present, the optional child elements can occur in any order and can include the following
elements, discussed in the named sections:

Element Discussed in

DOCTYPE “Specifying a DOCTYPE element” on page 13
DTD “Specifying a DTD” on page 14
CharacterEncoding “Specifying the character encoding for SGML files” on page 11
ConditionalText “Specifying conditional text output” on page 13
Entities “Specifying entities” on page 14
ExternalXRef “Specifying external cross reference behavior” on page 20
FileExtensionOverride “Specifying filename extensions” on page 21
Namespace “Enabling namespaces” on page 22
ReadWriteRules “Specifying a read/write rules document” on page 22
RulesSearchPaths “Specifying a search path for included files in rules documents”

Schema “Specifying a Schema for XML” on page 23
SGMLDeclaration “Specifying an SGML declaration” on page 24
Stylesheets “Managing CSS import/export and XSL transformation” on

Template “Specifying a FrameMaker template” on page 26
UseAPIClient,

UseDefaultAPIClient,
XMLDisplayEncoding “Specifying the character encoding for XML files” on page 27
XMLExportEncoding “Exporting XML” on page 29
XMLCharacterEncoding “XML character encoding from an SGML application” on

XMLWriteRules “Write rules for saving XML from an SGML application” on

on page 22

page 24

“Specifying a structure API client” on page 27

page HIDDEN

page HIDDEN

Some elements provide pathnames (for entities and read/write rules files; hence
RulesSearchPaths and EntitySearchPaths elements). If the pathname is absolute, the
software looks there. If it can’t find it via the specified path, the log reports an error and the
operation is aborted. If a relative pathname is given, the software looks for the file in several
places:

• The directory containing the file being processed. For example, if you’re opening a DTD, the

software first searches the directory in which it found the DTD.

• $STRUCTDIR (for information on what directory this is, see Developer Guide, page 131:

Location of structure files).

• The directory from which you started FrameMaker.

Structure Application Definition Reference 10

Providing default information

If an application definition includes any of these elements, the value in the application definition
overrides any value for that element in the Defaults element. The sections following the next
section describe these elements in detail.

Providing default information

Some of the information you provide for individual applications may be common to all your
applications. For such information you can specify defaults that are used whenever an application
does not provide its own version of the information. You use the Defaults element to provide
such information.

If present, the optional child elements of Defaults can occur in any order (with the exception
of the Graphics element, which must be the last child) and can include the following elements,
which are discussed in the named sections:

Element Discussed in

CharacterEncoding “Specifying the character encoding for XML files” on page 27
DTD “Specifying a DTD” on page 14
Entities “Specifying entities” on page 14
FrameDefaultAPIClient,

UseAPIClient
MaxErrorMessages “Limiting the length of a log file” on page 30
Namespace “Enabling namespaces” on page 22
ReadWriteRules “Specifying a read/write rules document” on page 22
RulesSearchPaths “Specifying a search path for included files in rules documents”

SGMLDeclaration “Specifying an SGML declaration” on page 24
Stylesheets “Managing CSS import/export and XSL transformation” on

Template “Specifying a FrameMaker template” on page 26
XMLCharacterEncoding “XML character encoding from an SGML application” on

XMLWriteRules “Write rules for saving XML from an SGML application” on

Graphics “Mapping graphic notations to file types” on page 30

“Specifying a structure API client” on page 27

on page 22

page 24

page HIDDEN

page HIDDEN

Specifying the character encoding for SGML files

The CharacterEncoding element tells the software which encoding to use for the SGML text.
Typically, this is only important on non-Western systems, or in SGML applications that encounter
SGML files using double-byte text. It can contain one of the following child elements:

Structured Application Developer Reference 11

Specifying the character encoding for SGML files

ISOLatin1, ASCII, ANSI, MacASCII, ShiftJIS, KSC8EUC, GB8EUC, CNSEUC, Big5,
JIS8EUC. The CharacterEncoding element looks like this:

SGML character encoding: Iso Latin1

On a non-Western system, the text for an SGML file can contain double-byte text. This text can be
in any one of a number of different text encodings.

FrameMaker can interpret SGML files that contain double-byte text in #PCDATA, RCDATA, and
CDATA. The software expects all other text to be within the 7-bit ASCII range (which is supported
by all Asian fonts). This means that document content can be in double-byte encodings, but the
markup must be in the ASCII range. Typically, for example, the only text in a DTD that will contain
double-byte characters would be text used to specify attribute values.

Important: For SGML documents, you should not use accented characters in element tag

names nor attribute names. If you use such characters, FrameMaker may not be able to
correctly import or export the document.

To import and export SGML that contains double-byte text, you should specify the character
encoding to use, either as a default for all applications, or for a specific SGML application. For a
given SGML application there can only be one encoding. If you don’t specify an encoding for your
application, FrameMaker determines the encoding to use by considering the current default user
interface language and the current operating system; for the current language, it uses the
operating system’s default encoding. The default encodings for Windows® are:

Languages Windows

Roman languages ANSI

Japanese Shift-JIS

Simplified Chinese GB8 EUC

Traditional Chinese Big5

Korean KSC8 EUC

You can have an Asian language for the user interface, but the content of the document files in
Roman fonts. In this case, any exported Roman text that falls outside of the ASCII range will be
garbled. For this reason, we recommend that you specify an encoding for any application that
might be used on a non-Western system.

The template for your application must use fonts that support the language implied by the
encoding you specify. Otherwise, the text will appear garbled when imported into the template.
You can fix this problem after the fact by specifying different fonts to use in the resulting files.

Structure Application Definition Reference 12

Specifying conditional text output

Specifying conditional text output

Add a ConditionalText child to the XMLApplication element to control conditional text
output. Place a single child, OutputTextPI in this element. Then add one of the four children
listed in the following table to the OutputTextPI element:

Child of OutputTextPi FrameMaker outputs

OutputAllTextWithPIs yes yes
OutputAllTextWithoutPIs yes no
OutputVisibleTextWithPIs no yes
OutputVisibleTextWithoutPIs no no
OutputAllTextWithPIsFiltered yes yes*
OutputVisibleTextWithPIsFiltered no yes*

*PIs are displayed only if the document settings are different from the template settings.
The ConditionalText element can only be a child of an XMLApplication element.

Specifying a DOCTYPE element

The DOCTYPE element specifies the generic identifier of the DOCTYPE declaration and root
element in markup documents used with this application. If you open a markup document with
the matching document element specified in the DOCTYPE declaration, FrameMaker uses this
application when translating the document. The element looks like:

DOCTYPE: doctype

where doctype identifies a document element.

hidden conditional text

Processing instructions
delimit conditional text

For example,

DOCTYPE: chapter

matches a markup document with the following declaration:

<!DOCTYPE chapter ...>

If more than one application defined in the structapps.fm file specifies the same document
element, and the end user opens a file with that document element, the software gives the user
a choice of which of these applications to use. If the user opens a markup document for which no
application specifies its document element, the software gives the user the choice of all defined
applications.

Structured Application Developer Reference 13

Specifying a DTD

You can use more than one DOCTYPE element for an application, if that application is applicable
to multiple document elements. For example, if the Book application applies when the document
element is either chapter or appendix, you can use this definition:

Application name: Book
DOCTYPE: chapter
appendix
. . .

The DOCTYPE element can be a child of an SGMLApplication or XMLApplication element.

Specifying a DTD

The DTD element specifies a file containing the external DTD subset that FrameMaker uses when
importing and exporting a markup document. It looks like:

DTD: dtd

where dtd is the pathname of a file containing a document type declaration subset.
Note that the file you specify with the DTD element must be an external DTD subset. It cannot be

a complete DTD. That is, the file cannot have the form:

<!DOCTYPE book [
<!element book . . .>
. . .
]>

Instead, it should simply have the form:

<!element book . . .>
. . .

For more information on external DTD subsets, see Developer Guide, page 89: XML and SGML

DTDs.

You can have only one DTD element for each SGMLApplication or XMLApplication. It can
also be a child of the Defaults element.

Specifying entities

To specify the location of various entities, you use the Entities element. It looks like this:

Entity locations

The possible child elements of a parent Entities element are:

Element Discussed in

EntityCatalogFile “Specifying entities through an entity catalog” on page 15

Structure Application Definition Reference 14

Specifying entities

Element Discussed in

Entity “Specifying the location of individual entities” on page 16
FileNamePattern “Specifying names for external entity files” on page 17
Public “Specifying public identifiers” on page 18
EntitySearchPaths “Specifying a search path for external entity files” on page 19

If you use the EntityCatalogFile element, you cannot use any of the elements Entity,
FilenamePattern, or Public.

You can have only one Entities element for each application, although that Entities
element can have more than one of some of its child elements. The Entities element can also
be a child of the Defaults element.

Specifying entities through an entity catalog

The EntityCatalogFile element specifies a file containing mappings of an entity’s public
identifier or entity name to a filename. It looks like:

Entity locations
Entity catalog file: fname

where fname is the filename of the entity catalog. Entity catalogs and their specified format are
described below.

You can specify multiple EntityCatalogFile elements in a single Entities element. If you
use this element, you cannot use any of the Entity, FilenamePattern, or Public elements.

You can use the EntityCatalogFile element both in the Entities element of the
Defaults element and in an SGMLApplication or XMLApplication element to specify
information for a particular application. When searching for an external entity, FrameMaker
searches the application’s entity catalogs before searching the default entity catalogs.

If you have an EntityCatalogFile element in an application definition, the software ignores
Entity, FilenamePattern, and Public elements in the Defaults element.

Why use entity catalogs

Technical Resolution 9401:1994 published by SGML Open discusses entity management issues
affecting how SGML documents work with each other:

• Interpreting external identifiers in entity declarations so that an SGML document can be

processed by different tools on a single computer system

• Moving SGML documents to different computers in a way that preserves the association of

external identifiers in entity declarations with the correct files or other storage objects.

The technical resolution uses entity catalogs and an interchange packaging scheme to address
these issues. FrameMaker supports such entity catalogs with the EntityCatalogFile
element.

Structured Application Developer Reference 15

Specifying entities

Entity catalog format

Each entry in the entity catalog file associates a filename with information about an external entity
that appears in a markup document. For example, the following are catalog entries that associate
a public identifier with a filename:

PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" "isolat1.ent"
PUBLIC "-//USA/AAP//DTD BK-1//EN" "aapbook.dtd"

In addition to entries mapping public identifiers to filenames, an entry can associate an entity
name with a filename:

ENTITY "chips" "graphics\chips.tif"

A single catalog can contain both types of entry.

If the specified filename in a catalog entry is a relative pathname, the path is relative to the
location of the catalog entry file.

For a complete description of the syntax of a catalog entry, see Technical Resolution 9401:1994
Entity Management published by SGML Open.

How FrameMaker searches entity catalogs

A single application may use multiple catalog files. When trying to locate a particular external
entity, FrameMaker searches the files one at a time until it finds the entry it is looking for. In each
file, the software first searches for an entity using the external entity’s public identifier. If the
software finds the identifier, it uses the associated filename to locate the entity. If it does not find
the public identifier, the software searches the file looking for the entity name. If it does not find
the entity name either, the software continues searching in the next catalog file.

In some circumstances, a system identifier specified in an external entity declaration may not be
valid. If so, FrameMaker uses public identifier and entity name mappings.

Specifying the location of individual entities

Instead of using an entity catalog to associate entities with files, you can use the Entity element
as a child of a parent Entities element. This element allows you to directly associate a filename
with an individual entity. It looks like:

Entity locations
Entity name: ename
Filename: fname

where ename is the name of an entity and fname is a filename.
You can specify multiple child Entity elements for a single Entities element. You use the

FilenamePattern and EntitySearchPaths elements to help the software find these files.
The Entity element can be a child of a parent Entities element in the Defaults element

to set default entity information, and of a parent SGMLApplication or XMLApplication

Structure Application Definition Reference 16

Specifying entities

element to specify information for a particular application. When searching for an external entity,
the software searches the application’s entity locations before searching the default entity
locations.

Specifying names for external entity files

One or more FilenamePattern elements can appear as a child of a parent Entities element
to tell the software how to locate an external entity.

A FilenamePattern element does not apply to an entity for which there is an Entity
element. Otherwise, it applies to all external entities except those with an external identifier that
includes a public identifier but no system identifier. The FilenamePattern looks like:

Entity locations:
Filename pattern: pattern

where pattern is a string representing a device-dependent filename. The three variables that
can appear within pattern are interpreted as follows:

Variable Interpretation

$(System) The system identifier from the entity declaration
$(Notation) The notation name from the entity declaration of an external data entity
$(Entity) The entity name

Case is not significant in variable names, although it may be significant in the values of the
variables. If a variable is undefined in a particular context, that variable evaluates to the empty
string.

A parent Entities element can contain multiple child FilenamePattern elements. The
software assumes the last pattern in the Entities element is:

Filename pattern: $(System)

Thus, if no FilenamePattern elements appear or even if no Entities element appears, the
software assumes system identifiers are complete pathnames and will check search paths to
locate the file.

How FrameMaker searches filename patterns

When locating an external entity, FrameMaker tests the value of the pattern arguments in
successive FilenamePattern elements that have the same parent Entities element, in the
order they occur, until it finds the name of an existing file. As it tests each pattern, it substitutes
relevant information from the entity’s declaration for variables in pattern.

You can use the FilenamePattern element both in the Entities element of the Defaults
element and in an SGMLApplication element to specify information for a particular
application. When searching for an external entity, FrameMaker tests all the filename patterns
specified for the application before it tests those in default FilenamePattern elements.

Structured Application Developer Reference 17

Specifying entities

Example

Suppose the Entities element looks like:

Entity locations:
Filename pattern: $(System).sgm
Filename pattern: $(System).$(Notation)

and the markup document contains:

<!ENTITY intro SYSTEM "introduction.xml">
<!ENTITY chips SYSTEM "chipsfile" NDATA cgm>
. . .
&intro;
. . .
<graphic entity=chips>

When processing the reference to intro, the software searches for a file called
introduction.xml. It is an error if the file does not exist.

When processing the entity attribute of the graphic element, FrameMaker searches for a file
named chipsfile.cgm. If one is not found, it then looks for chipsfile.CGM, assuming that
the NAMECASE GENERAL parameter of the associated SGML declaration is NAMECASE
GENERAL YES.

Note: The NAMECASE GENERAL parameter of the SGML declaration determines the

case-sensitivity of notation names. For XML, the implied setting for this parameter is NO,
which means that names are case-sensitive.

For SGML, the value of this parameter in the reference concrete syntax is NAMECASE
GENERAL YES. With this declaration, the SGML parser forces notation names to
uppercase.

Specifying public identifiers

The Public element of an Entities element tells the software how to process an external
identifier that has a public identifier but no system identifier. It looks like:

Entity locations:
Public ID: pid

Filename: fname

where pid is a public identifier and fname is the name of a file to be associated with the entity
using the public identifier.

You can give multiple Public elements in the same parent Entities element. If you want to
give multiple filenames to search for a particular public identifier, you can specify the same public
identifier in multiple Public elements.

Structure Application Definition Reference 18

Specifying entities

You can use the Public element both in the Entities element of the Defaults element and
in an Entities element of an SGMLApplication or XMLApplication element to specify
information for a particular application. If a Public element occurs as a child of an
SGMLApplication or XMLApplication element, that identifier is used in preference to one
occurring as a child of the Defaults element.

Specifying a search path for external entity files

The EntitySearchPaths child of a parent Entities element tells the software what
directories to search for the files indicated by Entity, FilenamePattern, and Public
elements. It looks like:

Entity locations:
Entity search paths
1: directory

. . .

N: directory

where each directoryi is a device-dependent directory name. The three variables and their
abbreviations that can be used to specify a directory are as follows:

1

n

Variable Abbreviation Interpretation

$HOME ~ The user’s home directory
$SRCDIR . The directory containing the document entity being

processed

$STRUCTDIR The structure directory in use (for information on what

directory this is, see Developer Guide, page 131: Location

of structure files)

Each directoryi value can be an absolute pathname or relative to $SRCDIR.

How FrameMaker searches for entity files

To locate an external entity, FrameMaker searches the specified directories in the order listed. You
can use the EntitySearchPaths element both in the Entities element of the Defaults
element and in an XMLApplication or SGMLApplication element. When searching for an
external entity, FrameMaker searches the directories named in the EntitySearchPaths
element for the application before it searches those in a default EntitySearchPaths element.

An Entities element can contain only one EntitySearchPaths element. The software
assumes the EntitySearchPaths element ends this way:

Entity search paths

. . .
N: $SRCDIR

Structured Application Developer Reference 19

Specifying external cross reference behavior

Thus, if there is no EntitySearchPaths element, the software assumes all markup files are in
the same directory.

Example

Assume the Defaults element is defined as follows:

Defaults
Entity locations:
Filename pattern: $(System).sgm
Filename pattern: $(System).$(Notation)
Entity search paths
1: $HOME
2: $SRCDIR

and the markup document contains:

<!ENTITY intro SYSTEM "introduction.xml">
<!ENTITY chips SYSTEM "chipsfile" NDATA cgm>
. . .
&intro;
. . .
<graphic entity=chips>

When processing the reference to intro, the software looks for the files:

$HOME/introduction.xml
$SRCDIR/introduction.xml

until it finds one of those files. When processing the graphic element, the software searches in
order for:

$HOME/chipsfile.cgm
$SRCDIR/chipsfile.cgm

Specifying external cross reference behavior

To ensure correct resolution of external cross references in XML, use the ExternalXRef
element. ExternalXRef can only be a child of XMLApplication.

Change file extension to .XML

Insert an ExternalXRef child in the XMLApplication element for the application you are
developing. In this ExternalXRef element, insert a ChangeReferenceToXML child. Finally,
insert an Enable element into the ChangeReferenceToXML element. It will look like this:

External X-Ref:

Change Reference To .XML: Enable

Structure Application Definition Reference 20

Specifying filename extensions

When a document with an external cross-reference is saved to XML, FrameMaker then changes
the extension in the xref’s srcfile attribute to .xml and exports the cross-reference as:

<xref srcfile="filepath/filename.xml#elemID">

Where:

• filepath is the absolute path to the saved source XML file

• filename is the name of the saved source XML file

• elemID is the ID of the referenced element.

You can save the source file to XML before or after saving the original file to XML. In either case,
the file name specified for the XML document must be identical to the filename of the original
FrameMaker document except for the extension.

If you insert a Disable element instead of an Enable element into
ChangeReferenceToXML, FrameMaker retains the default behavior and does not change the
extension in the srcfile attribute.

Try alternative extensions

TryAlternativeExtensions specifies an option for importing external cross-references
from XML. It looks like this:

External X-Ref:

Try Alternative Extensions: Enable

If its content is Enable, and FrameMaker cannot open the file specified by the srcfile
attribute, it changes the extension and tries to open the resulting file instead. In particular, if the
original extension is .xml, FrameMaker also tries .fm; if the original extension is .fm,
FrameMaker also tries .xml. If the content of TryAlternativeExtensions is Disable,
FrameMaker creates an unresolved cross-reference if the specified file cannot be opened.
Disable is the default.

Specifying filename extensions

The FileExtensionOverride element specifies a filename extension to use when saving a
FrameMaker document as markup. This is particularly useful when saving XHTML documents.
Some web browsers that support XHTML can only read files with a .htm or .html extension.
When you save a document as XML (even using the XHTML doctype) FrameMaker gives the file a
.xml extension by default. You can use this element to specify a .htm extension when saving a
document as XHTML. The FileExtensionOverride element looks like this:

File Extension Override: extension

where extension is the string for the filename extension, minus the dot character. You can have
only one FileExtensionOverride element for each XML or SGML structure application.

Structured Application Developer Reference 21

Enabling namespaces

Enabling namespaces

The Namespace element specifies whether the current XML structure application supports
namespaces in XML. This element can contain either an Enable or Disable child element. The
Namespace element looks like this with namespaces enabled:

Namespace: Enable

You can have only one Namespace element for each XML structure application. It can also be a
child of the Defaults element. It is not applicable for an SGML application.

Note: XML Schema: You must enable namespaces to allow FrameMaker to validate XML

against a Schema definition upon import and export. Schema allows an XML document to
reference multiple Schema locations in different namespaces. When this is the case, only
the first namespace is used. See Developer Guide, page 199: Schema location for
additional information.

Specifying a read/write rules document

The ReadWriteRules element specifies the read/write rules document associated with the
application. It looks like:

Read/write rules: rules

where rules is the pathname of a FrameMaker read/write rules document.
You can have only one ReadWriteRules element for each application. It can also be a child of

the Defaults element.

Specifying a search path for included files in rules documents

The RulesSearchPaths element is analogous to the EntitySearchPaths element, but it
pertains to additional files you include in a read/write rules document rather than to external
entities referenced within a markup document. Its Path child elements indicate individual
directories. It looks like:

Search paths for included read/write rules files:
1: directory

. . .

N: directory

1

n

Structure Application Definition Reference 22

Specifying a Schema for XML

where each directoryi is a device-dependent directory name. The two variables and their
abbreviations that can be used to specify a directory are as follows:

Variable Abbreviation Interpretation

$HOME ~ The user’s home directory
$STRUCTDIR The structure directory in use (for information on what

directory this is, see Developer Guide, page 131: Location of

structure files)

Each directoryi value can be an absolute pathname or relative to $RULESDIR.

How FrameMaker searches for rules files

Only one RulesSearchPaths element can occur as the child of a single parent
XMLApplication or SGMLApplication element or parent Defaults element. When

searching for a file you include in an read/write rules document, FrameMaker searches the
directories named in the RulesSearchPaths element for the application before it searches
those in the RulesSearchPaths element of the Defaults element.

The software assumes RulesSearchPaths ends in this way:

Search paths for included read/write rules files:

. . .
N: $RULESDIR

Thus, if there is no RulesSearchPaths element, the software assumes all files you include in
the read/write rules document are in the same directory as your rules document.

Specifying a Schema for XML

The Schema element, a direct child of XMLApplication, specifies the path and filename for an
XML Schema file that contains element declarations for XML. It look like this:

Schema: schema_path

where schema_path is the pathname of a file containing a Schema declaration file.

In order for a structure application to be selectable in the Use Structured Application list while
importing a document that is associated with a Schema, the Schema’s root element must be
included in the application’s DOCTYPE in the XmlApplication element.

Structured Application Developer Reference 23

Specifying an SGML declaration

Specifying an SGML declaration

The SGMLDeclaration element specifies the location of a file containing a valid SGML
declaration. It is used only for SGML applications and cannot be a child of an XMLApplication
element. The SGMLDeclaration element looks like:

SGML declaration: declaration

where declaration is the pathname of the SGML declaration file.
You can have only one SGMLDeclaration element for each SGML application. It can also be a

child of the Defaults element.

Managing CSS import/export and XSL transformation

The Stylesheets element of an XML structure application tells the software how to treat the
use of CSS stylesheets for a given XML document, and how and whether to perform XSL
transformation upon import or export of XML documents.

An XML application can have only one Stylesheets element. It can also be a child of the
Defaults element.

How the Stylesheets element affects CSS generation

You can specify whether to use an existing stylesheet, or whether FrameMaker should generate a
new one and use that for the exported XML. You can specify any number of stylesheets, and the
exported XML will include references to each one. The Stylesheets element also contains
instructions concerning the use of attributes and stylesheet processing instructions. The
Stylesheets element for CSS looks like:

CSS2 Preferences:

Generate CSS2: enable/disable
Add Fm CSS Attribute To XML: enable/disable

Retain Stylesheet Information: enable/disable
XML Stylesheet:

Type: stylesheet_type
URI: path

When you save a document to XML, FrameMaker can either use an existing stylesheet, or generate
a new one from the current EDD. How FrameMaker generates a stylesheet is determined by the
values of the children of the Stylesheets element. For more information about how
FrameMaker converts EDD information into a stylesheet, see Developer Guide, page 283: Saving

EDD Formatting Information as a CSS Stylesheet

GenerateCSS2 Specifies whether FrameMaker will generate a CSS when you save the document
as XML. It can be set to enable or disable. When this is set to enable, FrameMaker generates a CSS.
If a path is provided in StylesheetURI, FrameMaker saves the stylesheet to that location, with

Structure Application Definition Reference 24

Managing CSS import/export and XSL transformation

that filename. Otherwise, it saves the stylesheet to the same location as the XML document with
a filename xmldoc.css, where xmldoc is the name of the XML document you’re saving.

AddFmCSSAttrToXml Specifies whether FrameMaker will write instances of the fmcssattr
attribute to elements in the XML document. It can be set to enable or disable. An EDD can
include context selectors as criteria to assign format rules. CSS has no equivalent to this. When this
is set to enable, FrameMaker uses the fmcssattr attribute in certain elements so the CSS can
achieve the same formatting as the EDD.

RetainStylesheetPIs Specifies whether FrameMaker will retain the stylesheet declaration for
import and export of XML. It can be set to enable or disable. When this is set to enable,
FrameMaker does the following:

• On import, it stores the XML document’s stylesheet PI as a marker in the FrameMaker

document.

• On export, it writes the content of stylesheet PI marker in the resulting XML document.

StylesheetType Specifies the type of stylesheet. It contains a string for the stylesheet type.
Currently, you can specify CSS (upper or lower case) or XLS (upper or lower case). If you specify
XLS, FrameMaker will not generate a stylesheet.

StylesheetURI Specifies the URI for the stylesheet. It contains a string; for example,
/$STRUCTDIR/xml/xhtml/app/xhtml.css.

How the Stylesheets element affects CSS import

You can specify whether a CSS stylesheet that is referenced in an XML file is used to update the
formatting of the FrameMaker document. The ProcessStylesheetPI is an optional child of
the CssPreferences element and looks like this:

CSS2 Preferences:

ProcessStylesheetPI: enable/disable

ProcessStylesheetPI can have one of the following values: Enable or Disable. If the
value of the ProcessStylesheetPI element is Enable, then the CSS file referenced in the
XML file is used while opening the XML file. The default value of the ProcessStylesheetPI
element is Disable.

For more information about how the CSS file mentioned in the XML file is used when an XML file
is opened, see Chapter 5, “CSS to EDD Mapping.”

How the Stylesheets element affects XSL transformation

If an XML structure application specifies an XSL stylesheet, FrameMaker can apply transformations
defined in that stylesheet when importing an XML document, or when exporting a FrameMaker
document to XML. The XSLTPreferences element in the Stylesheets element allows you
to specify the XSL file to use for transformation upon import (PreProcessing) and/or export

Structured Application Developer Reference 25

Specifying a FrameMaker template

(PostProcessing). StylesheetParameters elements allow you to set parameters of an
XSL stylesheet at run time, before the transformation takes place.

XSLT Preferences:
Process Stylesheet PI: enable/disable
Preprocessing:

Stylesheet: path
Stylesheet Parameters

Name: parameter name
Expression: exp

Postprocessing:

Stylesheet: path
Stylesheet Parameters

Name: parameter name
Expression: exp

ProcessStylesheetPI Specifies whether FrameMaker will use the XSL file mentioned in the

xml-stylesheet PI of an XML file to transform that file. It can be set to enable or disable.
By default it is set to disable, and FrameMaker does not use the PI. Set to enable to use the PI.

PreProcessing Contains a Stylesheet element that specifies the XSL file to be used for
transformation upon import of an XML document. Transformation occurs before read rules are
applied. The XSLTPreferences element can contain 0 or 1 PreProcessing elements.

PreProcessing Contains a Stylesheet element that specifies the XSL file to be used for
transformation upon export of an XML document. Transformation occurs after write rules are
applied. The XSLTPreferences element can contain 0 or 1 PostProcessing elements.

Stylesheet Specifies the URI for the XSL file. It contains a string; for example,
/$STRUCTDIR/xml/xhtml/app/mystyles.xsl.

StylesheetParameters Contains ParameterName and ParameterExpression pairs. Each
pair specifies the name of a parameter used the XSL stylesheet, and an expression that constrains
the value of that parameter for the subsequent transformation.

For more information on XSL transformation of XML, see Developer Guide, Chapter 29, Additional

XSL Transformation for XML.

Specifying a FrameMaker template

The Template element specifies the location of the FrameMaker template. It looks like:

Template: template

where template is the pathname of a FrameMaker template.

The software uses this template to create new FrameMaker documents from markup documents,
which may be single documents resulting from the Open or Import command or documents in
a book created through the Open command.

Structure Application Definition Reference 26

Specifying a structure API client

If this element is not present, the software creates new portrait documents as needed. When you
import a markup document into an existing document, the software uses the import template
only to access reference elements that are stored on the template’s reference page. (For
information about reference elements, see Developer Reference, page 332: Translating SDATA

entities as FrameMaker reference elements.)

You can have only one Template element for each application. It can also be a child of the
Defaults element.

Specifying a structure API client

In an application definition, the UseDefaultAPIClient element tells the software that your
application does not use a special client for markup translation. In the defaults section, the

FrameDefaultAPIClient element serves the same purpose. The default client is named
FmTranslator.

If you do need a structure API client, use the UseAPIClient element in either context. For
information on creating structure API clients for a structure application, see the online manual
Structure Import/Export API Programmer’s Guide.

Specifying the character encoding for XML files

The XML specification supports UNICODE characters for document content and markup tokens. In
XML the given encoding is specified in the document prolog. The following example shows a
specification for ShiftJIS character encoding:

<?xml version="1.0" encoding="Shift_JIS" ?>

The XML specification states that an XML document must either specify an encoding in the prolog,
or it must be UTF-8 or UTF-16. FrameMaker follows this specification by assuming UTF-8 by default
if there is no encoding specified in the XML file.

If you read an XML file with character encoding that does not match either the declared encoding
or the default encoding (if no encoding is declared), it is likely that the import process will
encounter a character that does not match the encoding FrameMaker uses. In that case, you will
get a parsing error that says the document is not well-formed due to a bad token.

FrameMaker uses the encoding statement in the document prolog to determine which encoding
to use. The statement must specify one of the encodings supported by your specific FrameMaker
installation. FrameMaker ships with support for the following encodings:

Big5 KSC_5601
EUC-JP Shift_JIS
EUC-KR US-ASCII
EUC-TW UTF-16
GB2312 UTF-8

Structured Application Developer Reference 27

Specifying the character encoding for XML files

ISO-8859-1 windows-1252

You can add other encodings to your FrameMaker installation—see Developer Guide, page 103:

Unicode and character encodings.

FrameMaker converts the encoding of the XML document to an internal display encoding. In this
way FrameMaker fully supports Unicode characters for text that is in #PCDATA, RCDATA, and
CDATA. For any #PCDATA character that it cannot interpret, FrameMaker uses a marker of type
UNKNOWNCHAR to represent the character. For unknown CDATA characters, FrameMaker uses XML
character references.

The following sections describe how to control the display encoding that FrameMaker uses, and
how to specify an encoding when you save a document as XML.

Display encoding

On import, FrameMaker converts the XML encoding to a display encoding that is appropriate for
a given language. However, FrameMaker cannot automatically determine which conversion to
make. Although the XML document prolog specifies an encoding, the document may contain
elements or other constructs that override the language implied by that encoding. As a result, you
should specify a display encoding for the structure application. The display encodings you can
specify are:

Display encoding: For this language:

FrameRoman Western European languages
JISX0208.ShiftJIS Japanese
BIG5 Traditional Chinese
GB2312-80.EUC Simplified Chinese
KSC5601-1992 Korean

By default, FrameMaker uses the display encoding that matches the locale of your operating
system. To specify a different display encoding, use the XmlDisplayEncoding element.
XmlDisplayEncoding can contain one child element to specify one of the supported display
encodings.

The display encoding also determines how FrameMaker interprets the characters in markup
tokens such as GIs and attribute names. If FrameMaker encounters such a token with an unknown
character, FrameMaker drops the token. For more information, see Developer Guide, page 101:

Supported characters in element and attribute names.

For example, if your operating system locale is French, German, or English FrameMaker uses
FrameRoman by default. This is true, even if the XML prolog specifies an encoding for a different
language, such as ShiftJIS. To import XML encoded as ShiftJIS, you would use the
XmlDisplayEncoding element to specify JISX0208.ShiftJIS, as follows:

XML Display Encoding: JISX0208.ShiftJIS

Structure Application Definition Reference 28

Exporting XML

When you specify such an encoding, FrameMaker uses that encoding as the default for all the
#PCDATA, RCDATA, and CDATA in the imported XML. Markup tokens that include characters in the
upper range of the display encoding are interpreted correctly. If you have fonts installed for the
display encoding, then the text will appear as intended.

For another example, assume you have a version of US English FrameMaker installed on a
Traditional Chinese operating system. By default, FrameMaker uses Big5 as the display encoding.
It also supports any Big5 characters that are used in GIs and attribute names. If you are importing
an XML document that is in English, you would need to specify FrameRoman as the display
encoding.

Note that the XML standard includes the xml:lang attribute. This attribute can specify a change
of language for an element and its content. If that language is one of those listed in the table of
display encodings, a change made by this attribute take precedence over the setting made via
XmlDisplayEncoding.

Finally, the template for your application must use fonts that support the given language.
Otherwise, the text will appear garbled when imported into the template. You can fix this problem
by specifying different fonts to use in the resulting files.

Encoding of CSS files

FrameMaker supports the following encodings for CSS files: utf-8, utf-16, utf-16LE, and utf-16BE.
FrameMaker detects the encoding of a CSS file using the Byte Order Mark (BOM), and not the

“@charset” statement.

Exporting XML

Your XML structure application can include an XmlExportEncoding element to specify the
encoding to use when you save a document as XML. FrameMaker determines which encoding to
use according to the following rules:

If: FrameMaker uses:

1.The structure application specifies a value for

XmlExportEncoding, and that encoding is
supported

2.1 is not true, and the original XML source specified an
encoding, and that encoding is supported

3.1 and 2 are not true UTF-8

The XmlExportEncoding element contains a string for the name of an encoding. The name
you provide must conform with the IANA naming conventions. The standard installation of
FrameMaker supports the encodings that are listed at the beginning of this discussion (see

page 27).

The specified encoding

The encoding that was specified in
the original XML source

Structured Application Developer Reference 29

Limiting the length of a log file

For example, to export your document as ISOLatin1, use the XmlExportEncoding element as
follows:

XML Export Encoding: ISO-8859-1

Limiting the length of a log file

The MaxErrorMessages child element of the Defaults element allows you to limit the
length of structure error reports. It looks like:

Maximum number of error messages: n

where n is the desired limit. If n is less than 10, the software resets it to 10. This must be the last
child of the parent Defaults element.

By default, FrameMaker does not write more than 150 messages (error messages and warnings)
to a single log file.

Messages pertaining to opening and closing book components are not included in this limit.
Messages generated through your own structure API client are also not counted, although if you
wish, you can count them using your own code.

In documents that generate large numbers of messages, the 151st message is replaced with a
note that additional messages have been suppressed.

Note that processing continues, even though further messages are not reported. This message
limit is reset for every file processed and for each component of a book.

Mapping graphic notations to file types

The Graphics child element of the Defaults element allows you to provide mappings from
graphic notation to file type by using the file name extension. In the example below the JPEG
notation is mapped to the .jpg extension.

Graphics

Notation: JPEG Filetypehint:jpg

The Graphics element may contain one or more Mapping elements.

Structure Application Definition Reference 30

2

Read/Write Rules Summary 2

This chapter lists the available read/write rules by category and briefly describes the purpose of
each rule. The categories, which are arranged alphabetically, are as follows:

• “All Elements” on page 31

• “Attributes” on page 32

• “Books” on page 33

• “Cross-references” on page 33

• “Entities” on page 34

• “Equations” on page 34

• “Footnotes” on page 35

• “Graphics” on page 35

• “Markers” on page 36

• “Processing instructions” on page 37

• “Markup documents” on page 37

• “Tables” on page 38

• “Text” on page 39

• “Text insets” on page 39

• “Variables” on page 39.

All Elements

To Use this rule Page

Translate a markup element element 54

Discard or unwrap a FrameMaker element on
export

Translate a markup element to a FrameMaker
element

Translate a markup attribute within the
context of a single markup element

Structured Application Developer Reference 31

fm element 75

is fm element 108

attribute 44

Attributes

To Use this rule Page

Inform FrameMaker not to update a
FrameMaker element’s definition when
updating an existing EDD

Discard a FrameMaker or markup
element

Discard the content but not the structure of a
FrameMaker or markup element

Discard the structure but not the content of a
markup or FrameMaker element

Attributes

To Use this rule Page

Translate a markup attribute attribute 44
Discard a FrameMaker attribute fm attribute 74

Translate a markup attribute to a FrameMaker
attribute

Translate a markup attribute within the
context of a single markup element

Discard a markup or FrameMaker attribute drop 51

Translate a markup attribute to a particular
FrameMaker property

Translate a value for a markup attribute to a

FrameMaker property value

Translate a value of a markup notation

attribute or name token group to a value for
a FrameMaker choice attribute

Translate a markup attribute value to a
FrameMaker property or a choice attribute
value

Specify the value to use for a markup implied
attribute when a document instance provides
no value

preserve fm element
definition

drop 51

drop content 53

unwrap 158

is fm attribute 101

element 54

is fm property 114

is fm property value 122

is fm value 135

value 161

implied value is 94

144

Read/Write Rules Summary 32

Books

Books

To Use this rule Page

Specify whether to use elements or
processing instructions to indicate book
components when reading a markup
document

Specify elements to use to indicate book
components when reading a markup
document

Specify the use of processing instructions to
indicate book components when reading a
markup document

Specify whether or not to write processing
instructions that indicate book components
in a markup document

Cross-references

generate book 91

put element

(described with generate book)

use processing instructions
(described with generate book)

output book processing
instructions

91

91

143

To Use this rule Page

Translate markup elements to FrameMaker
cross-reference elements

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate a markup attribute to a particular
FrameMaker property

Translate a value for a markup attribute to a

FrameMaker property value

Translate a value of a markup notation

attribute or name token group to a value for
a FrameMaker choice attribute

Translate a FrameMaker cross-reference

element to text in markup

is fm cross-reference
element

fm property 78

value is

(described with fm property)

is fm property 114

is fm property value 122

is fm value 135

fm element unwrap 75,

107

78

158

Structured Application Developer Reference 33

Entities

Entities

To Use this rule Page

Translate a markup entity reference to an
appropriate FrameMaker representation

Determine the form of names of entities
created for exported graphics

Drop references to external data entities external data entity

Translate an entity reference to a FrameMaker

variable

Translate an entity reference to a single

character

Translate an entity reference to an element on

a reference page

Translate an SDATA entity reference to a text

inset
Determine the formatting of a text inset reformat as plain text 150

Discard external data entity references drop 51

entity 59

entity name is 61

69

reference
is fm variable 137

is fm char 105

is fm reference element 125

is fm text inset 133

reformat using target
document catalogs

retain source document
formatting

151

152

Equations

To Use this rule Page

Translate a markup element to a FrameMaker
equation element

Specify export information for translating
FrameMaker equations

Specify the filename used for exporting an
equation

Determine the form of names of entities
created for exported equations

Specify the data content notation for an
exported equation

Read/Write Rules Summary 34

is fm equation element 109

equation 63

export to file 67

entity name is 61

notation is 141

Footnotes

To Use this rule Page

Determine whether FrameMaker uses the
dpi attribute or the impsize attribute for
equations and also the resolution used

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker equation properties to
markup attributes

Translate a value for a markup attribute to a

FrameMaker property value

Translate a value of a markup notation

attribute or name token group to a value for
a FrameMaker choice attribute

Translate a markup attribute value to a
FrameMaker property or a choice attribute
value

specify size in 153

fm property 78

value is

(described with fm property)

is fm property 114

is fm property value 122

is fm value 135

value 161

78

Footnotes

To Use this rule Page

Translate a markup element to a FrameMaker
footnote element

Graphics

To Use this rule Page

Translate a markup element to a FrameMaker
graphic element

Specify export information for translating
FrameMaker graphics

Specify export information for translating
FrameMaker graphics that have a single inset

Specify the filename used for exporting a
graphic or a facet of a graphic

Force the software to export graphic files that
were imported by reference

is fm footnote element 110

is fm graphic element 111

anchored frame 41

facet 72

export to file 67

convert referenced graphics 49

Structured Application Developer Reference 35

Markers

To Use this rule Page

Determine the form of names of entities
created for exported graphics

Specify the data content notation for an
exported graphic

Determine whether FrameMaker uses the
dpi attribute or the impsize attribute for
imported graphics objects and also the
resolution used

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker graphic properties to
markup attributes

Translate a value for a markup attribute to a

FrameMaker property value

Translate a value of a markup notation

attribute or name token group to a value for
a FrameMaker choice attribute

Translate a markup attribute value to a
FrameMaker property or a choice attribute
value

entity name is 61

notation is 141

specify size in 153

fm property 78

value is

(described with

is fm property 114

is fm property value 122

is fm value 135

value 161

fm property)

78

Markers

To Use this rule Page

Discard FrameMaker non-element markers or
translate them to processing instructions

Translate a markup element to a FrameMaker
marker element

Determine whether marker text for marker
elements becomes content or an attribute
value in markup

Drop references to external data entities external data entity

Drop unrecognized processing instructions processing instruction 147

Translate FrameMaker non-element markers
to processing instructions

Discard non-element markers drop 51

Read/Write Rules Summary 36

fm marker 76

is fm marker element 112

marker text is 140

69

reference

is processing instruction 138

Processing instructions

To Use this rule Page

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker cross-reference

properties when no markup attribute exists

Translate FrameMaker marker properties to
markup attributes

Translate a value for a markup attribute to a

FrameMaker property value

Translate a value of a markup notation

attribute or name token group to a value for
a FrameMaker choice attribute

Translate a markup attribute value to a
FrameMaker property or a choice attribute
value

Processing instructions

fm property 78

value is

(described with fm property)

is fm property 114

is fm property value 122

is fm value 135

value 161

78

To Use this rule Page

Specify the treatment of unrecognized
processing instructions

Specify the use of processing instructions to
indicate book components when reading a
markup document

Specify whether or not to write processing
instructions that indicate book components
in a markup document

Translate FrameMaker non-element markers
to specific markup, or drop them

Translate FrameMaker non-element markers
to processing instructions

Discard processing instructions drop 51

Markup documents

To Use this rule Page

Specify whether or not to use an external DTD
subset to contain the DTD for a markup
document created by FrameMaker

processing instruction 147

use processing instructions

(described with

output book processing
instructions

fm marker 76

is processing instruction 138

include dtd 96

generate book)

91

143

Structured Application Developer Reference 37

Tables

Tables

To Use this rule Page

Specify whether or not to include an SGML
declaration in an SGML document created by
FrameMaker

Specify the system and public identifiers for
an external DTD subset

Specify whether to create an entire markup
document or just a markup document
instance

To Use this rule Page

Translate a markup element to a FrameMaker
table element

Translate a markup element to a FrameMaker
element for a particular table part

When creating a FrameMaker table, insert a

table part even if that part is empty

Specify that a particular element always
indicates a new table row

Indicate the start of a vertical straddle start vertical straddle 156
Indicate the end of a vertical straddle end vertical straddle 57
Specify the ruling style used for all tables table ruling style is 157

Specify the resolution used for column widths
with proportional widths

Specify that the software write the width of
table columns using proportional units

Translate FrameMaker table properties to
markup attributes

Translate a value for a markup attribute to a

FrameMaker property value

Translate a value of a markup notation

attribute or name token group to a value for
a FrameMaker choice attribute

Translate a attribute’s name token value to a
FrameMaker property or choice value

include sgml declaration 97

external dtd 70

write structured document 163
write structured document

instance only

is fm table element 130

is fm table part element 132

insert table part element 98

start new row 155

proportional width
resolution is

use proportional widths 160

is fm property 114

is fm property value 122

is fm value 135

value 161

163

148

Read/Write Rules Summary 38

Text

Tex t

To Use this rule Page

Translate an entity reference to a single

character

Determine the treatment of line breaks in
reading and writing markup documents

Define mappings between characters in the
markup and FrameMaker character sets

Text insets

To Use this rule Page

Translate an SDATA entity reference to a
FrameMaker text inset

Determine the formatting of a text inset reformat as plain text 150

is fm char 105

line break 138

character map 47

entity
is fm text inset

reformat using target
document catalogs

retain source document
formatting

59

133

151

152

Variables

To Use this rule Page

Translate a markup element to a FrameMaker
system variable element

Translate an entity reference to a FrameMaker

variable

Translate a markup entity reference to a
FrameMaker variable

Determine treatment of FrameMaker non­element variables

Translate a FrameMaker system variable

element to text in markup
Discard nonelement variables drop 51

Structured Application Developer Reference 39

is fm system variable
element

is fm variable 137

entity 59

fm variable 89

fm element unwrap 75,

129

158

Text

Read/Write Rules Summary 40

3

Read/Write Rules Reference 3

This chapter provides a reference to all read/write rules, listed in alphabetical order. The entry for
each rule starts with a brief explanation of the purpose of the rule and how to use it. The rule’s
description may include the following sections:

Synopsis and contexts The rule’s syntax and the context in which it can be used. If the rule
occurs as a subrule of another rule, the more general rule is shown. If the rule can be used in
multiple contexts, the synopsis shows each context. Each entry in this section shows a valid rule
that has the current rule either at the highest level or as one of its subrules.

Rule synopses use the following conventions:

• Bold portions and nonitalicized portions of a rule are entered by you as shown.

• Italicized portions of a rule indicate the rule’s arguments or possible subrules; you enter your

values.

• Brackets [ ] indicate optional parts of a rule; the entire form within the brackets can be included

or omitted.

Arguments The possible arguments to the rule. If an argument is optional, its default value is
provided. Some rules have subrule as one of their arguments. In these cases, a list of possible
subrules is provided. Some rule arguments allow variables. In these cases, a list of possible
variables is provided.

Details Instructions on how to use the rule and on FrameMaker behavior when the rule is not
supplied.

XSLT interaction Useful information about the relationship between FrameMaker’s Read/Write
rules and equivalent XSLT processing.

Examples Various examples of the rule.

See also Cross-references to other relevant information in the manual.

For information on how to create a Read/Write rules file and on the syntax of rules, see Developer

Guide, Chapter 18, Read/Write Rules and Their Syntax

anchored frame

Use the anchored frame rule and its subrules to define how FrameMaker handles the content
of anchored frames when writing to markup and creating a referenced graphic file. Subrules can
specify base entity name, file name construction, graphic file format, notation type and unit of

Structured Application Developer Reference 41

anchored frame

measure. The rule is used when an anchored frame contains FrameMaker graphics, more than one
imported graphic file, or a graphic file that has been copied into the document.

Note: Use the facet rule for anchored frames that contain single graphic files that have

been imported by reference.

Synopsis and contexts

1. element "gi" {

2. element "gi" {

Arguments

gi A markup element’s name (generic identifier).

is fm graphic element ["fmtag"];
writer anchored frame subrule;
. . .}

is fm graphic element ["fmtag"];
writer anchored frame {

subrules;
}

. . .}

fmtag A FrameMaker element tag.

subrules An anchored frame rule can have one or more of the following

subrules:

entity name is, tells the software how to create the base name for

the entity associated with this element type.

export to file tells FrameMaker how to write the file name when it

creates a new graphic file, and optionally the graphic format for the file.

notation is specifies the data content notation of the entity file.
specify size in specifies the units to use when writing the file.
export dpi is tells FrameMaker the dpi setting to use for the

exported graphic file.

Details

The anchored frame rule must be a subrule of a writer rule for a graphic element.

On export, if the anchored frame contains only a single imported graphic file, FrameMaker uses
that graphic file for the resulting markup graphic element by default. If the anchored frame
contains more than one graphic file, or has been modified using FrameMaker graphics tools, the
software writes out a graphic file to be used. The default format for these graphic files is CGM. The
export format can be changed with the export to file rule. For more information about

Read/Write Rules Reference 42

anchored frame

translating anchored frame contents, see Developer Guide, Chapter 23, Translating Graphics and

Equations

Examples

Assume you use the Graphic element for all graphic elements. If the graphic contains any single
facet, assume the graphic was imported as an entity and you want the default behavior. However,
if the author used FrameMaker graphic tools to create the objects in the graphic element, you
want the file written in QuickDraw PICT format.

To accomplish all this, use this rule:

Assume the FrameMaker document is named mydoc.fm. For the first graphic that is not a single
facet, the software writes out a graphic file named mydoc1.pic in the PICT format.

If the export DTD declares an entity attribute to identify the graphic file with the graphic
element, the software generates the following entity declaration:

element "graphic" {
is fm graphic element;
writer anchored frame export to file "$(docname).pic"

as "PICT";

}

<!ENTITY graphic1 SYSTEM "mydoc1.pic" NDATA PICT>

The corresponding graphic element in the markup could be:

<graphic entity = "graphic1"/>

If the export DTD includes only a file attribute to associate the graphic file with the graphic
element, the software uses this filename as its value:

<graphic file = "mydoc1.pic"/>

See also

Related rules “equation” on page 63

“facet” on page 72

Rules mentioned in
synopses

“element” on page 54

“is fm equation element” on page 109

“is fm graphic element” on page 111

“writer” on page 164

General information

Developer Guide, Chapter 23, Translating Graphics and Equations

on this topic

Structured Application Developer Reference 43

attribute

attribute

Use the attribute rule to describe how to process a markup attribute. By default, a markup
attribute translates to a FrameMaker attribute of the same name. Usually, this rule occurs as a
subrule of the element rule, to describe treatment of the attribute attr within the element gi.

Synopsis and contexts

1. [mdv] attribute "attr" {. . .

2. element "gi" {. . .

Arguments

mdv An optional markup declared value, specifying the type of the markup

subrule;
. . .}

[mdv] attribute "attr" {. . .
subrule;

. . .}

. . .}

attribute. Legal values for an XML application are:

• cdata

• nmtoken

• nmtokens

• entity

• entities

• id

• idref

• idrefs

• notation

• group.

Legal values for an SGML application are:

• cdata

• name

• names

• nmtoken

• nmtokens

Read/Write Rules Reference 44

attribute

• number

• numbers

• nutoken

• nutokens

• entity

• entities

• notation

• id

• idref

• idrefs

• group.

attr The name of a markup attribute.

gi A markup element’s name (generic identifier).

subrule An attribute rule can have one of the following subrules:

drop discards the attribute. If this rule is used, no other attribute

subrules may be used.

or:

is fm attribute translates a markup attribute into a FrameMaker

attribute.

or:

is fm property translates a markup attribute to a FrameMaker

property such as the width of columns in a table. This subrule is applicable
only to cross-reference, marker, graphic, equation, table, and table part
elements.

An attribute rule can also have the following subrules:

implied value is specifies the value to use for an impliable attribute

for which no value is given in a document instance.

value translates one of the possible values of a markup name token,

group or a notation attribute to a specific token of a FrameMaker choice
attribute.

Details

• In some cases, the same attribute may occur in several markup elements and may require the

same treatment for most of those occurrences. In these situations, you can use the

Structured Application Developer Reference 45

attribute

attribute rule at the highest level to set the default treatment of the attribute. You can then
override the default in individual element rules.

• If the drop rule is used no other subrules of attribute may be used. The subrules is fm

attribute, and is fm property are mutually exclusive. That is, if you use one of these

rules, you cannot use the other rule.

Examples

• The following rule specifies that the sec attribute of the markup list element is in a name

token group and corresponds to the attribute Security on the corresponding FrameMaker
element:

element "list"
group attribute "sec"
is fm attribute "Security";

• Assume you have several elements that represent graphic objects. Each of them has an

attribute w, representing the width of the object. Use this rule to make the width be 3 inches
unless otherwise specified for a particular element:

attribute "w" {
is fm property width;
implied value is "3in";
}

• Assume you have an element team with an attribute color. The possible values for color

are r, b, and g. To change the names of these values in the corresponding FrameMaker choice
attribute, use this rule:

element "team" {
attribute "color" {
value "r" is fm value "Red";
value "b" is fm value "Blue";
value "g" is fm value "Green";
}}

See also

Related rules “fm attribute” on page 74

“is fm attribute” on page 101

Rules mentioned in
synopses

General information
on this topic

“element” on page 54

Developer Guide, Chapter 20, Translating Elements and Their Attributes

Read/Write Rules Reference 46

character map

character map

Use the character map rule to define mappings between characters in the markup and
FrameMaker character sets. Many characters can be expressed using a string; others require using
the appropriate integer character code.

Note: XML: This read/write rule is primarily for SGML. XML can use UNICODE characters

which makes this rule unnecessary.By default FrameMaker assumes UTF-8 encoding for
XML import and export. If you want to use ISOLatin encoding with an XML document,
then you may need to use this rule to map characters.

Synopsis and contexts

1. character map is cmap1 [, . . ., cmapn];

2. reader character map is cmap1 [, . . ., cmapn];

3. writer character map is cmap1 [, . . ., cmapn];

Arguments

cmap

Details

i

A mapping between the character set used in the markup document and
the FrameMaker character set. Each cmapi has one of the following
forms:

sgmlch = fmch;
sgmlch = trap;
trap = fmch;

sgmlch is either a 1-character string or a character code representing a

character in the markup character set. sgmlch can be a single character
only if that character has the same character code in both the
FrameMaker and markup character sets. Otherwise, you must use the
integer character code.

fmch is either a 1-character string or a character code representing a
character in the FrameMaker character set.

For information on how to represent character codes and special
characters in strings, see Developer Guide, page 278: Strings and

constants.

• Some characters might be defined in only one of the two character sets. The keyword trap is

provided for this situation. By default, FrameMaker discards trapped characters.

• The character map need not be a one-to-one mapping. If a character in the input document is

mapped to multiple characters in the output character set, FrameMaker uses the output
character from the last mapping to appear in the character map rule.

Structured Application Developer Reference 47

character map

• If you use the character map rule at the highest level, do not also use it inside either a

• If you use the character map rule at the highest level, its behavior is bidirectional. For

• By default, FrameMaker assumes that the character set your SGML documents use is ISO

reader rule or a writer rule. If you use this rule inside a reader rule or a writer rule and

also use it at the highest level, FrameMaker ignores the highest-level character map rule.
You can only have one occurrence of this rule at the highest level.

Similarly, the character map rule can appear in one reader rule and one writer rule at
most. The software ignores any subsequent uses of the character map rule.

example, you could have this rule:

character map is 0x20 = 0x12;

This rule specifies that the ISO Latin-1 space character (character code 0x20) maps to the
FrameMaker thin space character (character code 0x12). With this rule, FrameMaker translates
a thin space to a standard space when it writes a markup document. However, this rule
translates all spaces in a markup document to thin spaces in a corresponding FrameMaker
document. This is unlikely to be the desired behavior. For this reason, instead you should use
this rule:

reader character map is 0x20 = 0x12;

Latin-1. It provides a default mapping between those character sets. For details, see Chapter 11,

“Character Set Mapping.” For information on other character sets you can use, see Chapter 10,
“ISO Public Entities.”

• By default, on export FrameMaker produces a character in the SGML document for most

printing characters in the corresponding FrameMaker document. FrameMaker documents

occasionally include unusual characters that serve no purpose outside FrameMaker. For

example, the codes 0x01 and 0x03 are nonprinting characters that represent information

about the insertion point movement. On export FrameMaker traps such characters, so that they

don’t appear in an exported SGML document.

Similarly, on import FrameMaker produces a character in the FrameMaker document for most

printing characters. It traps all control characters other than a tab or newline character.

• FrameMaker has an 8-bit character set. The SGML declaration can specify any character set that

the SGML parser can handle. Part of the character set description in the SGML declaration is

not human-readable and may not be interpretable automatically, therefore, any differences

between the native FrameMaker character set and the character set in the SGML document

must be specified with the character map rule.

• By default, FrameMaker discards trapped characters. You can provide a structure API client to

change the processing of trapped characters. For information on creating a structure API client,

see the Structure Import/Export API Programmer’s Guide.

Examples

• Both the FrameMaker and default SGML character sets have a character code for the character

ó (lowercase o with an acute accent). In FrameMaker, the character code is 0x97; in the default

Read/Write Rules Reference 48

convert referenced graphics

SGML character set, the character code is 0xF3. If you want to trap the SGML character that

looks like ó, you might try using this rule:

character map is "ó" = trap;

Hhowever, because you enter your read/write rules in a FrameMaker document, FrameMaker

interprets that rule as:

character map is 0x97 = trap;

which is not the behavior you want. Instead, you should use this rule:

character map is 0xF3 = trap;

• By default, FrameMaker maps the SGML broken bar character to the FrameMaker solid bar

character |. The rule for doing so could be written in the following equivalent ways:

character map is 0xA6 = "|";
character map is 0xA6 = 0x7C;
character map is "\xA6" = "\x7C";

• To trap the SGML broken bar character, use this rule:

character map is 0xA6 = trap;

See also

• For information on the FrameMaker character set, see the FrameMaker Character Sets guide.

• For details of the default mapping between the FrameMaker and ISO Latin-1 character sets, see

Chapter 11, “Character Set Mapping.”

convert referenced graphics

Use the convert referenced graphics rule to force the software to write out a graphic
file when exporting a graphic element that uses a referenced graphic. By default, FrameMaker
does not write out graphic files in this case. It is usually more advantageous to simply reference
the same graphic file in both the markup and the FrameMaker document. However, you can use
this rule to convert all such graphic files to a specific format.

Synopsis and contexts

element "gi" { . . .

writer facet "facetname" convert referenced graphics;
. . . }

Arguments

There are no arguments for this rule

Details

• This rule must be a subrule of a facet rule for a graphic element.

Structured Application Developer Reference 49

do not include dtd

• By default, if a graphic or equation element is imported by reference, the software does not

create a new graphic file for the element when exporting a FrameMaker document. You can

change that behavior using this rule.

Examples

• Assume you want to convert imported graphic files in graphic elements which have not

been edited in the FrameMaker document, to the PICT format. With the following example, the

software would create PICT files for each of these graphic elements:

element "graphic" {
is fm graphic element;

}}

• For graphic elements with a single TIFF facet, the following example converts the graphic files

in the graphic element to PICT:

element "graphic" {
is fm graphic element;
writer facet "TIFF"{

}}

writer {
facet default {

convert referenced graphics;
export to file "$(entity).pic" as "PICT";

convert referenced graphics;
export to file "$(entity).pic" as

"PICT";

See also

Related rules “facet” on page 72

“export to file” on page 67

“writer” on page 164

General information
on this topic

Developer Guide, page 367: Translating Graphics and Equations

do not include dtd

See “include dtd” on page 96.

Read/Write Rules Reference 50

do not include sgml declaration

do not include sgml declaration

See “include sgml declaration” on page 97.

do not output book processing instructions

See “output book processing instructions” on page 143.

drop

Use the drop rule to indicate information that you want discarded. Examples of information you
might discard include a markup element or attribute that has no counterpart in FrameMaker, or a
FrameMaker non-element marker that has no counterpart in markup.

Synopsis and contexts

1. attribute "attr" drop;

2. element "gi" drop;

3. element "gi" {. . .

attribute "attr" drop;
. . .}

4. external data entity reference drop;

5. fm attribute "attr" drop;

6. fm element "fmtag" drop;

7. fm marker type1 [, . . ., typen] drop;

8. fm variable drop;

9. processing instruction drop;

Arguments

attr The name of a markup or FrameMaker attribute. Note that fm

attribute names are case-sensitive and should appear as in the EDD.

The case of SGML attribute names depends on the setting of NAMECASE
in the SGML.dcl file—For XML attribute names are case sensitive.

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

type

i

A FrameMaker marker type, such as Index or Type 22.

Structured Application Developer Reference 51

drop

Details

• When FrameMaker encounters something to be discarded, it makes no attempt to insert the

corresponding information into the document it is creating. In the case of a dropped element,

it also discards all descendant elements.

• When creating an EDD from a DTD or schema, or a DTD from an EDD, FrameMaker does not

generate an element definition corresponding to a dropped element. It also removes any

references to the specified element in content rules for other elements unless you’ve specified

a preserve fm element definition rule for those elements.

• You can write a structure API client or XSLT stylesheet to process dropped information. Your

solution must also handle retrieving discarded information if it is needed when the document

is written back to its original format.

• If you use the drop rule in a rule, you can use no other subrules of the same rule. For example,

you cannot specify that FrameMaker both drop an attribute and translate it to a FrameMaker

property with the is fm property rule.

XSLT interaction

XSLT allows precise, context based equivalent processing to the FrameMaker drop rule. For
consistency and maintainabilty try to avoid mixing the methods used to drop FrameMaker or XML
elements.

Examples

• A markup element used instead of a processing instruction to indicate that a page or line break

is desired may be discarded when the markup document is read. Text formatting rules in the

EDD can be used to indicate a page break in FrameMaker; there is no need to mark the break

with an element. To drop the markup element break, use this rule:

element "break" drop;

• By default, FrameMaker stores processing instructions that it does not recognize in non-

element markers. In this way, even though FrameMaker does not perform special processing

on the processing instruction, when you save the FrameMaker document back to markup, the

software writes out the processing instruction so that a different application can use it. If you

don’t need to write out the processing instructions, you could use this rule:

processing instruction drop;

See also

Related rules “drop content” on page 53

“unwrap” on page 158

“preserve fm element definition” on page 144

Read/Write Rules Reference 52

drop content

Rules mentioned in
synopses

General information
on this topic

drop content

Use the drop content rule to either create a FrameMaker empty element or a markup element
with no content from occurrences of gi.

Synopsis and contexts

1. element "gi" {
is fm element "fmtag";
reader drop content;

}

“attribute” on page 44

“element” on page 54

“external data entity reference” on page 69

“fm attribute” on page 74

“fm element” on page 75

“fm marker” on page 76

“fm variable” on page 89

“processing instruction” on page 147

Developer Guide, Chapter 20, Translating Elements and Their Attributes

2. element "gi" {
is fm element "fm tag";
writer drop content;

}

Arguments

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

Details

• You can use this rule when you have an element whose content is created in a system-specific

way. If you plan to rely on some system to create the content, the existing content at the time
you import or export a document may not be relevant. For example, you may have a markup
element intended to contain a chapter number. In FrameMaker, you use FrameMaker’s
formatting capabilities to have the system maintain the value. When reading in the markup
document, you can drop the current content of the number element.

Structured Application Developer Reference 53

element

• Use drop content inside a reader rule when you translate markup documents to

FrameMaker documents. Use it inside a writer rule when you translate FrameMaker
documents to markup.

XSLT interaction

XSLT allows precise, context based equivalent processing to the FrameMaker drop content
rule. For consistency and maintainabilty try to avoid mixing the methods used to drop content.

Examples

• Assume your DTD has a toc element that represents the table of contents for a markup

document. FrameMaker can automatically generate a table of contents, which means that this
markup element can have its contents dropped upon import.

element "toc" reader drop content;

• Assume the total element’s content is computed by a structure API client. Outside the

FrameMaker environment you will use a different program to perform the computation.
Consequently, you do not want the value that is current when the document is exported. To
discard the current value, use this rule:

element "total" writer drop content;

element

See also

Related rules “drop” on page 51

“unwrap” on page 158

Rules mentioned in
synopses

General information
on this topic

You use the element rule as the primary rule for translating between a markup element and its
corresponding FrameMaker representation.

Synopsis and contexts

1. element "gi" {. . .

subrule;
. . .}

“element” on page 54

“reader” on page 149

“writer” on page 164

Developer Guide, Chapter 20, Translating Elements and Their Attributes

Structure Import/Export API Programmer’s Guide

Read/Write Rules Reference 54

element

2. element "gi" {. . .

transform;

subrule;

. . .}

Arguments

gi A markup element’s name (generic identifier).

transform The element rule can include a single transform subrule is used to map

to a FrameMaker object element.
is fm colspec specifies that the element represents a CALS table

colspec. This subrule applies only to CALS tables.

is fm cross-reference element specifies that the element

corresponds to a FrameMaker cross-reference element.

is fm element translates the element to a particular FrameMaker

element. You use this subrule to rename the element.

is fm equation element specifies that the element corresponds

to a FrameMaker equation element.

is fm footnote element specifies that the element corresponds

to a FrameMaker footnote element.

is fm graphic element specifies that the element corresponds to

a FrameMaker graphic element.

is fm marker element specifies that the element corresponds to a

FrameMaker marker element.

is fm span spec specifies that the element represents a CALS table

spanspec. This subrule applies only to CALS tables.

is fm system variable element specifies that the element

corresponds to a FrameMaker system variable element.

is fm table element specifies that the element corresponds to a

FrameMaker table element.

is fm table part element specifies that the element corresponds

to a FrameMaker element for a particular table part, such as a table title
or cell.

subrule The subrules of element indicate the treatment of the markup element

and its attributes.

attribute specifies what to do with a markup element’s attributes.
drop discards the element.

Structured Application Developer Reference 55

element

fm attribute specifies what to do with attributes present in the

FrameMaker representation of the element but not in the markup
representation of it.

fm property specifies what to do with FrameMaker properties

associated with the element. This subrule applies only to elements that
correspond to graphic, equation, table, table part, cross-reference, or
marker elements.

marker text is specifies whether the text of a FrameMaker marker

element should be element content or an attribute value in markup. This
subrule applies only to marker elements.

drop content specifies that the content but not the structure of an

element should be discarded on import of a markup document.

end vertical straddle indicates that the associated table cell or

row element terminates a vertical table straddle. This subrule applies only
to table cell or row elements.

insert table part element indicates that the software should

insert the specified table part (title, heading or footing), even if the
markup element structure does not contain the corresponding element.
This subrule applies only to table elements.

line break determines whether to interpret line breaks in text

segments in elements in the markup document as forced returns or
spaces within the elements.

start new row indicates that the occurrence of the associated table

cell element always starts a new row in the table. This subrule applies only
to table cell elements.

start vertical straddle indicates that the associated table cell

element starts a vertical table straddle. This subrule applies only to table
cell elements.

unwrap indicates that the content of the element, but not the element

itself, should be included in the translated document.

anchored frame tells FrameMaker what to do with graphic elements

other than those with a single non-internal FrameMaker facet. This
subrule applies only to graphic elements.

drop content specifies that the content but not the structure of an

element should be discarded on export of a FrameMaker document.
writer equation tells FrameMaker what to do with equation

elements. This subrule applies only to equation elements.

Read/Write Rules Reference 56

end vertical straddle

Details

If you use either the drop or unwrap subrule of an element rule, that subrule must be the
element’s only subrule. For example, you cannot both unwrap a markup element and translate it
to a FrameMaker element.

Examples

• To translate the markup element p to the FrameMaker element Paragraph, use this rule:

element "p" is fm element "Paragraph";

writer facet tells FrameMaker what to do with a graphic element that

has a single non-internal FrameMaker facet. This subrule applies only to
graphic elements.

writer line break limits the length of lines the software generates
in the markup document.

writer notation is specifies a notation name when the element is
a graphic or equation.

writer specify size in specifies the units of measure for the size
of a graphic or equation element.

• To translate the markup element tab2 to a FrameMaker table element Two Table with two

columns, use this rule:

element "tab2" {
is fm table element "Two Table";
fm property columns value is "2";
}

See also

Related rules “fm element” on page 75

General information
on this topic

end vertical straddle

Use the end vertical straddle rule inside the element rule for a table row or table cell
to specify that the row (or the row containing the cell) indicates the end of a vertical straddle

Developer Guide, Chapter 20, Translating Elements and Their Attributes

Structured Application Developer Reference 57

end vertical straddle

started by some earlier table cell element. The straddle can end either before the current row or
at the current row.

Synopsis and contexts

element "gi" {
is fm table row_or_cell element ["fmtag"];
reader end vertical straddle "name
[before this row];
. . .}

Arguments

gi A markup element’s name (generic identifier).

row_or_cell One of the keywords: row or cell.

fmtag A FrameMaker element tag. These names are case-sensitive and must

" [, . . . "namen"]

1

appear in the rule the same as in the EDD.

name

Details

i

A name associated with a table straddle. Each namei must occur in a
corresponding start vertical straddle rule.

• Your DTD may contain elements that you want to format as tables in FrameMaker even though

the element hierarchy does not match that required by FrameMaker for tables. In such a
situation, the nature of the element hierarchy may indicate where vertical straddles begin and
end. The end vertical straddle rule allows you to specify such elements.

• Use this rule in conjunction with the start vertical straddle rule. That rule specifies

a table cell that indicates the first cell in a vertical straddle. In the start vertical

straddle rule, give a name to the particular straddle started by that element. In the end

vertical straddle rule, you must specify by name which vertical straddles started by

earlier cells are ended by the occurrence of gi.

• If you use this rule for a table cell element, you can end only one vertical straddle. If you use it

for a table row element, you can end more than one vertical straddle.

• If you use this element without the before this row keyword phrase, the cell or row (gi)

specified in the rule becomes part of the straddle. If you do include that keyword phrase, then
the straddle ends in the row above the one specified.

Examples

For an example of the use of this rule, see “Creating vertical straddles” on page 360.

See also

Related rules “start vertical straddle” on page 156

Read/Write Rules Reference 58

entity

entity

General information
on this topic

You use the entity rule to translate an entity to an appropriate FrameMaker representation.

With this rule, you can translate an entity to a particular character or set of characters, a reference

element, a text inset, or a FrameMaker variable. If you choose to translate the entity to a text inset,
you can also specify how to format that text inset in the resulting document.

Synopsis and contexts

1. entity "ename" {

type_rule;
[format_rule;]
. . .}

2. reader entity "ename" {

type_rule;
[format_rule;]
. . .}

Arguments

Developer Guide, Chapter 22, Translating Tables

ename An entity name.

type_rule One of the following:

is fm char translates the entity to a particular character in

FrameMaker.

is fm reference element translates the entity to an element

whose content resides on a reference page in the FrameMaker document.

is fm text inset translates the entity to a FrameMaker text inset.
is fm variable translates the entity to a FrameMaker non-element

variable.

format_rule One of the following subrules can be specified, but only if type_rule is

is fm text inset:

reformat as plain text specifies that the software remove the

internal structure and formatting from the text of the text inset and apply
the formatting used at the insertion point.

reformat using target document catalogs specifies that the

software retain the text inset’s internal structure and apply the containing
document’s formats and element format rules to the text. This rule is

Structured Application Developer Reference 59

entity

applied as if the following three options were checked when a file is
imported through the File>ImportFile menu: 1. Reformat Using Target
Document’s catalog; 2. While importing Remove: Manual Page Breaks; and

3. While Importing Remove: Other Format Overrides. For more
information, see the section “Import text” in Chapter 9 of the Using
FrameMaker guide.

retain source document formatting specifies that the

software remove the internal structure of the text inset and retain the
formatting of the text inset as it appeared in the source document.

Details

• If you use the entity rule at the highest level, then it applies both on import and export. If

you use it inside a reader rule, then FrameMaker translates the entity as specified when
importing a markup document, but does not create an entity reference on export.

• For SGML, while you can use this rule to translate any entity type to a text inset, we recommend

you convert only SDATA entities to text insets. Note that the source file for such a text inset
must be a format FrameMaker can automatically filter. Also, such a text inset cannot use a
markup document as the source file.

• For XML and SGML, FrameMaker imports external text entities as text insets by default. The

source files for these insets can be markup or text files. The software stores entity information
on the Entity Declarations reference page so it can export the text inset as an external text
entity.

• For XML, SDATA and CDATA entities are not allowed.

Examples

• To translate the text entity mn to the FrameMaker variable Manual Name, use this rule:

entity "mn" is fm variable "Manual Name";

Suppose the text entity mn is declared as <!ENTITY mn "Developer’s Guide">, and
the template for the application does not contain a variable named Manual Name. Then the
software will create a FrameMaker variable named Manual Name defined as Developer’s
Guide and replace the reference in the text with the variable text Developer’s Guide.

However, if a FrameMaker variable named Manual Name, defined for example as My
Favorite Manual, currently exists in the template for the application, when importing
SGML, the software will not create a new variable nor modify the existing one. It will replace
the reference in the text with the variable text My Favorite Manual. When importing XML,
it does modify the variable definition.

Read/Write Rules Reference 60

entity name is

• To have FrameMaker create a text inset for the legalese entity using the text in the file

See also

legal.fm and to have the software format that text inset as it appears in legal.doc, use
this rule:

entity "legalese" {
is fm text inset "legal.fm";
retain source document formatting;
}

General information
on this topic

entity name is

Use the entity name is rule only in an element rule for a graphic or equation element to
provide information the software needs when writing a document containing graphics or
equations to markup. The entity name is rule determines the name FrameMaker gives an
entity reference it generates for the graphic or equation.

Synopsis and contexts

1. element "gi" {

is fm equation element ["fmtag"];
writer equation entity name is "ename";
. . .}}

2. element "gi" {

is fm graphic element ["fmtag"];
writer anchored frame entity name is "ename";
. . .}}

Developer Guide, Chapter 21, Translating Entities and Processing
Instructions

Developer Guide, Chapter 25, Translating Variables and System Variable
Elements

3. element "gi" {

is fm graphic element ["fmtag"];
writer facet "facetname" entity name is "ename";
. . .}}

Arguments

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

Structured Application Developer Reference 61

entity name is

facetname A facet name. The string for the facetname must exactly match the string

ename A string representing the base name for an entity name.

Details

By default, when FrameMaker exports an external data entity for a graphic or equation, it uses the
entity name that is stored with the graphic inset. If there is no such entity name, the software
generates a name for the entity based on the element name. You use the entity name is
rule to change this behavior.

The entity name you specify is a base name FrameMaker uses to generate a unique entity name.

When it needs to create a new entity name, FrameMaker adds an integer to the name specified

by ename to create a unique name.
If the keyword facet is used, the rule applies to a graphic element that contains only a single

facet with the name specified by facetname. This occurs when the graphic element is an
anchored frame containing only a single imported graphic object whose original file was in the
facetname graphic format. You can use this rule multiple times if you want FrameMaker to treat
several file formats differently.

for the facetname in the FrameMaker document. To determine a graphic
file’s facetname, select the graphic, click Graphics>ObjectProperties, and
observe the facetname in the dialog box.

Examples

• Assume you have a markup element graphic that corresponds to graphic elements in

FrameMaker. Suppose further that some of the graphic elements in FrameMaker contain
imported-by-copy graphics, or contain modifications to a graphic inset using FrameMaker
graphic tools, or contain just graphic objects drawn using FrameMaker graphic tools. On
export, the software must create new graphic files for these elements and declare entities for
them. By default, FrameMaker would declare entities for these graphic elements based on the
element name "graphic," for example, graphic1, graphic2, and so on. To specify that the
names of the entities associated with such successive graphic elements have the form car1,

car2, and so on, use this rule:

element "graphic" {
is fm graphic element;
writer anchored frame entity name is "car";
}

• Assume with a single facet graphics in the car element sometimes use the IGES file format and

sometimes use the TIFF file format. Also assume that the DTD for the application does not
currently contain entity declarations for the imported-by-reference graphic files. By default, the
software would declare entities for all such graphics based on the element name "car," for

Read/Write Rules Reference 62

equation

example, car1, car2, and so on. If you want to name the entities for the IGES graphics icar
and the entities for the TIFF graphics tcar, then use this rule:

element "car" {
is fm graphic element;
writer facet "IGES" entity name is "icar";
writer facet "TIFF" entity name is "tcar";
}

See also

Related rules “export to file” on page 67

“notation is” on page 141

“specify size in” on page 153

Rules mentioned in
synopses

General information
on this topic

equation

Use the equation rule only in an element rule for an equation element, to provide information
the software needs when writing to markup a document containing equations. FrameMaker
creates graphic files to represent equations. Use this rule to specify information about the files
FrameMaker creates for instances of the equation element. By default, the software creates a file
in CGM format for each equation, and the filename is based on the element name. Also, by default,
if the equation element is associated with an external data entity, then the entity name is based
on the element name.

“element” on page 54

“is fm graphic element” on page 111

“is fm equation element” on page 109

“anchored frame” on page 41

“equation” on page 63

“facet” on page 72

“writer” on page 164

Developer Guide, Chapter 23, Translating Graphics and Equations

Synopsis and contexts

element "gi" {
is fm equation element ["fmtag"];
writer equation subrule;
. . .}

Arguments

Structured Application Developer Reference 63

export dpi is

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

subrule An equation rule can have the following subrules:

entity name is tells the software how to create the base name for

the entity associated with this element type.

export to file tells the software to write a new file for the

associated external data entity.

notation is specifies the data content notation of the entity file.
specify size in specifies the units to use when writing the file.

Examples

Assume you have an element named math with an attribute of type Entity that is mapped to
the fm property entity for this element. If you want to create TIFF files for the equations in a
document named mytest.doc, you might use this rule:

element "math" {
is fm equation element;
writer equation export to file "$(docname).eqn" as "TIFF";
}

The software will create graphic files for each equation in mytest.doc named mytest1,
mytest2,...and will declare entities named math1, math2, ...for each graphic.

See also

Related rules “anchored frame” on page 41

“facet” on page 72

“is fm graphic element” on page 111

Rules mentioned in
synopses

General information
on this topic

“element” on page 54

“is fm equation element” on page 109

“writer” on page 164

Developer Guide, Chapter 23, Translating Graphics and Equations

export dpi is

You use the export dpi rule only in an element rule for a graphic or equation element, to
provide information the software needs when writing a document containing graphics or

Read/Write Rules Reference 64

export dpi is

equations to markup. The export dpi rule tells FrameMaker the dpi setting to use for an
exported graphic file.

Synopsis and contexts

1. element "gi" {

is fm equation element ["fmtag"];
writer equation
export dpi is number;

. . .

. . .}

2. element "gi" {

is fm graphic element ["fmtag"];
writer anchored frame
export dpi is number;

. . .

. . .}

3. element "gi" {

is fm graphic element ["fmtag"];
writer facet "facetname"
export dpi is number;

. . .

. . .}

Arguments

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

facetname A facet name. The string for the facetname must exactly match the string

for the facetname in the FrameMaker document. To determine a graphic
file’s facetname, select the graphic, click Graphics>ObjectProperties, and
observe the facetname in the dialog box.

number The required dpi value.

Details

• In the absence of this rule, FrameMaker uses the dpi setting associated with the graphic file. If

there is no setting associated with the graphic, the software assumes a value of 300.

• In Windows, if the initialization file for a graphics filter specifies a dpi setting that setting

overrides this rule whenever that filter is used to export a graphic file.

• If the keyword facet is used, the rule applies to a graphic element that contains only a single

facet with the name specified by facetname. This occurs when the graphic element is an

Structured Application Developer Reference 65

export dpi is

anchored frame containing only a single imported graphic object whose original file was in the
facetname graphic format. You can use this rule multiple times if you want FrameMaker to
treat several file formats differently.

Examples

• Assume you export the FrameMaker file Math.doc and have the following rule:

element "eqn" {
is fm equation element "Equation";
writer equation

export dpi is 72;

}

When FrameMaker finds an instance of the Equation element, it exports equations as graphic
files at 72 dpi.

• Assume you have the rule:

element "imp" {
is fm graphic element;
writer facet “TIFF”{

convert referenced graphics;
export dpi is 1200;
export to file "$(entity).tif";

}}

This rule tells FrameMaker for every graphic element with a single TIFF facet, it should write a
new graphic file with a dpi of 1200, using the entity name as part of the graphic file’s filename.

See also

Related rules “convert referenced graphics” on page 49

“entity name is” on page 61

“notation is” on page 141

“specify size in” on page 153

Rules mentioned in
synopses

General information
on this topic

“element” on page 54

“is fm graphic element” on page 111

“is fm equation element” on page 109

“anchored frame” on page 41

“equation” on page 63

“facet” on page 72

“writer” on page 164

Developer Guide, Chapter 23, Translating Graphics and Equations

Read/Write Rules Reference 66

export to file

export to file

You use the export to file rule only in an element rule for a graphic or equation element,
to provide information the software needs when writing a document containing graphics or
equations to markup. The export to file rule tells FrameMaker how to write the file name
when it creates a new graphic file, and optionally the graphic format for the file.

Synopsis and contexts

1. element "gi" {

is fm equation element ["fmtag"];
writer equation
export to file "fname" [as "format"];
. . .}

2. element "gi" {

is fm graphic element ["fmtag"];
writer anchored frame
export to file "fname" [as "format"];
. . .}

3. element "gi" {

is fm graphic element ["fmtag"];
writer facet "facetname"
export to file "fname" [as "format"];
. . .}

Arguments

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

facetname A facet name. The string for the facetname must exactly match the string

for the facetname in the FrameMaker document. To determine a graphic
file’s facetname, select the graphic, click Graphics>ObjectProperties, and
observe the facetname in the dialog box.

fname A base filename which can be either absolute or relative to the output

directory. Note: If path information is included in fname, use double
backslashes to translate path backslashes correctly. The fname argument
can contain the variables $(docname) and $(entity), described
below.

format A file data content format code, such as TIFF or PICT. See Developer Guide,

Chapter 23, Translating Graphics and Equations for a complete list of

graphic format codes. format must be one of these code names.

Structured Application Developer Reference 67

export to file

Details

• By default, if a graphic element has a single facet (other than a FrameMaker internal facet) that

was imported by reference, FrameMaker does not create a new graphic file. On export, the
original file will be associated with a markup graphic element via the file attribute, or via the

entity attribute plus a corresponding entity declaration. You can use the convert
referenced graphics rule to force FrameMaker to export such graphic files.

• If the keyword facet is used, the rule applies to a graphic element that contains only a single

facet with the name specified by facetname. This occurs when the graphic element is an
anchored frame containing only a single imported graphic object whose original file was in the
facetname graphic format. In this case, the rule is only executed if the convert

referenced graphics rule is also used. Otherwise, it is ignored.You can use this rule

multiple times if you want FrameMaker to treat several file formats differently.

• If your rules specify the software will write a graphic file, if a graphic element has a single facet

(other than a FrameMaker internal facet), FrameMaker writes the graphic file in that format by
default. It writes the graphic file for equation elements and all other graphic elements in CGM
format by default.

If you supply a format argument, you must first make sure that the format is one known to
FrameMaker. For information on which graphic export filters the software provides and on how
to add new ones, see Developer Guide, Chapter 23, Translating Graphics and Equations.

• The fname argument can use these variables:

Variable Meaning

$(entity) The value of the corresponding markup element’s entity attribute. If the

source of the graphic inset wasn’t originally an entity, this variable defaults to
a unique name based on the name of the element. You can change this name
using the entity name is rule.

$(docname) The name of the FrameMaker file, excluding any extension or directory

information.

• The fname argument is used as a template for the actual filename FrameMaker generates for

a particular graphic or equation element. FrameMaker takes the filename specified with the
fname argument and may append an integer to the filename to ensure uniqueness of the
filename. For an example of this behavior, see the first example below.

Examples

• Assume you export the FrameMaker file Math.fm and have the following rule:

element "eqn" {
is fm equation element "Equation";
writer equation
export to file "$(docname).eqn" as "PICT";
}

Read/Write Rules Reference 68

external data entity reference

When FrameMaker finds an instance of the Equation element, it generates filenames of the
form MathN.eqn until it finds a name that does not collide with an already existing file. For
example, if you already have files in the specified directory named Math1.eqn and
Math2.eqn, the software writes the first equation to a file named Math3.eqn. FrameMaker
writes the equation file in PICT format, instead of the default CGM format.

• Assume you have the rule:

element "imp" {
is fm graphic element;
writer facet "TIFF" {

convert referenced graphics;
export to file "$(entity).tif";

}}

This rule tells FrameMaker that if it encounters a graphic element with an imported graphic file
with a single TIFF facet, it should write that graphic to the file specified by $(entity).tif.

See also

Related rules “convert referenced graphics” on page 49

“entity name is” on page 61

“notation is” on page 141

“specify size in” on page 153

Rules mentioned in
synopses

General information
on this topic

“element” on page 54

“is fm graphic element” on page 111

“is fm equation element” on page 109

“anchored frame” on page 41

“equation” on page 63

“facet” on page 72

“writer” on page 164

Developer Guide, Chapter 23, Translating Graphics and Equations

external data entity reference

Use the external data entity reference rule to drop references to all external data
entities. By default, FrameMaker stores such references as the marker text in non-element Entity
Reference markers.

Synopsis and contexts

external data entity reference drop;

Structured Application Developer Reference 69

external dtd

ArgumentsNone.

Details

• In markup, the values of general entity name attributes, such as those used with graphics, are

not considered entity references. This rule does not affect how FrameMaker treats general
entity name attributes. In XML such entity name attributes are the only way to reference non­parsed entities such as graphics.

• When you translate a markup document to FrameMaker, when the software encounters an

external data entity reference such as:

&door;

it stores the reference as the text of a non-element DOC Entity Reference marker by default,
with the following marker text:

door

When you translate a FrameMaker document to markup, it outputs the marker text of non­element DOC Entity Reference markers as entity references.

Examples

To discard all external data entity references, use this rule:

external data entity reference drop;

See also

Rules mentioned in
synopses

General information
on this topic

external dtd

Use this rule to specify how an exported markup instance refers to the current structure
application’s DTD. By default, FrameMaker uses the name of the file containing the DTD as the
system identifier in the external identifier for the DTD. The external dtd rule provides the
software with a different external identifier. The different forms of the rule allow specification of a
system identifier, public identifier, or both.

Synopsis and contexts

1. writer external dtd is system;

2. writer external dtd is system "sysid";

3. writer external dtd is public "pubid";

“drop” on page 51

Developer Guide, Chapter 21, Translating Entities and Processing
Instructions

Read/Write Rules Reference 70

external dtd

4. writer external dtd is public "pubid" "sysid";

Arguments

sysid A system identifier.

pubid A public identifier.

Details

• Use this rule when you export FrameMaker documents to markup documents To use this rule,

you must have a DTD specified for the current structure application in the structapps.fm
file.

• By default, FrameMaker does not reproduce the DTD in the document type declaration subset.

Instead, it uses the filename of the DTD that was specified in the structure application to write
a document type declaration of the form:

<!DOCTYPE doctype SYSTEM "fname" [. . .

where doctype is the document type name and fname is the DTD filename specified in the
structure application. This rule allows you to specify different system and public identifiers.

• To output both external DTD and Schema with an XML document, use this rule and specify a

Schema file for output in the XML structure application (in structapps.fm). This rule
modifies how the external DTD is written.

To output Schema only, with no DTD, specify only the Schema file, not the DTD, in

structapps.fm. You do not need to use this rule.

• You cannot use the external dtd rule in the same read/write rules file as the include

dtd rule.

Examples

• To specify a local DTD as an external DTD and include the path with the filename, you could

use this rule:

writer

external dtd is
system "/doc/dtds/manuals.dtd";

Note that the Windows platform requires two backslashes in paths in the rules file in order to
translate as one backslash.

• To specify and locate the CALS DTD as an external DTD, you could use this rule:

writer external dtd is
public "-//USA-DOD//DTD MIL-M-38784B//EN"
"/doc/dtds/cals.dtd";

Structured Application Developer Reference 71

facet

• To specify just the CALS DTD as an external DTD using a public identifier, you could use this

rule:

writer external dtd is

public “-//USA-DOD//DTD MIL-M-38784B//EN”;

You could then specify the location of the DTD in the structure application using the
EntitiesLocation element. A DTD is an entity in the strictest sense.

See also

Related rules “include dtd” on page 96

“include sgml declaration” on page 97

“write structured document” on page 163

“write structured document instance only” on page 163

facet

Rules mentioned in
synopses

Use the facet rule only in an element rule for a graphic element, to provide information the
software needs when writing a document containing graphics to markup. The facet rule applies
only when a graphic element is an anchored frame containing only a single imported graphic
object whose original file was in the facetname graphic format. Use this rule to specify
information about the graphic file and/or entity declaration for instances of the graphic element.

Synopsis and contexts

element "gi" {
is fm graphic element ["fmtag"];
writer facet "facetname" subrule;
. . .}

Arguments

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

“writer” on page 164

appear in the rule the same as in the EDD.

facetname The name of the particular facet to which this rule applies, or “default”

for all facets.

subrule A facet rule can have the following subrules:

convert referenced graphics tells the software to create new

graphic files for imported graphic files with a single facet.

Read/Write Rules Reference 72

facet

entity name is tells the software how to create the base name for

the entity associated with this element type.

export to file tells the software the name to use for graphics it

creates, and optionally, the graphic format to which it should convert.

notation is specifies the data content notation of the entity.
specify size in specifies the units to use when writing the file.

Details

To specify all facets, use the keyword default for the facetname argument. For example:

element "pict" {

is fm graphic element "Picture";
writer {

facet default {
convert referenced graphics;
export to file "$(entity).tif" as "TIFF";
. . .

}}}

will convert every imported graphic file in the document to a TIFF file, no matter what its original
facet was.

Examples

By default, FrameMaker does not create a new graphic file for a graphic element that originated
as an external entity, and was not modified by the user in any way. Assume you want the software
to generate a graphic file for every imported TIFF file, whether it was modified or not. Then you
could use this rule:

element "pict" {
is fm graphic element "Picture";
writer {
facet "TIFF" {

convert referenced graphics;
export to file "$(entity).tif" as "TIFF";

}}}

See also

Related rules “anchored frame” on page 41

“convert referenced graphics” on page 49

“equation” on page 63

Structured Application Developer Reference 73

fm attribute

Rules mentioned in
synopses

General information
on this topic

fm attribute

You use the fm attribute rule with the “drop” subrule to discard an attribute that you’ve
defined for a FrameMaker element but that does not exist on the corresponding markup element.
Read/write rules do not support double-byte characters, so you cannot use this rule to drop
attributes with double-byte characters in their names.

Synopsis and contexts

1. fm attribute "attr" drop;

2. element "gi" {. . .

fm attribute "attr" drop;
. . .}

“element” on page 54

“is fm equation element” on page 109

“is fm graphic element” on page 111

“writer” on page 164

Developer Guide, Chapter 23, Translating Graphics and Equations

Arguments

attr A FrameMaker attribute name.

gi A markup element’s name (generic identifier).

Examples

• Assume the element chapter exists in both the markup and FrameMaker representations of

your documents. In FrameMaker, you use the XRefLabel attribute in formatting cross­references to this element. Since this attribute exists only for formatting purposes, you don’t
want it in the markup document. To drop this attribute on export, use this rule:

element "chapter" {
is fm element;
fm attribute "XRefLabel" drop;
}

• If you use the XRefLabel attribute on many elements for the same purpose, you can discard

it from all elements on export with this rule:

fm attribute "XRefLabel" drop;

Read/Write Rules Reference 74

fm element

• If you want to keep the XRefLabel attribute on the appendix element, but drop it from all

others, use these rules:

element "appendix" {
is fm element;
attribute "xreflab" is fm attribute "XRefLabel";
}
fm attribute "XRefLabel" drop;

Note that the order of these rules is not important. If you reversed them, the XRefLabel
attribute would still be correctly interpreted for the appendix element, since that reference
to the attribute is more specific. Note also that case is sensitive for fm attribute names.

See also

Related rules “attribute” on page 44

“is fm attribute” on page 101

Rules mentioned in
synopses

General information
on this topic

fm element

Use the fm element rule to tell FrameMaker what to do on export with FrameMaker elements
that do not correspond to markup elements. Read/write rules do not support double-byte
characters, so you cannot use this rule to process elements with double-byte characters in their
names.

Synopsis and contexts

1. fm element "fmtag" drop;

2. fm element "fmtag" unwrap;

Arguments

fmtag A FrameMaker element tag. These names are case-sensitive and must

Details

“element” on page 54

“drop” on page 51

Developer Guide, Chapter 20, Translating Elements and Their Attributes

appear in the rule the same as in the EDD.

• Use this rule when you export FrameMaker documents to markup documents.

• If you use this rule, you may want to write a structure API client to handle the export of the

element or to create it on import.

Structured Application Developer Reference 75

fm marker

• The first version of this rule discards the FrameMaker element on export. The second version

inserts the contents of fmtag in the corresponding markup document, but not fmtag itself.

• If you use this rule to unwrap FrameMaker cross-reference elements or system variable

elements, those elements become text in the resulting markup document.

XSLT interaction

XSLT allows precise, context based equivalent processing to the FrameMaker drop and unwrap
rules. For consistency and maintainabilty try to avoid mixing the methods used to drop or unwrap
FrameMaker elements.

Examples

• If Chapter Number is a FrameMaker element that you want to discard on export, use this

rule:

fm element "Chapter Number" drop;

If you use this rule and want to create this element on import, you need to write a structure
API client.

• If Modification Date is a FrameMaker system variable element that you wish to translate

to text on export to markup, use this rule:

fm element "Modification Date" unwrap;

See also

Related rules “element” on page 54

Rules mentioned in
synopses

General information
on this topic

fm marker

On export, you use the fm marker rule to tell FrameMaker what to do with non-element
markers other than markers of the type reserved for storing processing instructions, PI entities,
and external data entities. (By default, Structure PI markers are reserved for processing
instructions, and Entity Reference markers are reserved for external data entities.) In the absence
of a rule to the contrary, the software creates processing instructions for non-element markers.

“is fm element” on page 108

“drop” on page 51

“unwrap” on page 158

Developer Guide, Chapter 20, Translating Elements and Their Attributes

Read/Write Rules Reference 76

fm marker

You can also choose to discard them. Read/write rules do not support double-byte characters, so

you cannot use this rule to process markers with double-byte characters in their names.

Synopsis and contexts

fm marker ["type1", . . ., "typen"] drop;
fm marker ["type1", . . ., "typen"] is processing instruction;

Arguments

type

i

Details

• If type

If no typei is specified, this rule applies to all non-element markers other than markers of the
reserved type. For information on what the software does with the reserved marker type, see

Developer Guide, Chapter 26, Translating Markers

is specified, this rule applies only to markers of that type.

i

The name of a FrameMaker marker type.

• You can have multiple occurrences of this rule in a rules file, to determine different treatment

for different FrameMaker markers. You can have only one occurrence of the rule with no
explicitly listed markers. A given marker type can be explicitly mentioned in only one
occurrence of this rule.

• The order of fm marker rules is not important. A more specific occurrence of the rule always

takes precedence over a more general occurrence. For example, the following rules:

fm marker "Index" is processing instruction;
fm marker drop;

have the same effect, exporting only index markers as processing instructions, if they occur in
this order:

fm marker drop;
fm marker "Index" is processing instruction;

XSLT interaction

XSLT allows precise, context based equivalent processing to the FrameMaker drop rule. For
consistency and maintainabilty try to avoid mixing the methods used to drop FrameMaker non­element markers.

Examples

• To discard all non-element markers, use this rule:

fm marker drop;

• To discard non-element conditional text markers but retain all others as processing

instructions, use this rule:

fm marker "Conditional Text" drop;

Structured Application Developer Reference 77

fm property

• To retain only Index and Hypertext markers as processing instructions and drop all other non-

element markers, use the following set of rules:

fm marker "Index", "Hypertext" is processing instruction;
fm marker drop;

See also

Related rules “is fm marker element” on page 112

Rules mentioned in
synopses

General information
on this topic

fm property

You use the fm property rule to determine values for properties defined for certain types of
FrameMaker constructs that you do not want to represent as markup attributes.

Synopsis and contexts

1. Cross-reference elements

element "gi" {
is fm cross-reference element ["fmtag"];
fm property cross-reference format value is val;
. . .}

1.1 Arguments

val A valid cross-reference format name. These names are case-sensitive and

“drop” on page 51

“is processing instruction” on page 138

Developer Guide, Chapter 26, Translating Markers

must appear in the rule the same as in the structure application’s
template.

2. Graphic elements, equation elements, or MathML equations

element "gi" {
is fm graphic_or_equation element ["fmtag"];
fm property prop value is "val";
. . .}

2.1 Arguments

prop • alignment Indicates the anchored frame’s

horizontal alignment on the page.

val

– aleft Align left

Read/Write Rules Reference 78

fm property

– acenter Align center
– aright Align right
– ainside Align inside, or closest to the binding margin.
– aoutside Align ouside, or farthest from the binding margin.

• angle Indicates an angle of rotation for the anchored frame that

contains the graphic. You must specify exact multiples of 90 degrees.
Otherwise, the value is ignored and the graphic is imported at 0
degrees (default).

val examples:
– 0 No rotation (default)
– 90 Rotate 90 degrees clockwise
– -90 Rotate 90 degrees anticlockwise
– 180 Rotate 180 degrees
– 270 Rotate 270 degrees.

• baseline offset Indicates how far from the baseline of a

paragraph to place an anchored frame. Baseline offset is relevant only
for anchored frames whose position attribute is one of inline, sleft,
sright, snear, or sfar.

val A number plus a valid unit of measure, e.g. “12pt”, “10mm”. If not
supplied, the value is 0.

• cropped Indicates whether a wide graphic should be allowed to

extend past the margins of the text frame. The cropped property is
relevant only for anchored frames whose position attribute is one
of top, below, or bottom.

val

– 0 The graphic may extend past the margins of the text frame.
– 1 (Default) The graphic is cropped at the margins of the text frame.

• dpi Indicates how to scale an imported graphic object.

val The value of the dpi attribute must be an integer greater than 0.
If not supplied, the default value is 72.

• entity Provides the entity name of the imported graphic. This rule

limits the graphic import to a single, fixed file for all instances of the
element.

val A valid entity name as defined in an entity declaration in the
markup instance.

• file Provides the file name of the imported graphic. This rule limits

the graphic import to a single, fixed file for the element.
val A valid file name for an imported graphic.

Structured Application Developer Reference 79

fm property

• floating Indicates whether the graphic should be allowed to float

from the paragraph to which it is attached. The floating property is
relevant only for anchored frames whose position property is one
of top, below, or bottom.

val

– 0 (Default) No float, the graphic must stay with the paragraph.
– 1 Allow float.

• height Indicates the height of the anchored frame.

val The value for a single imported graphic object is the sum of the
height of the object plus twice the value of the vertical offset property.

• horizontal offset Indicates how far the graphic object is offset

from the right and left edges of the anchored frame.
val A number with a valid unit of measure. If not supplied, the

delault value is 6.0pt.

• import angle Indicates an angle of rotation in degrees for the

graphic inside its anchored frame.
val A real number, if not supplied, the default value is 0.0.

• import by reference or copy Indicates whether an

imported graphic object remains in a separate file or is copied into the
FrameMaker document on import from markup.

val

– ref (Default) The object is referenced and will not be copied into

the document.

– copy The object will be copied into the document.

• import size indicates the size of the imported graphic object by

specifying a width and height.
val Two numbers, separated by a space, with a valid units of

measure. The first measurement is the width and the second is the
height. If no unit of measure is supplied, points are assumed. Example:

“100mm 50mm”.

• near-side offset Indicates how far to set a frame from the text

frame to which the frame is anchored. It is relevant only for anchored
frames whose position attribute is one of sleft, sright, snear, or
sfar.

val A number plus a valid unit of measure, e.g. “12pt”, “10mm”. If not
supplied, the value is 0.

• position Indicates where on the page to put the anchored frame.

If not supplied, the value is below.

Read/Write Rules Reference 80

fm property

val Possible anchoring position values are as follows:
– inline At insertion point.
– top At top of column.
– below Below current line.
– bottom At bottom of column.
– sleft Outside column - left side.
– sright Outside column - right side.
– snear Outside column - right side.
– sfar Outside column - side closer to the page edge.
– sinside Outside column - side closer to the binding.
– soutside Outside column - side farther from the binding.
– tleft Outside text frame - left side.
– tright Outside text frame - right side.
– tnear Outside text frame - side closer to the page edge.
– tfar Outside text frame - side farther from the page edge.
– tinside Outside text frame - side closer to the binding.
– toutside Outside text frame - side closer to the binding.
– runin Run into paragraph.

• sideways Indicates that the imported graphic will be flipped left to

right to give a mirror image.

val

– 0 (Default) No flip.
– 1 Flip left/right.

• vertical offset Indicates how far the graphic object is offset

from the top and bottom edges of the anchored frame.
val A number plus a valid unit of measure. If not supplied, the

delault value is 6.0pt.

• width Indicates the width of the anchored frame.

val The value for a single imported graphic object is the sum of the
width of the object plus twice the value of the horizontal offset
property.

• poster The name of the file displayed as the poster for an imported

media file. For SWF files, FrameMaker displays the first frame of the SWF
file as the poster. For a SWF file whose first frame cannot be read, and
for all other media types, FrameMaker displays the relevant
placeholder image.

val A valid path to the location of the poster file.

Structured Application Developer Reference 81

fm property

• graphic name A name assigned to the imported object, for easy

identification when linking to it.
val A string representing the graphic name.

• activate in PDF A boolean value indicating whether or not the

graphic element is activated when the PDF file containing it, is opened.

The default value is False.

val

– 0 (Default) Not activated in PDF.
– 1 Activated in PDF.

• open in pop-up window A boolean value indicating whether or

not the graphic element in a PDF file is displayed in a new frame, when
clicked.

val

– 0 (Default) Not opened in pop-up window.
– 1 Opened in pop-up window.

• javascript file The JavaScript file that is attached to the

graphic object with a U3D facet.
val A valid path to the location of the JavaScript file.

• U3D view The object perspectives available for a 3D object. The

selected view is rendered when the document is saved. All predefined
views of the 3D object are available when the document is converted
to a PDF file. The last view that you selected in the document, before
saving, becomes the default view in the PDF.

val A valid object perspective available for the 3D object.

• background color The color of the background for the anchored

frame containing the 3D file.
val A valid color for the background.

• render mode The rendering mode for an imported 3D object. The

default value is Solid.
val A valid rendering mode.

• lighting The lighting scheme to cast a 3D object using different

light sources. The default lighting scheme for all 3D objects is Lights
From File.

val A valid lighting scheme for casting the 3D object.

• link to text A 3D object and a destination marker that links the

object to text in the document.

Read/Write Rules Reference 82

fm property

val Number of links from the 3D object and link name - destination
marker pairs.

For example, linktotext="2;Ground_Plane=newlink

aa;Blue_Sphere=newlink cc;"

• compose Dpi The resolution, in Dpi, of the image composed by the

MathML editor for a MathML object, displayed in FrameMaker.
val A valid resolution for the MathML object.

• alt text The text that is displayed when a graphic element cannot

be rendered.
val A string for the alternate text.

• font size The size of the font used for MathML objects.

val A valid size for the MathML object fonts.

3. Marker elements

element "gi" {
is fm marker element ["fmtag"];
fm property prop value is val;.
. . .}

3.1 Arguments

prop • marker text Provides a fixed text string for all instances of the

marker.
val Any valid marker text string.

• marker type Identifies the type of marker if not provided by a

markup attribute.
val A valid marker type name.

4. Table elements

element "gi" {
is fm table element ["fmtag"];
fm property prop value is val;.
. . .}

4.1 Arguments

prop • column ruling Specifies whether all columns should have ruling

on their right side. This property does not specify the style or weight
of the ruling. The default ruling is defined by the relevant table format
in the structured template.

val

– 0 Columns have no ruling.

Structured Application Developer Reference 83

fm property

– 1 Columns have ruling.

• column widths The width of successive columns in the table. On

import from markup these widths are reapplied regardless of any
changes made by the user.

val Each value is either an absolute width or a width proportional to
the size of the entire table. If proportional widths are used, the pgwide
attribute or page wide property determines the table overall width.
Example for a three column table:

“22mm 40mm 100mm”.

• columns The number of columns in the table. This is essential to the

correct rendering of the table if the markup does not state the number
of columns as an attribute value.

val An integer greater than 0.

• page wide This is relevant only to tables whose columns use

proportional widths on pages with more than a single column. In this
case, the attribute indicates whether the entire table should be the
width of the column in which it is anchored, or the width of the overall
text frame.

val

– 0 (Default) The table is the width of the text column.
– 1 The table is the width of the text frame.

• row ruling Specifies whether all rows should have ruling on their

bottom side. This property does not specify the style or weight of the
ruling. The default ruling is defined by the relevant table format in the
structured template.

val

– 0 Rows have no ruling.
– 1 Rows have ruling.

• table border ruling Specifies whether the table should have

ruling around its outside borders. This property does not specify the
style or weight of the ruling. The default ruling is defined by the
relevant table format in the structured template.

val

– all Rows have no ruling.
– top Rows have ruling.

• table format Specifies the table format for all instances of the

FrameMaker table element.
val A name of a table format that is present in the application’s

structured template.

Read/Write Rules Reference 84

fm property

5. Table cell elements

element "gi" {
is fm table cell element ["fmtag"];
fm property prop value is val;.
. . .}

5.1 Arguments

prop • column name Associates a name with a cell in a given column.

val A valid column name as defined in a colspec.

• column number Indicates the column number that the cell will start

in. This rule is used when the column number is not available in the
markup and requires each cell in a given row to have a unique element
name.

val An integer greater than 0.

• column ruling Specifies whether the cell should have ruling on

its right side. This property does not specify the style or weight of the
ruling. The default ruling is defined by the relevant table format in the
structured template.

val

– 0 Cell has no right side ruling.
– 1 Cell has right side ruling.

• end column name Specifies the name of a column that ends a

straddle.
val A valid column name as defined in a colspec.

• horizontal straddle Specifies the number of columns a

straddled cell spans.
val An integer greater than 1 and no greater than the number of

columns.

• more rows Specifies the number of additional rows a straddled cell

spans.
val An integer greater than 1 and no greater than the number of

rows in the table part. The total number of rows the cell occupies is

more rows+1.

• rotate Indicates how much to rotate the contents of a cell.

val The CALS model restricts this property to a boolean value, where
1 indicates a rotation of 90 degrees anti-clockwise. FrameMaker
extends the possible values to allow rotations of 0, 90, 180, and 270
degrees.

Structured Application Developer Reference 85

fm property

• row ruling Specifies whether the cell should have ruling on its

bottom side. This property does not specify the style or weight of the
ruling. The default ruling is defined by the relevant table format in the
structured template.

val

– 0 Cell has no bottom side ruling.
– 1 Cell has bottom side ruling.

• span name Applies a predefined CALS spanspec, starting at this cell.

val A valid spanspec name.

• start column name Specifies the name of a column that begins

a horizontal straddle.
val A valid column name as defined in a colspec.

• vertical straddle Specifies the number of rows a straddled cell

spans.
val An integer greater than 1 and no greater than the number of

rows in the section (head, body or foot) of the table that contains the
starting cell.

• cell angle Specifies the angle of rotation

val The degrees.

• use fill override Specifies whether a custom fill percentage

overrides the fill percentage specified in the table format.

val

– 0 Cell has no fill override.
– 1 Cell has fill override.

• fill override Specifies the fill percentage for the cell.

val A valid fill percentage.

6. Table row elements

element "gi" {
is fm table row element ["fmtag"];
fm property prop value is val;.
. . .}

6.1 Arguments

prop • maximum height Specifies the maximum height for each row in

the table.
val A number plus a valid unit of measure, e.g. “24pt”, “15mm”. If not

supplied, the maximum height of the row is not limited.

Read/Write Rules Reference 86

fm property

• minimum height Specifies the minimum height for each row in the

table.
val A number plus a valid unit of measure, e.g. “12pt”, “9mm”. If not

supplied, the minimum height of the row is not limited.

• row type Sets the row type.

val

– heading
– body
– footing

• row ruling Specifies whether the cell should have ruling on its

bottom side. This property does not specify the style or weight of the
ruling. The default ruling is defined by the relevant table format in the
structured template.

val

– 0 Cell has no bottom side ruling.
– 1 Cell has bottom side ruling.

7. For CALS table colspecs:

element "gi" {
is fm colspec;
fm property prop value is val;
. . .}

7.1 Arguments

prop • cell alignment character

• cell alignment offset

• cell alignment type

• column name

• column number

• column ruling

• column width

• row ruling

• vertical alignment

8. element "gi" {

is fm spanspec;
fm property prop value is val;
. . .}

Structured Application Developer Reference 87

fm property

8.1 Arguments

prop

• cell alignment character

• cell alignment offset

• cell alignment type

• column ruling

• end column name

• row ruling

• span name

• start column name

• vertical alignment

9. Used at the top level

fm property prop value is “val”;

9.1 Arguments

gi A markup element’s name (generic identifier).

fmtag A FrameMaker element tag. These names are case-sensitive and must

appear in the rule the same as in the EDD.

Details

• This rule applies only to an element corresponding to a cross-reference, graphic, equation,

marker, table, or table part element.

• Some FrameMaker properties have no natural markup counterparts. If you choose to not

translate such properties as markup attributes, a markup document will not contain
information on appropriate values for these properties. In this situation, you can use the fm

property rule to explicitly set property values when reading a markup document.

• This rule can be used either at the highest level to set a default or within an element rule to

specify the translation of a property for a particular element.

• If you use this rule to set a property value explicitly, you cannot also have a markup attribute

that corresponds to this property. For example, the following rule is erroneous:

element "tab2" {
is fm table element;
attribute "w" is fm property column widths;
fm property column widths value is "1in 2in";
}

Read/Write Rules Reference 88

fm variable

Examples

• To translate the markup element table to a FrameMaker table with two columns:

element "table" {
is fm table element;
fm property columns value is "2";
}

On import to FrameMaker, the software creates the table as a 2-column table in FrameMaker.

• Assume you have a markup element halfpage that holds a 4.5 inch by 6.5 inch graphic

object; it does not use an attribute to store the size information. You can translate this to a
FrameMaker graphic as follows:

element "halfpage" {
is fm graphic element;
fm property width value is "6.5";
fm property height value is "4.5";
}

See also

Related rules “is fm property” on page 114

“is fm property value” on page 122

General information
on this topic

fm variable

On export, use the fm variable rule to tell FrameMaker what to do with certain variables. Use
this rule if you do not want them translated to entities. Read/write rules do not support double­byte characters, so you cannot use this rule to process variables with double-byte characters in
their names.

Synopsis and contexts

fm variable ["var1", . . ., "varn"] drop;

Arguments

var

i

Developer Guide, Chapter 22, Translating Tables

Developer Guide, Chapter 23, Translating Graphics and Equations

Developer Guide, Chapter 24, Translating Cross-References

Developer Guide, Chapter 26, Translating Markers

The name of a FrameMaker variable.

Structured Application Developer Reference 89

fm version

Details

• Use this rule when you export FrameMaker documents to markup documents. It applies only

to non-element variables, not to system variable elements.

• If var

applies to all variables.

is specified, this rule applies only to that variable. If no vari is specified, this rule

i

• If you use this rule, you may want to write a structure API client, or use an XSLT transform to

handle the export of variables or to create variables on import.

• You can have multiple occurrences of this rule in a rules document to determine different

treatment for different FrameMaker variables. You can have only one occurrence of the rule
with no explicitly listed variables. A given variable can be explicitly mentioned in only one
occurrence of this rule.

Examples

To translate the FrameMaker variables Licensor and Product as entities and discard all other
variables, use these rules:

entity "licensor" is fm variable;
entity "product" is fm variable;
fm variable drop;

See also

Related rules “is fm system variable element” on page 129

General information
on this topic

Developer Guide, Chapter 21, Translating Entities and Processing
Instructions

Developer Guide, Chapter 25, Translating Variables and System Variable
Elements

Structure Import/Export API Programmer’s Guide

fm version

The fm version rule specifies the version of the product being run. It is required and must be
the first rule in all rules documents. If you create your rules document with the New Read/Write
Rules command, this rule automatically appears in the document.

Synopsis and contexts

fm version is "8.0";

ArgumentsNone.

Read/Write Rules Reference 90

generate book

Details

Note that you would use the string "8.0" in this rule even though the product version may be
an incremental release above 8.0, such as 8.0.1.

See also

General information
on this topic

generate book

Use the generate book subrule of a highest-level reader rule to specify whether FrameMaker
should use elements or processing instructions to indicate where in a markup document to start
a book and its components in the corresponding FrameMaker book.

Synopsis and contexts

1. reader generate book

use processing instructions;

2. reader generate book

{
put element "gi1" in file ["fname1"];
. . .
put element "giM" in file ["fnameM"];
}

3. reader generate book [for doctype "dt1" [, . . . "dtN"]]

{
put element "gi1" in file ["fname1"];
. . .
put element "giM" in file ["fnameM"];
}

Developer Guide, Chapter 18, Read/Write Rules and Their Syntax

Arguments

dt

i

gi

j

fname

j

Structured Application Developer Reference 91

A document type name.

A generic identifier.

A filename for the book component. FrameMaker adds a counter to the
name (before the suffix if there is one) as needed, to generate a unique
filename. You can use the $(bookname) variable to base the
component’s filename on the book filename (excluding any suffix). If you
do not supply this argument, the filename is gij.doc.

generate book

Details

• By default, when reading a markup document into FrameMaker, the software uses the <?FM

• Your DTD may be defined so that you can use elements to indicate the start of a book and its

book ?> and <?FM document ?> processing instructions to indicate the start of a book

and of its components. The following rule confirms this default behavior:

reader generate book
use processing instructions;

components. When you use the second form of the generate book rule, FrameMaker
creates a book for every markup document you translate. When you use the third form of the
generate book rule, it creates a book only for markup documents whose DTD specifies the
document type you’ve listed in the rule. If you have a markup document with a different
document type, FrameMaker translates that document as a single FrameMaker document, even
if it contains elements referenced in put element rules. For example, assume you have this
rule:

reader generate book for doctype "manual"
put element "chapter" in file;

If you translate a markup document whose highest-level element is report, that document
becomes a single FrameMaker document, even if it contains chapter descendant elements.

• When it encounters one of the gi

FrameMaker starts a new book component. Since the software does not allow an element to
be broken across files, it places the entire gij element in the same file, even if another element
appears that you’ve said should start a new file. To illustrate, assume the section element can
occur either within or outside of a chapter element and you have this rule:

reader generate book {
put element "chapter" in file;
put element "section" in file;
}

When FrameMaker encounters a chapter element, it starts a new file. If it encounters a
section element as a child of that chapter element, it does not start a new file. It continues

with the file started by the chapter element. On the other hand, if the software encounters
a section element outside a chapter element it does start a new file for it.

elements specified in a put element subrule,

j

• Consider these points when dividing a markup document into book components:

– Every FrameMaker document must contain exactly one highest-level element. That is, there

cannot be two elements in a single file that do not have an ancestor element in the same
file.

– A book element can contain substructure but cannot directly contain text. That is, child

elements that can contain text must occur in separate files.

Assume you have this rule:

reader generate book
put element "chapter" in file;

Read/Write Rules Reference 92

generate book

• By default, when it writes a FrameMaker book to markup, the software writes <?FM book ?>

And you have a markup document with the following element structure:

<manual>

<chapter>

<head>Introduction</head>

. . .
</chapter>
<appendix>

<head>The final word</head>

. . .
</appendix>

</manual>

When FrameMaker translates this document, it creates a book with manual as the highest-
level element in the book file. When it encounters the chapter element, the software starts
a new file for that element. When it encounters the appendix element, FrameMaker flags an
error, because your rules have not told it what to do with this element. It cannot put the
element in the same file as the preceding chapter element, because that would create two
highest-level elements in the same file. It also cannot put the appendix element in the book
file, because it contains text.

and <?FM document ?> processing instructions for the book and book components. It does
this even if you use the generate book rule to have particular elements specify book
components when reading a markup document. If you do not want FrameMaker to output
these processing instructions, use writer do not output book processing

instructions.

Examples

• If you know that a markup document should always correspond to a FrameMaker book and

that individual files in the book should start when the document reaches a toc or chapter
element, you can use this rule:

reader generate book {
put element "toc" in file;
put element "chapter" in file "ch.doc";
}

With this rule, FrameMaker creates a book for each markup document. In a markup document,
FrameMaker starts a new book component when it encounters a toc or chapter element.
For the first toc element, FrameMaker uses the filename toc1 unless a file of that name
already exists in the directory it is using. It continues that book component until it encounters
either another toc element or a chapter element. At that point, it starts a new book
component. It tries to put the first chapter element in a file called ch1.doc.

• Assume that a markup document whose highest-level element is either manual or book

should correspond to a FrameMaker book and any other markup document should correspond
to an individual FrameMaker document. Further assume that the books created from manual

Structured Application Developer Reference 93

implied value is

See also

Related rules “output book processing instructions” on page 143

and book elements should have new files for each instance of the elements chapter, front,
or toc. To accomplish all this, you can use this rule:

reader generate book for doctype "manual", "book"
{
put element "chapter" in file "ch.doc";
put element "front" in file;
put element "toc" in file "$(bookname).toc";
}

With this rule, FrameMaker asks you for a name for the book file if you open a markup
document with manual as its document type. If you specify myfile.book as its name, and
the document contains two chapter elements, one front element, and one toc element,
FrameMaker creates the following files: myfile.book, ch1.doc, ch2.doc, front, and
myfile.toc.

General information
on this topic

implied value is

Use the implied value is rule to specify default attribute values in your EDD to correspond
with imported elements that specify no value for the attribute. For example, assume your DTD
declares an element named list, which has an attribute named style defined as
<!ATTLIST list style (bul | num) #IMPLIED>. For importing the DTD, you can use
this rule to set up a default value in the EDD for the Style attribute of the List element. Then,
if you import a list element that has no value for style, this default attribute value will be used
for formatting purposes. Also, when you export the EDD, the DTD will declare the style attribute
for the list element as #IMPLIED.

Synopsis and contexts

1. attribute "attr" {. . .

implied value is "val";
. . .}

2. element "gi" {. . .
attribute "attr" {. . .
implied value is "val";
. . .} . . .}

Developer Guide, Chapter 28, Processing Multiple Files as Books

Arguments

attr The name of an impliable attribute in markup.

Read/Write Rules Reference 94

implied value is

val A value to use for the attr attribute.

gi A markup element’s name (generic identifier).

Details

• This rule is for importing DTDs and exporting EDDs. In FrameMaker, a default attribute value

• This rule specifically does not supply an attribute value for an element that has no value in the

• The rule can be used in a highest-level attribute rule to specify the value to use for that

Examples

Assume you have these declarations for a markup element used for cross-references:

can only be specified in the EDD, so this rule has no effect when importing a markup instance
or exporting a FrameMaker document.

markup instance. It only sets up a default attribute value in the EDD. This default value can be
used for formatting by attributes. When you export the document, FrameMaker will not add a
value for the attribute to the element’s start tag.

attribute in any element. Alternatively, it can be used in an attribute rule within an

element rule to specify the value for that element only.

<!ELEMENT xref EMPTY>
<!ATTLIST xref
id IDREF #IMPLIED
format CDATA #IMPLIED>

And you have this rule:

element "xref" {
is fm cross-reference element;
attribute "format" {
is fm property cross-reference format;
implied value is "Page";
}}

When FrameMaker encounters an instance of the xref element in a markup document and that
instance does not have a value for the format attribute, the software use the Page cross­reference format for the cross-reference in the FrameMaker document.

See also

Related rules “value” on page 161

Rules mentioned in
synopses

General information
on this topic

Structured Application Developer Reference 95

“attribute” on page 44

“element” on page 54

Developer Guide, Chapter 20, Translating Elements and Their Attributes

“Default value” on page 198

include dtd

include dtd

By default, when creating a markup document, FrameMaker includes in the document type
definition an external identifier that refers to the DTD file. Therefore, it does not include a copy of
actual declarations in the document type declaration subset. The include dtd rule tells
FrameMaker to do so.

Synopsis and contexts

writer [do not] include dtd;

ArgumentsNone.

Details

• You use this rule when you export FrameMaker documents to markup documents. If this rule

is specified, FrameMaker does not generate an external identifier in the DOCTYPE declaration.

• To confirm the default behavior, you can use the opposite rule:

• The include dtd rule and the external dtd rule are mutually exclusive. That is, you

cannot use both of these rules in the same read/write rules file. (If you try to put both of these
rules in the same file, you will get an alert.) Also, the include dtd rule and the write

structure document instance only rule are mutually exclusive.

writer do not include dtd;

• To write an entire markup document, including a DTD and (for SGML) an SGML declaration with

the document instance, you must use the following rules:

writer {

include sgml declaration;
include dtd;

}

• This rule uses the DTD that is specified in the current structure application. If that DTD includes

references to external files, this rule does not expand those references as it writes out the DTD.
Instead, it writes out the references as they appear in the parent DTD file.

• You can use this rule to translate the EDD from the current document as an a DTD that is

written in the markup document. To do this, use the include dtd rule, but use a structure
application that does not specify a DTD in its definition. Be warned that if your document uses
the CALS table model, the resulting DTD may be incorrect.

• When you use this rule, no Schema information is included in the output. If you use this rule

to output an internal DTD and the XML structure application specifies a Schema file for export,
that file is converted to internal DTD (see Chapter 6, “XML Schema to DTD Mapping”) and that
DTD is saved with the markup document.

If the XML structure application specifies both a Schema file and a DTD, the DTD is output as
the internal DTD and the Schema is dropped.

Read/Write Rules Reference 96