Adobe 65030365 - FrameMaker - PC Instruction Manual

Adobe, the Adobe logo, Acrobat, Acrobat Reader, Adobe Type Manager, ATM, Display PostScript, Distiller, Exchange, Frame, FrameMaker,
FrameViewer, InstantView, and PostScript are trademarks of Adobe Systems Incorporated. Apple, PowerBook, QuickTime, Mac, Macintosh and
Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. HP-UX is a registered trademark of
Hewlett-Packard Company. Microsoft, MS-DOS, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corpora-
tion in the United States and/or other countries. Sun and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States
and other countries. Unix is a registered trademark and X Window System is a trademark of The Open Group. All other trademarks are property of
their respective owners. © 2003 Adobe Systems Incorporated. All rights reserved.

Structure Application Developer’s Guide iii
Contents
Before You Begin - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - xv
Part I Developing a FrameMaker structure application
Chapter 1 What’s New in FrameMaker - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3
What’s new in FrameMaker 7.1 . . . . . . . . . . . . . . 3
Conditional text . . . . . . . . . . . . . . . . . . . . . . . . 3
External cross-references . . . . . . . . . . . . . . . . 3
Preserving the XML extension . . . . . . . . . . . . . 3
Priority of variable definitions . . . . . . . . . . . . . . 4
What’s new in FrameMaker 7.0 . . . . . . . . . . . . . . 4
Path and filename changes . . . . . . . . . . . . . . .4
Application development. . . . . . . . . . . . . . . . . .5
Read/write rules . . . . . . . . . . . . . . . . . . . . . . . .5
Namespaces. . . . . . . . . . . . . . . . . . . . . . . . . . .5
CSS support . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Exporting variables to markup . . . . . . . . . . . . .5
New starter kits. . . . . . . . . . . . . . . . . . . . . . . . .6
Chapter 2 Structure Application Basics - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7
Where to begin. . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Structure application scenarios . . . . . . . . . . . . . . 7
Translating in one or two directions? . . . . . . . . 7
Can you simplify when translating in only one
direction? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Do you have an existing DTD or EDD? . . . . . . 8
Structure application development . . . . . . . . . . . .9
The starting point: an EDD or DTD. . . . . . . . .11
Translation between DTDs and EDDs . . . . . .11
Formatting information in FrameMaker. . . . . .11
Changing the default translation. . . . . . . . . . .11
How you modify the translation. . . . . . . . . . . .12
What your end users do . . . . . . . . . . . . . . . . .12
Chapter 3 A General Comparison of Markup and FrameMaker Documents13
Structure descriptions. . . . . . . . . . . . . . . . . . . . . 13
FrameMaker EDDs . . . . . . . . . . . . . . . . . . . . 13
XML and SGML DTDs . . . . . . . . . . . . . . . . . . 13
Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
FrameMaker element types . . . . . . . . . . . . . . 15
XML and SGML elements. . . . . . . . . . . . . . . .15
Element declarations and definitions . . . . . . .16
Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Structure Application Developer’s Guide iv
Markup documents. . . . . . . . . . . . . . . . . . . . . 18
FrameMaker documents . . . . . . . . . . . . . . . . 19
Multiple-file documents. . . . . . . . . . . . . . . . . . . . 19
Format rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Graphics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Cross-references. . . . . . . . . . . . . . . . . . . . . . . . .21
Processing instructions . . . . . . . . . . . . . . . . . . . .22
Parameter entity declarations . . . . . . . . . . . . . . .22
Chapter 4 The SGML and FrameMaker Models - - - - - - - - - - - - - - - - - - - - - - - 23
SGML declaration . . . . . . . . . . . . . . . . . . . . . . . 23
SGML features with no counterparts . . . . . . . . . 23
Marked sections and conditional text . . . . . . . . .23
Unsupported optional SGML features. . . . . . . . .24
Chapter 5 The XML and FrameMaker Models- - - - - - - - - - - - - - - - - - - - - - - - - 25
Namespace declaration . . . . . . . . . . . . . . . . . . . 25
Rubi text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Element and attribute definition . . . . . . . . . . . . . 26
Supported characters in element and attribute
names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Multiple attribute lists for an element . . . . . . .27
Unicode and character encodings. . . . . . . . . . . .27
Supported encodings . . . . . . . . . . . . . . . . . . .27
FrameMaker display encodings . . . . . . . . . . .28
Encoding for XML files . . . . . . . . . . . . . . . . . .28
Chapter 6 Creating a Structure Application- - - - - - - - - - - - - - - - - - - - - - - - - - 29
The development process . . . . . . . . . . . . . . . . . 30
Task 1. Producing an initial EDD and DTD . . 30
Task 2. Getting sample documents . . . . . . . . 33
Task 3. Creating read/write rules. . . . . . . . . . 35
Task 4. Finishing your application . . . . . . . . . 38
For more information . . . . . . . . . . . . . . . . . . . 40
Pieces of a structure application. . . . . . . . . . . . . 41
Application definition file. . . . . . . . . . . . . . . . . 41
External DTD subset . . . . . . . . . . . . . . . . . . . 41
SGML declaration . . . . . . . . . . . . . . . . . . . . . 41
FrameMaker template. . . . . . . . . . . . . . . . . . .42
Read/write rules document. . . . . . . . . . . . . . .42
Entity catalogs. . . . . . . . . . . . . . . . . . . . . . . . .42
Documentation . . . . . . . . . . . . . . . . . . . . . . . .42
Creating a FrameMaker template . . . . . . . . . . . .43
Cross-reference formats. . . . . . . . . . . . . . . . .43
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Special text flows to format generated lists and
indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
HTML mapping for export. . . . . . . . . . . . . . . .46
Chapter 7 Working with Special Files - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 49
Location of structure files . . . . . . . . . . . . . . . . . . 49
Application definition file. . . . . . . . . . . . . . . . . . . 50
Editing an application definition file . . . . . . . . 51
Contents of structapps.fm . . . . . . . . . . . . . . . 51
Defining an application. . . . . . . . . . . . . . . . . . 53
Providing default information . . . . . . . . . . . . .54
Specifying a document element . . . . . . . . . . .55
Specifying a read/write rules document . . . . .55
Specifying a DTD . . . . . . . . . . . . . . . . . . . . . .56
Enabling namespaces. . . . . . . . . . . . . . . . . . .56

Structure Application Developer’s Guide v
Specifying filename extensions . . . . . . . . . . . 56
Specifying a FrameMaker template . . . . . . . . 57
Specifying an SGML declaration . . . . . . . . . . 57
Specifying entities . . . . . . . . . . . . . . . . . . . . . 57
Specifying entities through an entity catalog . 58
Specifying the location of individual entities. . 59
Specifying names for external entity files. . . . 60
Specifying public identifiers . . . . . . . . . . . . . . 61
Managing CSS generation. . . . . . . . . . . . . . . 62
Specifying a search path for external entity files
63
Specifying a search path for including files in
rules documents. . . . . . . . . . . . . . . . . . . . . . . 64
Specifying a structure API client. . . . . . . . . . .66
Specifying the character encoding for SGML files
66
Specifying the character encoding for XML files.
68
Limiting the length of a log file . . . . . . . . . . . .70
Log files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Generating log files. . . . . . . . . . . . . . . . . . . . .71
Messages in a log file. . . . . . . . . . . . . . . . . . .71
Using hypertext links. . . . . . . . . . . . . . . . . . . .72
Setting the length of a log file . . . . . . . . . . . . .72
Other special files . . . . . . . . . . . . . . . . . . . . . . . .72
Part II Working with an EDD
Chapter 8 Developing an Element Definition Document (EDD)- - - - - - - - - - 75
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Overview of the development process . . . . . . . . 76
Creating or updating an EDD from a DTD . . . . . 77
About the DTD . . . . . . . . . . . . . . . . . . . . . . . . 77
Read/write rules and the new EDD . . . . . . . . 77
Creating an EDD from a DTD . . . . . . . . . . . . 78
What happens during translation . . . . . . . . . . 78
Updating an EDD from a DTD . . . . . . . . . . . . 79
Log files for a translated DTD . . . . . . . . . . . . 79
Starting an EDD without using a DTD . . . . . . . . 80
Creating a new EDD . . . . . . . . . . . . . . . . . . . 80
Exporting an Element Catalog to a new EDD 80
The Element Catalog in an EDD . . . . . . . . . . . . 81
High-level elements . . . . . . . . . . . . . . . . . . . . 81
All elements in the catalog. . . . . . . . . . . . . . . 82
Defining preliminary settings in an EDD. . . . . . . 88
Specifying whether to create formats
automatically . . . . . . . . . . . . . . . . . . . . . . . . . 89
Specifying whether to transfer HTML mapping
tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Setting a structure application . . . . . . . . . . . .89
Organizing and commenting an EDD . . . . . . . . .90
Writing element definitions . . . . . . . . . . . . . . . . .91
About element tags. . . . . . . . . . . . . . . . . . . . .92
Guidelines for writing element definitions. . . .92
Defining a container, table or footnote element .
93
Defining a Rubi group element. . . . . . . . . . . .97
Defining an object element. . . . . . . . . . . . . . .99
Keyboard shortcuts for working in an EDD. . . .102
Editing structure . . . . . . . . . . . . . . . . . . . . . .102
Moving around the structure. . . . . . . . . . . . .103
Creating an Element Catalog in a template . . .103
Importing element definitions . . . . . . . . . . . .104
Log files for imported element definitions. . .104
Debugging element definitions . . . . . . . . . . .104
Saving an EDD as a DTD for export. . . . . . . . .105

Structure Application Developer’s Guide vi
Read/write rules and the new DTD . . . . . . . 105
Creating a DTD from an EDD . . . . . . . . . . . 106
What happens during translation . . . . . . . . . 106
SGML declarations . . . . . . . . . . . . . . . . . . . .107
Log files for a translated EDD. . . . . . . . . . . .107
Sample documents and EDDs . . . . . . . . . . . . .107
Chapter 9 Structure Rules for Containers, Tables, and Footnotes - - - - - 109
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 109
Overview of EDD structure rules . . . . . . . . . . . 110
Writing an EDD general rule. . . . . . . . . . . . . . . 111
Syntax of a general rule for EDD elements . 112
Restrictions on general rules for tables . . . . 114
Default general rules for EDD elements. . . . 115
Specifying validity at the highest level in a flow 116
Adding inclusions and exclusions. . . . . . . . . . . 116
Inclusions. . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Exclusions . . . . . . . . . . . . . . . . . . . . . . . . . . 118
How content rules translate to markup data . . .118
Inserting descendants automatically in containers .
119
Inserting table parts automatically in tables . . .120
Initial structure pattern . . . . . . . . . . . . . . . . .121
Default initial structure . . . . . . . . . . . . . . . . .122
Inserting Rubi elements automatically in Rubi
groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Initial structure pattern . . . . . . . . . . . . . . . . .123
Debugging structure rules. . . . . . . . . . . . . . . . .123
Chapter 10 Text Format Rules for Containers, Tables, and Footnotes - - 125
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 125
Overview of text format rules . . . . . . . . . . . . . . 126
How elements inherit formatting information . . 127
The general case . . . . . . . . . . . . . . . . . . . . . 128
Inheritance in a table or footnote . . . . . . . . . 130
Inheritance in a document within a book . . . 131
Specifying an element paragraph format . . . . . 132
Writing context-dependent format rules . . . . . . 132
All-contexts rules . . . . . . . . . . . . . . . . . . . . . 133
Context-specific rules. . . . . . . . . . . . . . . . . . 134
Level rules . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Nested format rules . . . . . . . . . . . . . . . . . . . 140
Multiple format rules. . . . . . . . . . . . . . . . . . . 141
Context labels . . . . . . . . . . . . . . . . . . . . . . . 142
Defining the formatting changes in a rule. . . . . 143
Paragraph formatting . . . . . . . . . . . . . . . . . . 143
Text range formatting. . . . . . . . . . . . . . . . . . 144
No additional formatting . . . . . . . . . . . . . . . . 145
Specifications for individual format properties. .146
Basic properties . . . . . . . . . . . . . . . . . . . . . .147
Font properties . . . . . . . . . . . . . . . . . . . . . . .150
Pagination properties . . . . . . . . . . . . . . . . . .152
Numbering properties . . . . . . . . . . . . . . . . . .153
Advanced properties. . . . . . . . . . . . . . . . . . .154
Table Cell properties. . . . . . . . . . . . . . . . . . .155
Asian Text Spacing properties . . . . . . . . . . .155
Writing first and last format rules. . . . . . . . . . . .156
How first and last rules are applied. . . . . . . .157
A first or last rule with an autonumber . . . . .157
Defining prefixes and suffixes . . . . . . . . . . . . . .158
How prefix and suffix format rules are applied . .
158
A prefix or suffix for a text range. . . . . . . . . .159
A prefix or suffix for a paragraph. . . . . . . . . .159
A prefix or suffix for a sequence of paragraphs .
160
A prefix or suffix for a text range or a paragraph
161

Structure Application Developer’s Guide vii
Attributes in a prefix or suffix rule. . . . . . . . . 162
When to use an autonumber, prefix or suffix, or first
or last rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Defining a format change list . . . . . . . . . . . . . . 163
Setting minimum and maximum limits on properties
165
Debugging text format rules . . . . . . . . . . . . . . .166
Chapter 11 Attribute Definitions - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 169
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 169
Some uses for attributes. . . . . . . . . . . . . . . . . . 169
How an end user works with attributes. . . . . . . 170
Writing attribute definitions for an element. . . . 171
Attribute name . . . . . . . . . . . . . . . . . . . . . . . 172
Attribute type . . . . . . . . . . . . . . . . . . . . . . . . 172
Specification for a required or optional value173
Hidden and Read-only attributes . . . . . . . . . 174
List of values for Choice attributes . . . . . . . .175
Range of values for numeric attributes. . . . .175
Default value. . . . . . . . . . . . . . . . . . . . . . . . .176
Using UniqueID and IDReference attributes. . .176
UniqueID attributes. . . . . . . . . . . . . . . . . . . .178
IDReference attributes . . . . . . . . . . . . . . . . .179
Using attributes to format elements . . . . . . . . .180
Using attributes to provide a prefix or suffix . . .182
Chapter 12 Object Format Rules - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 185
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 185
Overview of object format rules . . . . . . . . . . . . 186
Context specifications for object format rules. . 187
All-contexts rules . . . . . . . . . . . . . . . . . . . . . 187
Context-specific rules. . . . . . . . . . . . . . . . . . 188
Setting a table format . . . . . . . . . . . . . . . . . . . . 190
Specifying a graphic content type. . . . . . . . . . .191
Setting a marker type . . . . . . . . . . . . . . . . . . . .192
Setting a cross-reference format. . . . . . . . . . . .194
Setting an equation size . . . . . . . . . . . . . . . . . .194
Specifying a system variable. . . . . . . . . . . . . . .195
Debugging object format rules . . . . . . . . . . . . .197
Part III Translating between markup data and FrameMaker
Chapter 13 Introduction to Translating between Markup Data and
FrameMaker - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 201
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 201
What you can do with read/write rules . . . . . . . 201
What you can do with structure API clients . . . 202
A detailed example. . . . . . . . . . . . . . . . . . . . . . 203
DTD fragment. . . . . . . . . . . . . . . . . . . . . . . . 203
Document instance. . . . . . . . . . . . . . . . . . . .204
EDD fragment. . . . . . . . . . . . . . . . . . . . . . . .205
Formatting and read/write rules . . . . . . . . . .206
FrameMaker document. . . . . . . . . . . . . . . . .206
Opening XML documents . . . . . . . . . . . . . . . . .207

Structure Application Developer’s Guide viii
Chapter 14 Read/Write Rules and Their
Syntax- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 209
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 209
The rules document . . . . . . . . . . . . . . . . . . . . . 209
Rule order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Rule syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Case conventions. . . . . . . . . . . . . . . . . . . . . . . 212
Strings and constants. . . . . . . . . . . . . . . . . . . . 212
String syntax. . . . . . . . . . . . . . . . . . . . . . . . .212
Constant syntax . . . . . . . . . . . . . . . . . . . . . .213
Variables in strings . . . . . . . . . . . . . . . . . . . .213
Comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Include files . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Reserved element names . . . . . . . . . . . . . . . . .214
Commands for working with a rules document.215
Chapter 15 Saving EDD Formatting Information as a CSS Stylesheet- - - 217
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 217
Default translation. . . . . . . . . . . . . . . . . . . . . . . 217
Comparison of EDD format rules and CSS . 218
Differences in translation . . . . . . . . . . . . . . . 222
Generating a CSS. . . . . . . . . . . . . . . . . . . . . . .224
Generating a CSS on command. . . . . . . . . .224
Generating a CSS on Save As XML. . . . . . .225
Chapter 16 Translating Elements and Their Attributes - - - - - - - - - - - - - - - 227
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 227
Default translation. . . . . . . . . . . . . . . . . . . . . . . 228
Translating model groups and general rules 228
Translating attributes . . . . . . . . . . . . . . . . . . 229
Naming elements and attributes . . . . . . . . . 231
Inclusions and exclusions . . . . . . . . . . . . . . 233
Line breaks and record ends . . . . . . . . . . . . 233
Modifications to the default translation. . . . . . . 234
Renaming elements. . . . . . . . . . . . . . . . . . . 234
Renaming attributes. . . . . . . . . . . . . . . . . . . 235
Renaming attribute values . . . . . . . . . . . . . . 235
Translating a markup element to a footnote
element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Translating a markup element to a Rubi group
element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Changing the declared content of a markup
element associated with a text-only element 238
Retaining content but not structure of an element
238
Retaining structure but not content of an element
239
Formatting an element as a boxed set of
paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . .240
Suppressing the display of an element’s content
240
Discarding a markup or FrameMaker element . .
240
Discarding a markup or FrameMaker attribute . .
241
Specifying a default value for an attribute. . .242
Changing an attribute’s type or declared value. .
243
Creating read-only attributes . . . . . . . . . . . .244
Using markup attributes to specify FrameMaker
formatting information. . . . . . . . . . . . . . . . . .244

Structure Application Developer’s Guide ix
Chapter 17 Translating Entities and Processing Instructions - - - - - - - - - 247
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 247
Default translation. . . . . . . . . . . . . . . . . . . . . . . 248
On export to markup . . . . . . . . . . . . . . . . . . 248
On import to FrameMaker . . . . . . . . . . . . . . 251
Modifications to the default translation. . . . . . . 257
Specifying the location of entity declarations258
Renaming entities that become variables . . 258
Translating entity references on import and
export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Translating entities as FrameMaker variables .
259
Translating SDATA entities as special
characters in FrameMaker . . . . . . . . . . . . . . 260
Translating SDATA entities as FrameMaker text
insets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Translating SDATA entities as FrameMaker
reference elements. . . . . . . . . . . . . . . . . . . .263
Translating external text entities as text insets. .
264
Translating internal text entities as text insets . .
265
Changing the structure and formatting of a text
inset on import . . . . . . . . . . . . . . . . . . . . . . .266
Discarding external data entity references . .267
Translating ISO public entities . . . . . . . . . . .267
Facilitating entry of special characters that
translate as entities. . . . . . . . . . . . . . . . . . . .268
Creating book components from general entities
268
Discarding unknown processing instructions268
Using entities for storing graphics or equations .
269
Chapter 18 Translating Tables - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 271
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 271
Default translation. . . . . . . . . . . . . . . . . . . . . . . 272
On import to FrameMaker . . . . . . . . . . . . . . 272
On export to markup . . . . . . . . . . . . . . . . . . 275
Modifications to the default translation. . . . . . . 275
Formatting properties for tables . . . . . . . . . . 276
Identifying and renaming table parts . . . . . . 279
Representing FrameMaker table properties as
attributes in markup . . . . . . . . . . . . . . . . . . . 280
Representing FrameMaker table properties
implicitly in markup. . . . . . . . . . . . . . . . . . . . 281
Adding format rules that use CALS attributes
(CALS only) . . . . . . . . . . . . . . . . . . . . . . . . . 282
Working with colspecs and spanspecs (CALS
only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Specifying which part of a table a row or cell
occurs in . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
Specifying which column a table cell occurs in. .
284
Omitting explicit representation of table parts. . .
285
Creating parts of a table even when those parts
have no content . . . . . . . . . . . . . . . . . . . . . .287
Specifying the ruling style for a table . . . . . .289
Exporting table widths proportionally . . . . . .290
Creating vertical straddles . . . . . . . . . . . . . .290
Using a table to format an element as a boxed
set of paragraphs . . . . . . . . . . . . . . . . . . . . .293
Creating tables inside other tables . . . . . . . .295
Rotating tables on the page . . . . . . . . . . . . .295
Chapter 19 Translating Graphics and Equations - - - - - - - - - - - - - - - - - - - - 297
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 297 Default translation. . . . . . . . . . . . . . . . . . . . . . .298
Supported graphic file formats . . . . . . . . . . .298

Structure Application Developer’s Guide x
General import and export of graphic elements.
299
On export to markup . . . . . . . . . . . . . . . . . . 300
On import to FrameMaker . . . . . . . . . . . . . . 307
Modifications to the default translation. . . . . . . 308
Identifying and renaming graphic and equation
elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Exporting graphic and equation elements . . 309
Representing the internal structure of equations
311
Renaming markup attributes that correspond to
graphic properties . . . . . . . . . . . . . . . . . . . . 311
Omitting representation of graphic properties in
markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Omitting optional elements and attributes from
the default DTD declarations . . . . . . . . . . . .313
Specifying the data content notation on export. .
313
Changing the name of the graphic file on export
314
Changing the file format of the graphic file on
export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
Specifying the entity name on export . . . . . .318
ChanginghowFrameMakerwritesoutthesizeof
a graphic. . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Chapter 20 Translating Cross-References - - - - - - - - - - - - - - - - - - - - - - - - - - 321
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 321
Default translation. . . . . . . . . . . . . . . . . . . . . . . 321
On export to markup . . . . . . . . . . . . . . . . . . 322
On import to FrameMaker . . . . . . . . . . . . . . 323
Modifications to the default translation. . . . . . . 324
Translating markup elements as FrameMaker
cross-reference elements. . . . . . . . . . . . . . . 324
Renaming the markup attributes used with
cross-references. . . . . . . . . . . . . . . . . . . . . .325
Translating FrameMaker cross-reference
elements to text in markup . . . . . . . . . . . . . .326
Maintaining attribute values with FrameMaker . .
326
Translating external cross-references to and
from XML . . . . . . . . . . . . . . . . . . . . . . . . . . .326
Chapter 21 Translating Variables and System Variable Elements - - - - - - 329
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 329
Default translation. . . . . . . . . . . . . . . . . . . . . . . 329
On export to markup . . . . . . . . . . . . . . . . . . 330
On import to FrameMaker . . . . . . . . . . . . . . 331
Modifications to the default translation. . . . . . . 331
Renaming or changing the type of entities when
translating to variables. . . . . . . . . . . . . . . . . 332
Translating markup elements as system variable
elements . . . . . . . . . . . . . . . . . . . . . . . . . . . .333
Translating FrameMaker system variable
elements to text in markup . . . . . . . . . . . . . .333
Translating FrameMaker variables as SDATA
entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
Discarding FrameMaker variables . . . . . . . .334
Chapter 22 Translating Markers- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 335
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 335
Default translation. . . . . . . . . . . . . . . . . . . . . . . 335
On export to markup . . . . . . . . . . . . . . . . . . 336
On import to FrameMaker . . . . . . . . . . . . . . 336
Modifications to the default translation . . . . . . .337
Translating markup elements as FrameMaker
marker elements. . . . . . . . . . . . . . . . . . . . . .337
Writingmarkertext aselementcontentinsteadof
as an attribute. . . . . . . . . . . . . . . . . . . . . . . .337

Structure Application Developer’s Guide xi
Using markup attributes and FrameMaker
properties to identify markers. . . . . . . . . . . . 338 Discarding non-element FrameMaker markers . 339
Chapter 23 Translating Conditional Text - - - - - - - - - - - - - - - - - - - - - - - - - - - 341
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 341
Default translation. . . . . . . . . . . . . . . . . . . . . . . 341
Condition settings. . . . . . . . . . . . . . . . . . . . . 342
Conditional text . . . . . . . . . . . . . . . . . . . . . . 342
On export to markup. . . . . . . . . . . . . . . . . . .343
On import to FrameMaker. . . . . . . . . . . . . . .344
Modifications to the default translation . . . . . . .344
Chapter 24 Processing Multiple Files
as Books - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 347
In this chapter. . . . . . . . . . . . . . . . . . . . . . . . . . 347
Default translation. . . . . . . . . . . . . . . . . . . . . . . 348
On import to FrameMaker . . . . . . . . . . . . . . 348
On export to markup . . . . . . . . . . . . . . . . . . 350
Modifications to the default translation . . . . . . .351
Using elements to identify book components on
import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Suppressing the creation of processing
instructions for a book on export. . . . . . . . . .353
Chapter 25 Read/Write Rules Summary - - - - - - - - - - - - - - - - - - - - - - - - - - - - 355
All Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Cross-references . . . . . . . . . . . . . . . . . . . . . . . 356
Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Markers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359
Processing instructions. . . . . . . . . . . . . . . . . . .360
Markup documents . . . . . . . . . . . . . . . . . . . . . .361
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .362
Text insets. . . . . . . . . . . . . . . . . . . . . . . . . . . . .362
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .362
Chapter 26 Read/Write Rules Reference- - - - - - - - - - - - - - - - - - - - - - - - - - - - 365
anchored frame . . . . . . . . . . . . . . . . . . . . . . . . 365
attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
character map. . . . . . . . . . . . . . . . . . . . . . . . . . 369
convert referenced graphics. . . . . . . . . . . . . . . 372
do not include dtd. . . . . . . . . . . . . . . . . . . . . . . 373
do not include sgml declaration . . . . . . . . . . . . 373
do not output book processing instructions . . . 373
drop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
drop content . . . . . . . . . . . . . . . . . . . . . . . . . . .375
element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
end vertical straddle . . . . . . . . . . . . . . . . . . . . .379
entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
entity name is . . . . . . . . . . . . . . . . . . . . . . . . . .383
equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385

Structure Application Developer’s Guide xii
export dpi is . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
export to file . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
external data entity reference. . . . . . . . . . . . . . 391
external dtd. . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
facet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
fm attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
fm element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
fm marker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
fm property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
fm variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
fm version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
generate book. . . . . . . . . . . . . . . . . . . . . . . . . . 403
implied value is. . . . . . . . . . . . . . . . . . . . . . . . . 406
include dtd . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
include sgml declaration. . . . . . . . . . . . . . . . . . 409
insert table part element. . . . . . . . . . . . . . . . . . 410
is fm attribute . . . . . . . . . . . . . . . . . . . . . . . . . . 414
is fm char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
is fm cross-reference element . . . . . . . . . . . . . 418
is fm element . . . . . . . . . . . . . . . . . . . . . . . . . . 419
is fm equation element . . . . . . . . . . . . . . . . . . . 420
is fm footnote element . . . . . . . . . . . . . . . . . . . 421
is fm graphic element . . . . . . . . . . . . . . . . . . . . 422
is fm marker element . . . . . . . . . . . . . . . . . . . . 423
is fm property . . . . . . . . . . . . . . . . . . . . . . . . . . 424
is fm property value . . . . . . . . . . . . . . . . . . . . . 426
is fm reference element . . . . . . . . . . . . . . . . . . 430
is fm rubi element. . . . . . . . . . . . . . . . . . . . . . . 432
is fm rubi group element. . . . . . . . . . . . . . . . . . 432
is fm system variable element . . . . . . . . . . . . . 433
is fm table element . . . . . . . . . . . . . . . . . . . . . . 435
is fm table part element. . . . . . . . . . . . . . . . . . .436
is fm text inset . . . . . . . . . . . . . . . . . . . . . . . . . .437
is fm value. . . . . . . . . . . . . . . . . . . . . . . . . . . . .439
is fm variable. . . . . . . . . . . . . . . . . . . . . . . . . . .441
is processing instruction . . . . . . . . . . . . . . . . . .441
line break. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443
marker text is. . . . . . . . . . . . . . . . . . . . . . . . . . .444
notation is . . . . . . . . . . . . . . . . . . . . . . . . . . . . .445
output book processing instructions . . . . . . . . .447
preserve fm element definition . . . . . . . . . . . . .448
preserve line breaks . . . . . . . . . . . . . . . . . . . . .449
processing instruction . . . . . . . . . . . . . . . . . . . .451
proportional width resolution is . . . . . . . . . . . . .452
put element . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
reformat as plain text. . . . . . . . . . . . . . . . . . . . .454
reformat using target document catalogs . . . . .455
retain source document formatting . . . . . . . . . .456
specify size in . . . . . . . . . . . . . . . . . . . . . . . . . .456
start new row. . . . . . . . . . . . . . . . . . . . . . . . . . .458
start vertical straddle. . . . . . . . . . . . . . . . . . . . .460
table ruling style is. . . . . . . . . . . . . . . . . . . . . . .461
unwrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .461
use processing instructions. . . . . . . . . . . . . . . .463
use proportional widths . . . . . . . . . . . . . . . . . . .463
value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .464
value is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .465
write structured document. . . . . . . . . . . . . . . . .466
write structured document instance only. . . . . .466
writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .467

Structure Application Developer’s Guide xiii
Appendix A Conversion Tables for Adding Structure to Documents . . . . 471
How a conversion table works . . . . . . . . . . . . . 471
Setting up a conversion table. . . . . . . . . . . . . . 472
Generating an initial conversion table . . . . . 473
Setting up a conversion table from scratch . 474
Updating a conversion table. . . . . . . . . . . . . 474
Adding or modifying rules in a conversion table474
About tags in a conversion table . . . . . . . . . 475
Identifying a document object to wrap . . . . . 476
Identifying an element to wrap . . . . . . . . . . . 477
Identifying a sequence to wrap . . . . . . . . . . 478
Providing an attribute for an element . . . . . .479
Using a qualifier with an element . . . . . . . . .480
Handling special cases . . . . . . . . . . . . . . . . . . .481
Promoting an anchored object . . . . . . . . . . .481
Flagging format overrides. . . . . . . . . . . . . . .482
Wrapping untagged formatted text . . . . . . . .483
Nesting object elements . . . . . . . . . . . . . . . .483
Building table structure from paragraph format
tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .484
Testing and correcting a conversion table . . . .484
Appendix B The CALS Table Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
FrameMaker properties that DO NOT have
corresponding CALS attributes. . . . . . . . . . . . . 487
Element and attribute definition list declarations . .
488
Element structure . . . . . . . . . . . . . . . . . . . . . . . 490
Attribute structure . . . . . . . . . . . . . . . . . . . . . . .491
Inheriting attribute values . . . . . . . . . . . . . . .491
Orient attribute . . . . . . . . . . . . . . . . . . . . . . .491
Straddling attributes . . . . . . . . . . . . . . . . . . .491
Appendix C Read/Write Rules for CALS Table Model . . . . . . . . . . . . . . . . . . 493
Appendix D SGML Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Text of the default SGML declaration. . . . . . . . 497
SGML concrete syntax variants . . . . . . . . . . . . 499
Unsupported optional SGML features. . . . . . . .500
Appendix E Character Set Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Appendix F ISO Public Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
What you need to use ISO public entities. . . . . 510
Entity declaration files . . . . . . . . . . . . . . . . . 511 Entity read/write rules files . . . . . . . . . . . . . .511
What happens with the declarations and rules .514
Appendix G SGML Batch Utilities for UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Importing SGML documents in batch mode. . . 517 Exporting documents as SGML in batch mode.519
Appendix H Developing XML or SGML Publishing Applications . . . . . . . . 521
Implementing an XML or SGML application in the
FrameMaker publishing environment. . . . . . . . 521 Overview of FrameMaker Application Development. . . . . . . . . . . . . . . . . . . . . . . . .521

Structure Application Developer’s Guide xiv
Technical Steps in FrameMaker Application
Development . . . . . . . . . . . . . . . . . . . . . . . . 529 Typical Application Development Scenarios.538
Conclusions . . . . . . . . . . . . . . . . . . . . . . . . .542
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Index- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 555

Structure Application Developer’s Guide xv
Before You Begin
This manual is for anybody who develops structured FrameMaker templates and XML or
SGML applications. It is not 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) or SGML (Standard
Generalized Markup Language) documents. XML and SGML are two types of 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.
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 the software reads markup data, FrameMaker displays the data as a formatted,
structured document. When the software writes a structured FrameMaker document, the
software can save 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 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:

Before You Begin xvi
•A structured template
•Read/Write rules (described in this manual)
•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
declaration
•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:
•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. 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.
Using this manual
This manual is divided into three major parts and a series of appendixes. If you’re creating
a structure application, you’ll find information you need in all three parts. If, however, you’re
not working with markup data but are creating a structured template, you’ll need only Part II.
The parts are as follows:
•Part I, “Developing a FrameMaker structure application”
Part I is for developers of XML or SGML structure applications. This section contains
- introductory information
- An overview of the steps in creating a structure application

Structure Application Developer’s Guide xvii
- A comparison of FrameMaker concepts and XML and SGML
- Details of assembling the pieces of an application into a whole
•Part II, “Working with an EDD”
Part II is for developers of a FrameMaker structured template. It contains information on
how you use an element definition document (EDD) to define elements and determine
their formatting for your documents. You use this part in conjunction with chapters in the
FrameMaker user’s manual that describe other aspects of template creation.
•Part III, “Translating between markup data and FrameMaker”
Part III is for developers of structure applications. FrameMaker’s default translation
between markup documents and FrameMaker documents follows a model. This part
describes the model and the rules you use to modify the default translation.
•Part III, “Translating between markup data and FrameMaker”
Part IV is for developers of XML applications. FrameMaker’s default translation between
XML documents and FrameMaker documents follows a model. This part describes the
model and the rules you use to modify the default translation.
•Appendixes
The appendixes include information such as how to add structure to unstructured
FrameMaker documents and how to work with ISO public entities. There is also a
glossary of terms.
If you’re creating an XML or SGML application, we encourage you to read the first three
chapters of Part I before reading any of the rest of the manual. For your purposes, these
chapters are a prerequisite to the rest of the manual.
Each of the parts of this manual begins a short introduction in which you can find
information about specific chapters in that part.
Using other FrameMaker documentation
The FrameMaker User Guide 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.
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

Before You Begin xviii
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.

Structure Application Developer’s Guide 1
Part I Developing a
FrameMaker structure
application
Part I provides basic information for developing SGML applications, manual including:
•Chapter 2, “Structure Application Basics”
Describes situations that require a structure application. Also contains a high-level
description of application creation.
•Chapter 3, “A General Comparison of Markup and FrameMaker Documents”
Compares relevant SGML and FrameMaker concepts. You should read this chapter even
if you are already familiar with both SGML and FrameMaker, since translation between
the two is its own distinct topic. The chapter deals with counterpart constructs in the two
representations, and also with constructs in one that have no real counterpart in the
other.
•Chapter 6, “Creating a Structure Application”
Describes typical application creation workflow. Also discusses the types of files used in
your final SGML application.
•Chapter 7, “Working with Special Files”
Tells where to find special files used by FrameMaker with XML and SGML documents.
Also explains creation of the file that defines the pieces of your structure application.

Developing a FrameMaker structure application 2