Macromedia FrameMaker - 7.1 User Guide
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 Corporation 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.
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 iii
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 att rib ut e
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
Structure Application Developer’s Guide iv
Providing default information . . . . . . . . . . . . .54
Specifying a document element . . . . . . . . . . .55
Specifying a read/write rules document . . . . .55
Specifying a DTD . . . . . . . . . . . . . . . . . . . . . .56
Enabling namespaces. . . . . . . . . . . . . . . . . . .56
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 v
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 cont ain ers .
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 vi
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
Structure Application Developer’s Guide vii
Document instance. . . . . . . . . . . . . . . . . . . .204
EDD fragment. . . . . . . . . . . . . . . . . . . . . . . .205
Formatting and read/write rules . . . . . . . . . .206
FrameMaker document. . . . . . . . . . . . . . . . .206
Opening XML documents . . . . . . . . . . . . . . . . .207
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 eleme n t 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 el em e nt . .
240
Discarding a markup or FrameMaker attr ibu te . .
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 viii
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 tabl e pr op er tie s as
attributes in markup . . . . . . . . . . . . . . . . . . . 280
Representing FrameMaker tabl e pr op er tie s
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 ix
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 expor t
314
Changing the file format of the graphic file on
export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
Specifying the entity name on export . . . . . .318
Changing how FrameMaker writes out the size of
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
Writing marker text as element content instead of
as an attribute. . . . . . . . . . . . . . . . . . . . . . . .337
Structure Application Developer’s Guide x
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
Markers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359
Processing instructions. . . . . . . . . . . . . . . . . . .360
Markup documents . . . . . . . . . . . . . . . . . . . . . .361
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .362
Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
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
Structure Application Developer’s Guide xi
drop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
drop content . . . . . . . . . . . . . . . . . . . . . . . . . . .375
element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
end vertical straddle . . . . . . . . . . . . . . . . . . . . .379
entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
entity name is . . . . . . . . . . . . . . . . . . . . . . . . . .383
equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
export dpi is . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
is fm table part element. . . . . . . . . . . . . . . . . . .436
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 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
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
Structure Application Developer’s Guide xii
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
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 mo d e . . . 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
Structure Application Developer’s Guide xiii
Overview of FrameMaker Application
Development. . . . . . . . . . . . . . . . . . . . . . . . .521
Technical Steps in FrameMaker Application
Development . . . . . . . . . . . . . . . . . . . . . . . . 529
Typical Application Development Scenarios.538
Conclusions . . . . . . . . . . . . . . . . . . . . . . . . .542
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Index - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 555
Structure Application Developer’s Guide xiv
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 elem ents. 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 mark up data, FrameMaker displays th e data as a formatted,
structured document. When the software writes a structured FrameMaker document, the
software can save the docume nt 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 doc ument 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:
Structure Application Developer’s Guide xv
• A structured template
• Read/Write rules (described in this manual)
• An XML and SGML API client (if n ecessary) developed with the Frame Develop er’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 a nd 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
Before You Begin xvi
- 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 understa nding FDK basics. This manual
describes how to use the FDK to enhance the functionality of FrameMaker and describes
Structure Application Developer’s Guide xvii
how to use the FDK to work with structured documents. To make advanced modifications
to the software’s default transla tion behavior, refer to the Structur e 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 xviii
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 creatio n.
• Chapter 3, “A General Comparison of Markup and FrameMaker Documents”
Compares relevant SGML and FrameMaker concepts. Yo u should read this chap ter 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 t he types of files use d 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.
Structure Application Developer’s Guide 1
Developing a FrameMaker structure application 2
1
What’s New in FrameMaker 1
This chapter describes new additions to FrameMaker that pertain to the development and
use of structured applications.
What’s new in FrameMaker 7.1
FrameMaker 7.1 introduces several changes in import and export of XML documents.
Important: None of these changes affect import or export of SGML documents.
The following sections briefly describe the new FrameMaker 7.1 functionality and provide
links to more complete descriptions.
Conditional text
FrameMaker 7.0 exported shown conditional text with no indication in the resulting XML that
the content was conditional. It never exported hidden conditional text. FrameMaker 7.1
allows export of both shown and hidden conditional text. Furthermore, it optionally exports
processing instructions that define condition settings and identify conditional material. It
interprets these processing instructions when importing an XML document and thus
supports round-tripping of conditional text. See Chapter 23, “Translating Conditional Text.”
External cross-references
FrameMaker 7.0 used XML elemen ts to export internal cross-refere n c es (th os e in w hic h th e
cross-reference source is in the same FrameMaker document as the cross-reference itself).
When it exported a book, it a lso generated XML elements for cross- references from one
book component to another component of the same book. It converted all other external
cross-references to text.
FrameMaker 7.1 exports all cross-references as XML elements. It uses a new srcfile
attribute to identify the source file of external cross-references. You can choose whether the
FrameMaker or XML form of the source file should be named. On import, FrameMaker
reads the srcfile attribute to create external cross-references. See Chapter 20,
“Translating Cross-References.”
Preserving the XML extension
When FrameMaker 7.0 opened an XML document, it created a new FrameMaker document
without preserving the fact that the document originated as XML. It changed the file
extension to .fm and used this modified filename to label the resulting document window.
Structure Application Developer’s Guide 3
1
What’s new in FrameMaker 7.0
FrameMaker 7.1 preserves the original file name. If you save an imported XML document,
the document is saved as XML rather than as a FrameMaker document. Furthermore,
FrameMaker locks an open XML document so that no other user can change it, with
FrameMaker or with another application, until it is closed. See “Opening XML documents”
on page 207 for more details.
Priority of variable definitions
FrameMaker imports some XML entity references as user variables. If the user variable is
not defined in the import tem plate, Fram eMaker defines it, using the entity definition (text in
quotation marks) in the XML entit y declaration as the FrameMaker variable definition.
FrameMaker 7.0 and FrameMaker 7.1 differ in their treatment of entity references when t he
corresponding variable is pred efined in the template. FrameMake r 7.0 gave priority to the
definition in the template. If the definition in the template differ ed from that in the XML
document, it used the definition in the template. FrameMaker 7.1 gives priority to the
definition in the XML entity declaration. FrameMaker 7.1 therefore supports round-tripping
of such entity declarations. See “Internal text entities” on page 251
What’s new in FrameMaker 7.0
FrameMaker 7.0 introduces full support for the import and export of XML markup. As a
result, many things have changed. Most notably, FrameMaker now supports the import of
XML with UNICODE text. You can edit the impor ted documents, and when you save th em
as XML again FrameMaker retains the font encoding.
.
The following sections briefly describe the changes in FrameMaker, and provide links to the
parts of this manual that describe these changes in detail.
Path and filename changes
Earlier versions of FrameMaker included many path and filenames that included the letters
“SGML” to identify them as spec ific to FrameMaker+SGML. With version 7.0 structured
FrameMaker documents can be saved as SGML or XML—many of these path and
filenames have changed. Also, the structure of the FrameMaker installation is slightly
changed to separate files specific to SGML and XML into separate branches. Among these
changes:
• What used to be the sgml branch of the installation is now found underneath the
structure directory—there you can find $installdir/structure/sgml and
$installdir/structure/xml which contain separate branches for files that pertain to
SGML and XML
• The file sgmlapps.fm is renamed to structapps.fm—you can find this file in
$installdir/structure/structlapps.fm
What’s New in FrameMaker 4
1
What’s new in FrameMaker 7.0
Application development
Because of the differences between SGML and XML, you must specify which structure
applications are for SGML and which are for XML. For XM L structure applications you can
specify how an application manages:
• CSS files
• Namespaces
• Character encoding and Unicod e support in XML
For more information, see Chapter 7, “Working with Special Files.”
Read/write rules
Because XML is case-sensitive, any references to XML keywords in your read/write rules
must match the case of thes e keywords. Generally, these key words are in uppercase
letters.
The names of the following read/write rules have changed:
From: To:
fmsgml version fm version
write sgml document write structured document
write sgml document instance only write structured document instanc e only
Namespaces
FrameMaker 7.0 supports XML namespace declarations. For more information, see
“Namespace declaration” on page 25
CSS support
FrameMaker does not use CSS data when importing XML, but it does retain the CSS
specification in an XML document on export. You can also generate a CSS from the
formatting information that is stored in an EDD. See Chapter 15, “Saving EDD Formatting
Information as a CSS Stylesheet.”
Exporting variables to markup
FrameMaker exports non-element variables as entities. Depending on the variable, some of
these entities can be SDATA or CDATA. XML doesn’t support SDATA or CDATA entities—
you have two options for handling such non-element variables:
• By default, FrameMaker writes the variables out as text
• You can use read/write rules to map the variables to empty elements
For variables that are elements, FrameMak er exports them as empty elements in markup.
Structure Application Developer’s Guide 5
1
What’s new in FrameMaker 7.0
For more information, see Chapter 21, “Translating Variables and System Variable
Elements.”
New starter kits
FrameMaker 7.0 includes a new starter kit for XHTML, and an updated kit for DocBook 4.1
(SGML) and 4.1.2 (XML). For more information, see the starter kit manuals in the online
manuals directory.
What’s New in FrameMaker 6
2
Structure Application Basics 2
This chapter provides an introduction to structure application development using
FrameMaker. The chapter examines some of the reasons you might be using markup data
and FrameMaker together and explains how those reasons affect the structure application
you develop. The chapter also provides high-level information about cr eating that
application.
Where to begin
If your end users do not need markup, but use structured documents only because they
want the benefits inherent in a structured authoring environment, you only need to provide
them an element definition document (EDD) and a structured template. In this case, the
material you need is contained in Part II, “Working with an EDD.”
If your end users need to read or write markup documents, you will probably need to
develop a structure application to mo dify the default translation between mark up data and
FrameMaker documents. In that c ase, this entire manual is of use to you. The rest of Part
I provides general information on creating a structure application. Part III, “Translating
between markup data and FrameM aker ,” provides details of the default translation between
markup data and FrameMaker and explains how you can change this default behavior with
structure read/write rules.
Structure application scenarios
The specific features of your structure application will largely depend on how your
organization intends to use it.
Translating in one or two directions?
You can write structure applications that translate documents in one direction—from XML
or SGML to FrameMaker or from FrameMaker to XML or SGML. Or your application can
translate in both directions, enabling in formation to make round tr ips between markup data
and FrameMaker.
If your end users only translate the data in one direction, you can limit your structure
application to only manage the translation in that direction. One-direction translations are:
• Reading markup data in to FrameMaker—the structure applic ation only needs to import
specific doctypes into FrameMaker
• Writing FrameMaker documents as markup data—the structure application only needs to
export FrameMaker documents as XML or SGML of a specific doctype
Structure Application Developer’s Guide 7
2
Structure application scenarios
For example, your company may have a large SGML document database of parts
information from which it periodically needs to produce catalogs. You may want to deliver
the information in FrameMaker to take advantage of its formatting capabilities while you
continue to create and store the information only in SGML. In this case, end users
manipulate the catalog document in FrameMaker, but not the source SGML database.
Because of this, you set up an application to translate from SGML to FrameMaker but don’t
worry about the reverse.
Or assume your company needs to publish documents in print, PDF, and XML. The authors
can create the documentation in FrameMaker, paying attention to pagination and other
formatting issues as they go. When they have a final version of the documents they can
save them as PDF and XML, and the online documentation will be made from the same
source as the printed documentation.
Or perhaps your end users work with FrameMaker to create their documents, but they
collaborate with other writers who use a different authoring environment for XML
documents. In this situation your application needs both to read XML documents into
FrameMaker and to write FrameMaker to XML, so that your end users can collaborate
effectively.
Can you simplify when translating in only one direction?
If your application only needs to translate in one direction, then you might be able to simplify
some of the information you present. For instance, if your end users have existing
FrameMaker documents to deliver in markup, they developed documents using the full
power of FrameMaker. They may well have used such FrameMaker features as markers to
facilitate document creation. But some of these features may not be relevant in markup
data, so you can choose to omit them from the markup document. If you won’t be reimporting the markup data back into FrameMaker, the resultant loss of information is not
important. Therefore, you don’t have to retain the use of those features in your structure
application.
Do you have an existing DTD or EDD?
Another factor influencing the design of your application is the degree to which the
document structure has already been defined for the markup data and the FrameMaker
template. Is your starting point an established EDD or DTD—for instance, one of the
Department of Defense CALS DTDs? Will you be provided with both an established EDD
and an existing body of documents that use that EDD? Or has neither definition document
as yet been written?
It is common to start application development with a DTD. In that case, your structure
application must also address the issues of translating the DTD to an EDD. It is also
possible that you begin with an existing EDD, and must translate the EDD into a DTD.
For example, assume your end users already have a library of documents based on a
particular DTD. In that case, you’ll be less inclined to make changes to the DTD that require
Structure Application Basics 8
2
Structure application development
modifying those documents. If you start without a model on either side, however, you have
the freedom to design the EDD and the DTD with its counterpart in mind. If you have this
freedom, the application desig n process may be easier.
Structure application development
Markup data and structure in FrameMaker have many similarities. To describe the
hierarchical nature of docume nts, b oth use sp ecial methods to define the elements that can
occur in a document instance, and the relationships among those elements. In markup,
these elements are defined in a DTD, and in FrameMaker they are defined in an EDD.
Within particular document instances, both use descriptive tags to identify each instance of
a structural element. The tags in the document content correlate to the element definitions
found in the DTD or the EDD, as shown in the following illustration. The top of the illustration
shows pages of SGML and Fram eMaker documents, while the bottom sh ows a DTD and
EDD, respectively. The highlighted portion of the SGML document corresponds to the
highlighted definition for <list> in the corresponding DTD. The FrameMaker page and
EDD illustrate a similar correspondence.
Structure Application Developer’s Guide 9
2
Structure application development
An SGML document instance
and its DTD
<chapter><head>Summary of
Transportation 2000 Plan Elements
</head>
<section><head>Highway System</head>
<para>
A base network of roads for people and
goods movement, designed to operate at
maximum efficiency during off-peak and
near capacity in peak hours. Elements
include freeways, expressways and major
arterials. Current projects include:
</para>
<list type = “bullet”><item>Completion
of Measure “A” program of Routes 101,
85, and 237</item>
<item>Emphasis on Commuter Lanes and
bottleneck improvements including new
and upgraded interchanges</item>
<item>Capacity improvements in 101 and
Fremont/South Bay Corridors</item>
<item>Operational improvements
including signal synchronization and
freeway surveillance</item>
</list></section></chapter>
<!ELEMENT chapter - - (head, section+) >
<!ELEMENT head - - (#PCDATA) >
<!ELEMENT section - -
(head, (para | list)*) >
<!ELEMENT para - - (#PCDATA) >
<!ELEMENT list - - (item+) >
<!ATTLIST list
type (bullet | number) bullet >
<!ELEMENT item - - (#PCDATA) >
A FrameMaker document and its
EDD
Summary of Transportation 2000
Plan Elements
Highway System
A base network of roads for people and
goods movement, designed to operate at
maximum efficiency during off-peak and
near capacity in peak hours. Elements
include freeways, expressways and
major arterials. Current projects include:
• Completion of Measure "A" program
for Routes 101, 85, and 237
• Emphasis on Commuter Lanes and
bottleneck improvements including
new and upgraded interchanges
• Capacity improvements in 101 and
Fremont/South Bay Corridors
• Operational improvements including
signal synchronization and freeway
surveillance
Element (Container): Para
General rule: <TEXT>
. . .
Element (Container): List
General rule: Item+
Attribute list:
1. Name: Type Choice Optional
Choices: Bullet, Numbe r
Default: Bullet
Element (Container): Item
General rule: <TEXT>
Text format rules
1. In all contexts.
Basic properties
Indents
First indent: 0.0”
Move left indent by: 0.16667”
Despite the similarities in their basic approach to the creation of structured documents, XML
and SGML differ from FrameMaker in their methods of representing document content, and
in the aspects of documents they represent. In this respect, markup and FrameMaker are
like ordinary human languages that evolve from different cultures—they differ not only in the
particular words they use, but in their rules for putting words togeth er, and even in the
thoughts that can be easily expressed with them. For documents to move between
FrameMaker and markup data, the software needs instructions to help it translate between
the two languages.
Structure Application Basics 10
2
Structure application development
The starting point: an EDD or DTD
Your end users need a starting point that describe s the structur e of documents they’ll create
or edit. You provide this starting point either with a DTD or a FrameMa ker EDD.
If you start with a DTD, FrameMaker can create portions of a corresponding EDD for you.
Similarly, if you start with an EDD, FrameMaker can create a DTD for you. If a starting point
has not yet been established, you can create your own DTD or EDD. In this situation, we
recommend you to start by using FrameMaker’s tools for creating an EDD (describ ed in Part
II of this manual) and then create a DTD from that EDD.
Translation between DTDs and EDDs
FrameMaker can automatically translate a DTD or EDD. If you start with a DTD, the
software creates a default version of the corresponding EDD. Similarly, if you start with an
EDD, FrameMaker creates a default version of the DTD.
Once your application is complete, your end users use standard commands to save
individual FrameMaker documents as markup documents or to open individual markup
documents in FrameMaker. In either case, the structure application works transparently with
FrameMaker, making these automatic translations possible.
Formatting information in FrameMaker
You create a structured template to provide appropriate formatting for your document s.
Properly speaking, a DTD does not provide any formatting information. With XML,
formatting information is provided via CSS or XSL. When reading XML, FrameMaker does
not use any of this formatting information.
When reading markup data, FrameMaker combines any formatting that is defined in the
document template with any formatting rules that are specified in the EDD. To vary the
formatting of your documents, you may create more than one structured template for the
same DTD. For example, your end users can use the same markup data for different
purposes, such as a fully designed cata log and a brief parts list. They may wa nt the same
data formatted differently in these two situations.
Changing the default translation
The structure of markup data varies widely, and that can affect the way it maps to
FrameMaker document objects. As a result, much of your job in creati ng a structure
application is to change the default translation FrameMaker uses. You do so by providing
information the software needs to recognize and process particular constructs. If
FrameMaker automatically translates all the components of a document just as you want,
you don’t need to provide this extra information.
One of the differences betw een markup data and FrameM aker is that has explicit
representations for items such as tables or graphics. With XML or SGML, an individual DTD
defines a arbitrary representations for tables and graphics. For this reason, the defa ult
translation in FrameMaker ass ume certain DTD representations of th ese items. For
Structure Application Developer’s Guide 11
2
Structure application development
example, by default FrameMaker assumes a CALS model for tables. These assumptions
may or may not match your actual DTD. If they don’t match, you need to develop an
application that modifies the default translation accordingly.
How you modify the translation
To modify how FrameMaker translates documents, you start by using special read/write
rules. In many cases these rules are sufficient to successfully translate a given doctype. A
significant part of your effort in creating a structure application consists of specifying these
rules.
You specify read/write rules in a special rules document. Most rules are relevant to all
import or export functions, but a small number apply only to some. For example, there is a
rule to rename an element on import and export. There is also a rule to tell the software
how to treat FrameMaker non-element markers on export, but this rule doesn’t apply to
import or to creation of a DTD.
In some situations the representation you want in yo ur DTD and your EDD may be radically
different from what FrameMaker does by default. If so, rules might not be adequate to
correctly translate your docu ments. For example, the FrameMaker model for tables
assumes that a table is described in row-major order. But if your DTD describes tables in
column-major order, then the FrameMaker read/write rules won’t be able to translate
between the markup data and FrameMaker representations. In other situations, your XML
or SGML document may contain processing instructions that need to be interpreted but are
unknown to FrameMaker. In such situations, you can customize FrameMaker via the FDK.
The FDK allows you to modify FrameMaker’s import and export of individual markup and
FrameMaker documents. You cannot use it to modify the creation of an EDD or a DTD.
What your end users do
Once you’ve created a structur e application, your end users use th at application to open
markup documents in FrameMaker and to save FrameMaker documents as markup data.
For this purpose, they’ll work in a FrameMaker environment that includes your structure
application. Depending on your application, the fact that files are stored as markup or as
FrameMaker documents can be invisible to your end users. For example, the standard
Open command opens either an XML or a FrameMaker document.
Structure Application Basics 12
Loading...