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.

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

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 .

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

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

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

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

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

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

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

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

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

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

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

A General Comparison of Markup and FrameMaker Documents 3

Markup data and FrameMaker documents use models for structured documents that are sometimes similar and sometimes substantially different. This chapter describes the similarities and differences that you should understand before you can create a structure application.

Structure descriptions

In markup data, elements are defined in element declarations and attribute definition list declarations within a document type definition (DTD). In Fr ameMaker ele ments are de fined

in element definitions within an element definition document (EDD) and attributes are defined as part of an element.

FrameMaker EDDs

In FrameMaker, the EDD in which you create element definitions is a separate document. After creating the file of element definitions, you import the definitions into a template. A template is a FrameMaker document that stores information about a set of documents. This information includes element definitions and many other details such as paragraph formats, table formats, page layouts, and variable definitions.

The process of importing the EDD into a template stores the element definitions in the template’s Element Catalog. After the EDD designer has imported the EDD, it is no longer needed as a separate document. Typically, the EDD designer retains the separate EDD document for maintenance. End users such as writers or editors, however, don’t need direct access to the EDD. Instead, they work exclusively with the template file.

For information on creating EDDs, see Part II, “Wo rking with an EDD.”

XML and SGML DTDs

For markup data, the process of providing declarations for a document is somewhat different. The DTD designer can create the declarations in a separate file. However, there is no step of transforming a DTD for use by a particular document. The form of the DTD remains constant.

In addition, a DTD is only concerned with the syntax of a document—that is, with legal ways to put together the pieces of a document, regardless of the intended purpose of the pieces. Markup has nothing to say about the semantics of the process, that is, the meaning of those pieces.

Structure Application Developer’s Guide 13

Elements

Before its document instance, a markup document always includes either all the declarations or a reference to them. Rather than requiring that all of the declarations in a DTD be included in each markup document, the XML and SGML standards allow for the declarations to be stored separately and referenced from the document. The document type declaration in such a document includes the set of declarations stored separately by referring to them as an external entity.

A typical document type declaration has the form:

<!DOCTYPE name extid [ internal_declarations ] >

For XML, a document type declaration can have the form:

<!DOCTYPE name extid URL [ internal_declarations ] >

In these examples, name is the document type name and extid is the external identifier of an entity that consists of a list of declarations. For XML, URL refers to the location of the external declarations on the in ternet.

Important: When reading and writing XML data, FrameMaker ignores the URL statement in the document type declaration. In FrameMaker, the structure application can include a specific DTD, or it can use a map to resolve the public identifier for the DTD on your s ystem.

Elements

The declarations in the external entity are treated as though they appeared at the end of

internal_declarations. The declarations that actually appear in internal_declarations are read before the ones in the external entity. Together, the

declarations in the external entity and in internal_declarations are the document type declaration subset of the DTD.

There is an informal practice in the SGML community of using the ter m external DTD subset to refer to this external entity and using the term internal DTD subset to refer to the declarations shown here as internal_declarations.

In most places in this manual that use the term DTD, it can refer to either a complete DTD or to an external DTD subset. In the few places where the distinction matters, the manual clarifies which one is meant.

In both markup data and in FrameMaker, the basic building blocks of documents are elements. Elements hold pieces of a document’s content (its text, graphics, and so on) and together make up the document’s structure. FrameMaker distinguishes among several specific element types, corres ponding to special FrameMaker document objects such as tables or cross-references. Mark up does not make such a distinction.

A General Comparison of Markup and FrameMaker Documents 14

Elements

FrameMaker element types

A large proportion of the elements in a structured FrameMaker document are defined to include text, child elements, or both. FrameMaker has several additional element types that represent constructs in a document for which the software has special authoring tools. These element types are for

• footnotes

• cross-references

• markers

• system variables

• equations

• graphics

• tables

• table parts (such as table footings)

If the element does not correspond to one of these constructs for which FrameMaker has special tools, the element is tagged as a container in the EDD.

FrameMaker provides flexibility in handling markers and system variables. As noted above, you can define elements that correspond to them. Alternatively, you can allow users to create non-element markers or system variables directly in an element that can contain text. In this case, you do not create a corresponding element. You choose the appropriate representation depending on your end-user’s needs. For example, if your EDD includes a definition for a marker element, then when an end user inserts an element of this type in a document, FrameMaker uses the marker element’s format rules to insert a marker of the correct type. When an end user inserts a non-element marker, on the other hand, the user must explicitly specify the marker type.

For more information on element types, see Chapter 8, “Developing an Element Def inition Document (EDD).” For information on translating between FrameMaker and markup elements of various types, see Part III, “Translating between markup data and FrameMaker.”

XML and SGML elements

Markup data provides even more flexibility than does FrameMaker. Markup doesn’t dictate the purpose of elements of any type. A construct that is represented in FrameMaker by a marker or system variable element can be represented by an element with a declared content of empty in markup. It can also be represented by a completely different element structure.

Structure Application Developer’s Guide 15

Attributes

Element declarations and definitions

Each element definition or declaration in both markup data and in FrameMaker contains the element’s name and information about appropriate content for that elemen t. FrameMaker element definitions also contain appropriate formatting for the content. In markup data, an element’s name is its generic identifier; in FrameMaker, the name is its element tag. The information about content is in the declared content or in the content model of a markup element declaration and in the general rule of a FrameMaker element definition. Formatting information is specified via the format rules of a FrameMaker element definition.

Element content

The content model or declared content of a markup element and the element tag and general rule of a FrameMaker element specify in precise terms what an element can contain. In FrameMaker, the part of the content rule that specifies the basic element content is the general rule.

A FrameMaker element’s general rule can be the single specifier <EMPTY> to indicate no content, or a combination of text and child elements. Some of the special element types, such as cross-references, do not have a separate content rule, since an element of that type always has the same content (a single cross-reference in this case). A markup element’s content model can in clude either the reserved name ANY (“anything”) or a combination of child elements. In some element definitions in both markup and FrameMaker, the content rule also specifies what content is required or optional and the required order of the content.

Inclusions and exclusions

Definitions and declarations can specify elements with constraints other than their general rule. An element that is an inclusion in another elem ent can occur anywhere within that element, without the general rule explicitly listing the included element. An element that is an exclusion to another element cannot occur anywhere within that element, even if the content rule implies that the excluded element is allowed.

For example, you can define a n element representing a chapter as a heading followed by a combination of paragraphs and lists, each of which has its own structure. If you want to allow footnotes anywhere in a chapter, you could specify the element representing a footnote element as an inclusion in a chapter element. You then would not need to explicitly mention a footnote element in the definitions of paragraphs or lists, but would be able to include footnotes in those elements.

Attributes

FrameMaker and markup both provide attributes to supply additional information about an element. For example, the DTD designer for a manual could use an attribute called version for its book element to allow the user to specify a book’s revision status.

XML: The XML specification doesn’t allow inclusions or exclusions.

A General Comparison of Markup and FrameMaker Documents 16

Entities

In FrameMaker, the attributes for an element are a part of the definition of the element itself. In XML or SGML, the attributes for an element occur separately in an attribute definition list declaration (ATTLIST) in the DTD.

By default, FrameMaker translates most attributes in markup data as attributes of the same name in the FrameMaker document. However, you may decide to supply rules to change this behavior. Some attributes in markup data represent information best represented by other means in FrameMaker. For example, you can write a rule to specify that an attribute corresponds to a particular property, such as the number of columns in a table, instead of to a FrameMaker attribute.

Entities

For information on defining attrib utes in an EDD, see Chapter 11, “Attribute Definitions,” this manual. For information on translating between FrameMaker and markup attribu tes, see Chapter 16, “Translating Elements and Their Attributes.”

In markup, an entity is a collection of characters you reference as a unit. Entities are used for many purposes. You can use an entity as

• shorthand for a frequently used phrase

• a placeholder for an external file containing a graphic in some special format

• a way to include multiple physical files in the same document.

FrameMaker provides several features for handling situations for which you use entities in markup data.

Entities can be classified in various ways. For example, they can be grouped into general or parameter entities or into internal or external entities. General entities usually occur inside a document instance. Parameter entities usually occur inside a DTD. Internal entities have replacement text specified directly in an entity declaration. External entities are stored in a separate storage object (such as a data file) often identified in the entity declaration by a system identifier, public identifier, or both.

While FrameMaker doesn’t have a single construct called an entity, it uses various mechanisms to provide the functionality of many XML and SGML entities. Entity-like features include the following :

Text substitution You can represent frequently repeated sequences of characters as general entities in markup, and as variables or text insets in FrameMaker.

File management You can break large documents across multiple files and manage those files with a single document containing general entity references in markup, and with a book file in FrameMaker.

Graphics In markup data you often store graphics in separate files, then include them in the document with general entity name attributes. In FrameMaker, you can store graphics and equations externally or internally.

Structure Application Developer’s Guide 17

Documents

Special characters SGML doesn’t allow you to enter certain characters or sequences of characters directly as data characters in an SGML document. This can happen, for example, if the character is not in the character set of the SGML document. In FrameMaker these might be either variables or characters in a particular font.

XML: The XML specification allows the use of UNICODE text, which makes this use of entities largely unnecess ary. The specification also identifies pr edefined character entities which FrameMak er can translate by default.

Markup In SGML, entities may contain actual markup. Because FrameMaker is a WYSIWYG tool, it has no concept of markup as such.

For information on creating va riables, text insets, and books, see the FrameMaker User Guide.

For information on translating entities to various FrameMaker constructs, see Chapter 17, “Translating Entities and Processing Instructions,” Chapter 19, “Translating Graphics and Equations,”Chapter 21, “Translating Variables and System Variable Elements.” and Chapter 24, “Processing Multiple Files as Books.”

Documents

The XML and SGML specifications use the term document differently than it is used in FrameMaker. A markup document has a particular set of parts in a particular order and can be spread across multiple physical files. A FrameMaker document is simply a single file in FrameMaker format.

Markup documents

According to the XML and SGML standards, an XML or SGML docum ent contains an SGML declaration (SGML-only), a prolog, and a document instance set. (For more information

about the SGML declaration, see Chapter 4, “The SGML and FrameMaker Models.” The prolog and document instance set allowed with FrameMaker have the simplest form

defined in the standard. For a document used with FrameMaker, its prolog can contain comments, processing instructio ns, and exactly one DTD. Its document instance set includes exactly one document instance. A document instance is a particular collection of data and markup such as a memo or book—what most users informally think of as a document.

When you open the file or files comprising an XML or SGML document, you can clearly see the parts of the document corresponding to the SGML declaration, DTD, and document instance. Frequently, the bulk of the DTD actually resides in a separate file as an external DTD subset and is referenced in the document.

A General Comparison of Markup and FrameMaker Documents 18

)

Multiple-file documents

FrameMaker documents

Since FrameMaker is a WYSIWYG tool, a FrameMaker document is organized differently than a markup document. A FrameMaker document contains information specified in the template from which it was created, along with the data of the document. The template information is stored in various catalogs, such as the Element Catalog and the Paragraph Catalog, and in special nonprinting master and reference pages. Rather than having explicit markup that appears in the document, it uses commands for a dding stru cture a nd fo rmatting that take effect immediately.

Multiple-file documents

Frequently, your end user wants to divide the text for a document into multiple physical files. For example, a book may have a separate file for each chapter. Both markup documents and FrameMaker allow a single conceptual document to be divided into multiple physical files.

FrameMaker provides the book mechanism for this purpose. A book file contains a list of files that together form a complete work. Each file in the book is a complete FrameMaker document and can stand on its own.

In markup, you can use text entities for the same purpose—you can have a single file with references to text entities, each of which contains a portion of the document. In markup, each text entity isn’t a complete document. That is, each entity doesn’t have its own DTD, and document instance. Inste ad, the text entities are part of th e document instance of a single markup document.

For information on creating FrameMaker books, see the F rameMak er and Fr ameMa ker user guides. For information on creating books from text entities, see Chapter 24, “Processing Multiple Files as Books.”

Format rules

Markup has no standard mechanism for representing the formatting of a document, although some DTDs use attributes for some formatting information. XML uses CSS and XSL to represent formatting.

FrameMaker provides format rules that allow an EDD to store context-sensitive formatting information. When you read an XML document into FrameMaker, the formatting specified in the CSS or XSL file has no effect. In stead, FrameMaker us es the formatting spec ified in the EDD.

FrameMaker also uses the EDD format rules when you edit a document. As you insert an element with format rules, Fra meMaker applies the appropriate f ormat to the element’s content on the basis of surrounding structure and attribute values. That is, FrameMaker can format the same element in different ways, in different contexts in a document. In addition, an end user can override formats for any portion of a document.

Structure Application Developer’s Guide 19

Graphics

FrameMaker format rules can be defined hierarchically. For example, you can say that the font family and size for Section elements are Times 12pt and for MyTab table elements they are Helvetica 12pt. Later, you can say that the Fnote footnote element is 9pt. Since you did not specify the font family for Fnote, it is Times if it occurs in a Section element, but Helvetica if it occurs in a MyTab element.

For information on creating format rules in an EDD, see Chapter 10, “Text Format Rules for Containers, Tables, and Foot notes,” and Chapter 12, “Object Format Rules.”

There is no standard mechanism for representing graphics in markup data. There are several common methods in use, in each of which an entity holds the graphic object itself.

In markup, the entity can be in an external file, written in a particular format such as Sun raster format. The graphic data format is given a name called a data content notation. The entity declaration specifies its notation.

In XML, the graphic and its file format can be represented in a an unparsed entity. Then the XML document can use t his entity as an attribute in a graphic element to include the graphic in the document.

FrameMaker provides tools for creating a graphic. Alternatively, your users can import an external graphic, either by copying it directly into your FrameMaker document or by referring to an external graphic. In the latter case, the graphic remains in an external file and the name of the file is associated with the document. FrameMaker recognizes a graphic in several file formats, such as MIF or Sun raster format. Because FrameMaker determines the format directly by reading t he graphic, you don’t need to tell it the format of a graphic explicitly. Hence, there is no need to attach names to the formats.

For information on translating graphics, see Chapter 19, “Translating Graphics and Equations.”

Equations

As with graphics, markup has no standard mechanism for representing equations, while FrameMaker has a complete tool for working with them. Once created, however, equations in FrameMaker have characteristics very similar to graphics. For this reason, FrameMake r treats equations in essentially the same w ay as gr aphics fo r mark up impo rt and export , and this manual discusses them toge ther.

For information on creating graphics and equations in FrameMaker, see the FrameMaker User Guide.

For information on translating equations, see Chapter 19, “Translating Graphics and Equations.”

A General Comparison of Markup and FrameMaker Documents 20

Tables

FrameMaker has a complex facility for creating and manipulating tables within a FrameMaker document, including several special element types for use in your EDD. Tables have parts such as a title, body, rows, and cells.

Markup data doesn’t have a standard mechanism for representing tables. As a re sult, their representation is unique to each DTD. In practice, many DTDs use the CALS table model, which is similar to the table description supported by FrameMaker. Other DTDs can have element structure that is not auto matically recog nizable as a ta ble, but that needs to forma t as a table.

When you create an EDD from a DTD, FrameMaker automatically recognizes the CALS table model and creates elements of the appropriate type. If you have a different table model in your DTD, you’ll need to supply rules to identify the table structure.

For information on working with tables in FrameMaker, see the FrameMaker User Guide. For information on defining tables and table parts in an EDD, see Chapter 9, “Structure Rules for Containers, Tables, and Footnotes.” For information on translating tables, see Chapter 18, “Translating Tables.”

Cross-references

A cross-reference is a passage in on e place in a document that refers to anot her place (a source) in the same document or a different document. While the XML an d SGML sta ndards

do not explicitly support cross-references, they do provide the declared values ID, IDREF, and IDREFS for attributes, and attributes using t he se de cla re d v alu es customarily represent cross-references. FrameMak er can use this model for cross-refe rences within a FrameMaker document.

FrameMaker provides several additions to the cross-reference model suggested by XML and SGML. You need to keep these possibilities in mind when you work with crossreferences:

• For markup data, both the cross-reference and its source are elements. In FrameMaker

the source of the cross-reference can be an element but can also be a paragraph or a spot in a paragraph.

• For markup data, attributes contain the information connecting a cross-referenc e to its

source. In FrameMaker you can also store the information in markers instead.

• The ID/IDREF mechanism is natural in markup data for internal cross-references, those

in which the source and the cro ss-reference are in the same docume nt. However, it cannot be used with external cross-references, those in which the source and the crossreference are in different documents. FrameMaker provides a single mechanism for both internal and external cross-references.

Structure Application Developer’s Guide 21

Processing instructions

• FrameMaker represents external cross-references in XML with a variation of the ID/

IDREF model. Instead of an IDREF attribute, it uses a srcfile attribute whose value identifies the file containing the source element as well as the value of its ID attribute.

• FrameMaker and markup have different views of what constitutes an internal or external

cross-reference. In FrameMaker, a cross-refe renc e to a differ ent file is always an external cross-reference. In markup, cross-references to different entities in a single document are always internal cross-references. So cross-references between components in a FrameMaker book are considered external, but cross-references between the text entities that correspond to those components are internal, since the entire book translates to a single XML or SGML document.

• XML and SGML allow a single attribute value to link several sources. FrameMaker

requires a separate cross-reference for each citation.

For information on creating cross-references in FrameMaker documents, see the FrameMaker User Guide. For in formation on translating cross-refe rences to markup, see Chapter 20, “Translating Cross-Referen ces.”

Processing instructions

Markup data can include processing instructions to modify the treatment of a document in some system-specific manner. FrameMaker translates most processing instructions as markers in your FrameMaker document. It also defines a small number of special processing instructions for handling FrameMaker markers, books, and book components. You can use the FrameMaker Developer’s Kit (FDK) to handle other processing instructions when reading markup documents, but not when creating an EDD from a DTD.

For information on handling processing instructions, see Chapter17, “Translating Entities and Processing Instructions,” and Chapter 24, “Processing Multiple Files as Books.”

Parameter entity declarations

A DTD can use parameter e ntities as references to declaration content that is repeated in different statements. When FrameMaker reads a DTD with parameter entities, it expands them out to the full content of the reference. Any declarations that use a parameter entity will translate with the correct content, but the resulting EDD does not retain the parameter entity declaration nor the parameter entity itself.

When you create an EDD, you can use FrameMaker variables as references to repeated content. When FrameMakertranslates the EDD to a DTD, it does not convert these variables to corresponding parameter entities.

A General Comparison of Markup and FrameMaker Documents 22

The SGML and FrameMaker Models 4

Before building a structure application that is designed to work with SGML, you should understand the specific differences between SGML and the FrameMaker document model. For a discussion about markup in general, see Chapter 3, “A General Comparison of Markup and FrameMaker Documents.”

SGML declaration

According to the SGML standard, an SGML document contains an SGML declaration, a prolog, and a document instance set. The SGML declaration includes information on the

specific syntax in effect for the do cument. In the absence of an SGM L declaration, your SGML applications can use the reference concrete syntax defined in the SGML standard.

SGML features with no counterparts

SGML features with no FrameMaker counterparts include:

• Short reference mapping or usage

• Markup minimization

• Content references

FrameMaker correctly interprets a document with markup using any of the features mentioned in this list. However, it does not retain the information that the document’s markup used the feature. For example, your document might use markup minimization to omit certain start-tags. If it does, the parser interprets the document as though the omitted start-tags were present. The rest of FrameMaker’s processing can’t distinguish whether or not the start-tags were omitted.

FrameMaker also doesn’t use any of the abov e features when wr iting SGML documen ts. If you want an SGML document written by FrameMaker to use one of the features, you must write a Structure API client. For information on writing a Structure API client, see the online manual that comes with the FDK, the Structure Import/Export API Programmer’s Guide.

Marked sections and conditional text

Both SGML and FrameMaker have mechanisms for specifying portions of a document that can be included or left out as needed. In SGML, this mechanism is marked sections; in FrameMaker, it is conditional text. The details of these two mechanisms differ significantly. For this reason, when transla ting between FrameMak er and SGML, the software does not

Structure Application Developer’s Guide 23

Unsupported optional SGML features

attempt to preserve the fact that information was tagged as conditional text in a FrameMaker document or that it occurred in a marked section in an SGML document.

When reading an SGML document, if the SGML parser used by FrameMaker encounters a marked section declaration with the effective status IGNORE, it doesn’t include that section. If the effective status is INCLUDE, CDATA, or RCDATA, the software a ppropriately interprets and translates the marked section. The software doesn’t annotate marked sections in the resulting EDD or document. Since your modifications only affect documents after they have passed through the parser, you cannot modify this behavior.

Similarly, if FrameMaker encounters conditional text that is hidden when writing a FrameMaker document as SGML, it does not include that text in the SGML document. All other text, whether it is unconditional or conditional, is included in the SGML document. Conditional text is not annotated in any particular way in the resulting DTD or document. You can write a Structure API client to change the exported document instance to reflect condition tags.

For information on working with conditional text, see the FrameMaker User Guide.

Unsupported optional SGML features

The SGML standard defines some features as optional, meaning that a specific implementation does not have to accommodate these features to be considered a conforming SGML system.

The following optional SGML features are not supported by FrameMaker:

• DATATAG

• RANK

• LINK

• SUBDOC

• CONCUR

Your SGML documents cannot contain any of these features. If they do, FrameMaker signals an error and terminates processing. You cannot change this behavior with the FDK.

The SGML and FrameMaker Models 24

The XML and FrameMaker Models5

Before building a structure application that is designed to work with XML, you should understand the specific differences between XML and the FrameMaker document model. For a discussion about markup in general, see Chapter 3, “A General Comparison of Markup and FrameMaker Documents.”

Namespace declaration

FrameMaker supports the use of namespace declarations in XML. A namespace can be declared as an element attribute in the DTD, or it can be declared in a given element within the document instance.

FrameMaker does not require you to declare namespace attributes in the EDD. In FrameMaker you can enable or disable namespaces in the XML structured application.

To see namespace information, you can choose Element > Namespaces to display the NameSpaces dialog box. Or namespace information may appear in the structure view elements that declare namespaces. The display of namespace information in FrameMaker depends on whether namespaces are enabled, as well as how the namespaces are declared in the DTD.

For a structure application with namespaces enabled:

• When a namespace is declared in an element but not in the DTD, the namespace

information appears in the Namespaces dialog bo x. The stru ctur e view shows an asterisk for the element that has the namespace declaration.

• When a namespace is declared in an element and is also declared in the DTD, the

namespace information appears in the Namespaces dialog box. The structure view shows the namespace as a valid element attribute with no value. The structure view also shows an asterisk for the element.

• When a namespace is declared in the DTD, but is not declared in any element, the

structure view shows the namespace as a valid attribute with no value.

For a structure application with namespaces disabled:

• When a namespace is declared in an element but not in the DTD, the structur e view

shows the namespace as an invalid attribute, with the URI as the attribute value.

• When a namespace is declared in an element and is also declared in the DTD, the

structure view shows the namespace as a valid attribute, with the URI as the attribute value.

Structure Application Developer’s Guide 25

Rubi text

• When a namespace is declared in the DTD, but is not declared in any element, the

structure view shows the namespace as a valid attribute with no value.

When you export the FrameMaker document to XML, the namespace inform ation is written to the XML.

Japanese text uses a form of annotation known as Rubi to express the phonetic representation of a word over the characters used to spell the word. The XML specification suggests a representation for Rubi as follows:

<ruby>

<rb>Oyamoji text</rb> <rt>Rubi text</rt>

</ruby>

To import that representation you would need read/write rules similar to the following:

element "ruby" is fm rubi group element "MyRubiGroup"; element "rb" is fm rubi element "MyRubi"; element "rt" is fm rubi element "Oyamoji";

For more information, see “Defining a Rubi group element” on page 97

Element and attribute definition

The XML specification includes the f ollowing features concerning the declara tion of elements and attributes:

Supported characters in element and attribute names

In XML, various markup tokens (GIs, attribute names, etc.) can include characters from the upper range of UNICODE. While FrameMaker can read XML content that contains the full range of UNICODE, FrameMaker has limited support of the characters for markup tokens. This support is limited to char acters of the current display encoding. This d isplay encoding can be determined by the lo cale of the cu rrent operating system, or b y specifying a display encoding for the XML structure application. The characters you can use are:

Character set: For this language:

FrameRoman Western European languages JIS X 0208:1997 Japanese BIG5 Traditional Chinese GB2312-80 Simplified Chinese KSC5601-1992 Korean

For a given encoding, character support in markup tokens is further limited by the set of reserved characters. To see which characters are reserved for FrameRoman encoding,

The XML and FrameMaker Models 26

Unicode and character encodings

refer to the online manual, FrameMaker Character Sets and note the reserved characters in the standard character s et.

For more information, see “Specifying the character encoding for XML files” on page 68

Multiple attribute lists for an element

The XML specification allows you to define an element’s attributes in more than one attribute list. FrameMaker does not support this feature.

Unicode and character encodings

XML supports any character encoding that is compatible with UNICODE. FrameMaker offers equal support for any # PCDATA, CDATA and RCDATA content.

FrameMaker has limited support of characters in markup tokens such as GIs and attribute names—see “Supported characters in element and attribute names,” (the previous section) and “Specifying the character encoding for XML files” on page 68

Read/write rules do not support Asian characters, so you cannot use rules to manipulate elements or attributes whose names contain such text.

Supported encodings

FrameMaker ships with support for the following encodings, listed by their IANA names:

Big5 KSC_5601 EUC-CN macintosh EUC-JP Shift_JIS EUC-KR US-ASCII EUC-TW UTF-16 GB2312 UTF-8 ISO-8859-1 windows-1252

Using these IANA names, you can specify any of these encodings for export to XML—see “Specifying the character encoding for XML files” on page 68

These encodings are created in the ICU (International Components for Unicode) for mat, and stored as .cnv files. The supplied encodings are stored in the following locations:

• Windows: $installdir\fminit\icu_data

• Unix: $installdir/fminit/icu_data

• Macintosh: $installdir:Modules:Icu_Data

You can add other ICU encodings to the FrameMaker installation—you must create ICU compliant mappings and save them as .cnv files, then store them in the icu_data

Structure Application Developer’s Guide 27

Unicode and character encodings

directory. Once you install a new encoding, you can refer to it the same as you refer to the other export encodings.

FrameMaker associates a given ICU encoding to an internal display encoding that is appropriate for a given language. Because any number of languages can be used in an XML file, FrameMaker cannot make that association automatically. The XML document prolog specifies an encoding, but the document may contain elements or other constructs that override the language implied by that encoding.

As of this writing you can find more information about International Components for Unicode (ICU) at http://www-124.ibm.com/icu/.

FrameMaker display encodings

By default, FrameMaker uses the display encoding that matches the input locale of your operating system. However, you can specify a different encoding in your XML structure application. FrameMaker supports the following display encodings:

Display encoding: For this language:

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

On import, when FrameMaker encounters an unknown character in #PCDATA it imports the character as a marker of type UNKNOWNCHAR. The marker content is a text string representing the UTF16 encoding for that character. It imports unknown characters in CDATA as XML character references.

Encoding for XML files

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

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

The XML and FrameMaker Models 28

Creating a Structure Application 6

This chapter describes the major tasks you’ll perform to create a structure application and describes the pieces your application might contain. Much of your work in creating an application involves writing read/write rules to modify the software’s default behavior. Part III, “Translating between markup data and FrameMaker,” describes specific default behaviors and explains how you can change them.

The diagram shows your completed structure application at work. Information in the application funnels into the Open and Save As commands in FrameMaker, adapting their default translation behavior to your markup and FrameMaker environments. Your structure application has information (such as a DTD) specific to the markup representation of documents, other information (such as an EDD) specific to the FrameMaker representation of documents, and rules and definition to bridge this information. The application pieces are described in more detail in “Pieces of a structure application” on page 41

Struct application

Markup Environment

FM Environment

SGML Declaration

DTD

Entities

Markup Document

Read/Write

Rules

Application

Definition

FrameMaker

Open/Save As Commands

EDD

FrameMaker Tem-

plate

FrameMaker

Document

Structure Application Developer’s Guide 29

The development process

As a structure application developer, your primary task is to modify the default translation behavior of FrameMaker to fit the circumstances of your application. This section gives an overview of the steps used to create a struc ture application and to deliver that application to your end users.

At the highest level, there are four major application development tasks:

1. Get an initial version of both an EDD and a DTD. You typically start application development with eithe r an existing EDD or an existing

DTD. In some situations, however, you have neither of these things. Your first task is to provide yourself with either an EDD or a DTD as a starting point and then use th e software to create an initial version of a DTD if you started with an EDD or an EDD if you started with a DTD.

2. Get sample documents to test your application. If you don’t have sample markup documents and FrameMaker documents to test the

progress of your application, you will need to create them.

3. Create read/write rules to modify the translation between the EDD and DTD. Once you have an EDD, a DTD, and some sample documents, start an iterative process

of analysis and application modification. Write read/wr ite ru les to modify how t he so ftwar e translates between markup and FrameMaker.

4. Use the FDK and FrameMaker tools to finish your application. Once you’ve done as much as you can with rules, you may have to write a structure API

client to further modify the software’s behavior. Consider other modifications you want, such as customizing the FrameMaker end-user interface to remove inappropriate commands or add new ones. Finally, assemble all the pieces of your application for delivery to your end users.

The four following sections provide more detail on the major tasks. To simplify the discussion, they have no pointers to more information on the various steps. For these pointers, see “For more information” on page40

Task 1. Producing an initial EDD and DTD

This flowchart shows the steps you follow to produce an initial EDD and DTD for your application, and the notes below the chart give more detail on some of the steps. What you do once you have the development environment set up depends greatly on the situation at your company. Numbers in the flowchart refer to the notes below the chart.

Creating a Structure Application 30

The development process

Consider main design issues. (1)

Set up development environment. (2)

Yes

Create initial EDD from DTD. (3)

You have an initial EDD and an initial DTD for your application.

The following notes give more detail on some of the steps in the chart. Note numbers match the chart numbers.

Do you have a

DTD as your

starting point?

Yes

Do you have an

existing EDD as

your starting

point?

Create initial DTD from EDD. (5)

Create EDD from

scratch. (4)

(1) Consider the main design issues.

You need to think about:

• the kinds of documents you need to support

• what end users need in terms of access to both FrameMaker and markup versions of the

same document

• the environment (XML, SGML, or FrameMaker) in which documents will be created and

delivered

• whether end users work with only one structure application or multiple applications

(2) Set up the development environment.

You or your system administrator must insta ll FrameMaker.

Structure Application Developer’s Guide 31

The development process

Once FrameMaker is properly installed, you need to tell it where to find rules you’ll write and other information it may need. Collect this information in an application definition that you can associate with the EDD or the markup document element.

At this point, you can create a simple application file, giving the application a name and specifying the location of existing file s, such as an EDD, DTD, and (for SGML stru cture applications) the SGML declaration. Later in the development process, you’ll need to include other information in the definition.

(3) Create an initial EDD from your DTD, if you have one.

If you’re starting with a DTD, choose File>Developer Tools>Open DTD to create an initial EDD to see how the software translates your DTD with no help from your application. You use this initial EDD during your analysis to see how you want to translate markup constructs into FrameMaker constructs.

In the absence of read/write rules, FrameMaker translates:

• Markup elements to FrameMaker elements of the same name—For SGML the

FrameMaker element names are receive initial capitalization; for XML the FrameMaker elements receive the case found in XML

• Markup attributes to FrameMaker attributes, assuming that attributes contain extra

information about their associated elements

• entities to various constructs such as variables

The software produces a log file if it encounters any problems while processing your DTD.

(4) Create an EDD, if you’re starting from scratch.

If you’re in the situation of having neither a preexisting EDD nor a preexisting DTD, you need to create one or the other before you can create a structure application. Because of the richer semantics available in an EDD, you should first create an EDD and its associated FrameMaker template and then continue the development process from there.

If you’re starting from scratch and the sample documents you intend to use are unstructured FrameMaker documents, you may want to do this step in conjunction with the next major task.

(5) Create an initial DTD from your EDD.

If you have a preexisting EDD, choose File>Developer Tools>Save As DTD to create an initial DTD to see how the software translates your EDD with no help from your application.

The DTD has element and attribute definition list declarations corresponding to the element and attribute definitions in the EDD. The software reads through the E DD, processing the elements and their attributes o ne at a time. For each definition , the software

• creates a markup element of the appropriate type

• produces an attribute definition list declaration for any element that has defined attributes

Creating a Structure Application 32

The development process

• writes notation declarations for use with graphics and equations and produces comments

in the DTD corresponding to th ose in the EDD

An EDD includes more semantic information on the usage of its elements than does a DTD. For example, there are special element types corresponding to markers, system variables, and graphics, among other things. The declarations in the DTD created by FrameMaker reflect this information.

Task 2. Getting sample documents

This flowchart shows the steps you follow to get sample documents to test with your application, and the notes below the chart give more detail on some of the steps. Numbers in the flowchart refer to the notes below the chart.

Structure Application Developer’s Guide 33

The development process

Do you have sample

documents?

Create sample

documents from

scratch. (6)

Yes

Are your sample

documents in

markup?

Yes

Are your sample

documents structured

FrameMakerdocume

Yes

nts?

Yes

Create an EDD for your sample documents.

Are your sample

documents unstructured

FrameMaker

documents?

Use an import filter to create unstructured FrameMaker documents from your sample

documents. (7)

Create a conversion table to add structure to your

unstructured sample documents. (8)

Structure one or more sample documents.

You have sample documents to start testing your application.

The sample documents you need depend on your starting point. For example, if you already have markup documents, you probably won’t yet have FrameMaker documents. If you have existing unstructured FrameMaker documents, you may need to structure them. Later in the process, you may decide to create more sample documents.

(6) Create sample documents if you have none.

Add to the collection as you develop the application, in order to test particular parts of the application. If you’re starting with a preexisting DTD, create sample XML or SGML

Creating a Structure Application 34

The development process

documents. If you’re starting wit h a preexisting EDD, create structured FrameMaker documents.

(7) Use document import filters to get FrameMaker documents.

If your sample documents are in a file format other than XML, SGML, or FrameMaker, you should convert them to unstructured FrameMaker documents and then use the software’s tools for structuring unstruct ured documents.

(8) Structure unstructured FrameMaker documents if necessary.

If you’ve gotten to this point, you have unstructured FrameMaker documents to use as your sample documents. FrameMaker provides tools to aid you in structuring unstructured documents.

You create a conversion table that describes a set of unstructured documents and then use FrameMaker commands to s tructure your docum ents. Once the do cuments are structu red, you also need an EDD and structured template that corresponds to the elements described in the conversion table.

If you use FrameMaker’s conversion tools, you should use the resulting EDD as one of the starting points of your structure application.

Task 3. Creating read/write rules

Once you have both an EDD and a DTD, you can use read/write rules to refine how FrameMaker translates between them. This portion of application development is an iterative process. This flowchart shows the steps of this process. The notes below the chart give more detail on some of the steps, and numbers in the flowchart refer to the notes.

Structure Application Developer’s Guide 35

The development process

You have an initial EDD, DTD, and sample documents for your application.

Analyze DTD, EDD, and sample documents.

Identify needed rules and other information such as entity locations. (9)

Write read/write rules and modify application definition to change FrameMaker’s

default behavior. (10)

Use your modified application to create a new version of the EDD or DTD from the

current DTD or EDD. (11)

If you’re making a DTD from an EDD, correct

syntax errors uncovered by the parser. (12)

Test opening and saving sample documents as appropriate for your end users. (14)

Yes

Is there more you can do with rules?

(9) Analyze the details of what your application must do.

If you are not already familiar with it, you need to study the original DTD or EDD, with the partially completed new EDD or DTD and sample documents, to determine what constructs are defined and how they are intended to be used. Sample documents are invaluable in understanding the meaning of t he defined element s tructures; the partially co mpleted EDD or DTD lets you know how well Fr ameMaker performs the translation so far.

If you start with a DTD, the steps of your analysis should be similar to the following:

1. Examine element declarations or definitions. Determine the representation of elements and, from a high level, the element and

document groupings. Determine which elements are used for text or as containers for other elements and which are used for special constr ucts such as tables or graphics.

Determine the level of minimization provided by the DTD. Markup minimization is irrelevant in FrameMaker’s internal representation, but you may need to understand its usage in sample documents. During the early stages of development, you probably won’t try to reproduce minimization in markup, but you may later write a structure API client to do so.

If you’re making an EDD from a DTD, add any new

format rules to EDD and import EDD to template. (13)

Creating a Structure Application 36

The development process

Determine the purpose of elements with a declared content of EMPTY. These will translate to the appropriate FrameMaker constructs, such as graphic elements.

2. Examine attribute use. Examine attributes to distinguish attributes that control formatting from attributes that

simply provide information about the associated element. Formatting attributes for special constructs such as tables or graphics may become formatting properties in a FrameMaker document.

3. Examine entity declarations. Determine how entities are used and which become text, variables, graphics, book files,

or special characters in FrameMaker. The SGML standard defines several sets of character entities. Check whether your DTD refer s to any of these character sets.

4. Examine notation declarations. Determine how to represent non-SGML data (NDATA) in FrameMaker. NDATA can often

be represented directly as FrameMaker graphic or equation elements.

5. Examine elements and attributes used as cross-references. FrameMaker assumes markup attributes with declared value of ID or IDREF refer to

cross-references. Your DTD may also use other declared values, such as IDREFS, NAME, and NAMES, for cross-references.

(10) Write rules and modify the application definition.

While working on your rules, you may need to modify your application definition. For example, you need to tell the software how to locate entities that have public identifiers.

Some parts of the task of changing the translation between the two representations will require more work than others. For example, standard elements such as those representing text in paragraphs or lists may translate with no help from you. But other elements, such as those representing graphics, will require your assistance.

The steps described here suggest working on a portion of the representation only as far as possible with rules and waiting until you’re finished with rules before a ttempting to write a structure API client. An alternate approach is to work on a particular representation until it is complete, before moving o n to the next representation, even if that means creating a structure API client.

(11) Create a new version of the EDD or the DTD.

After you have written the rules your application requires, use the appropriate command to update your EDD or to recreate your DTD. Where they are applicable, FrameMaker uses your rules to modify its processing. Wh ere it encounters no applicable rule, the software uses its default behavior.

(12) Correct syntax errors uncovered by the parser.

FrameMaker uses parsers to interpret XML and SGML markup in ways that comply with the associated standards. Whe n FrameMaker processes a DTD or a markup document on

Structure Application Developer’s Guide 37

The development process

import, the parser interprets ma rkup and ident ifies the informa tion in the docume nt such as element declarations and element start-tags.

The parser may find problems that cause the DTD to be syntactically invalid. Some problems can be corrected with read/write rules, while others may require you to modify the DTD.

SGML: The SGML standard allows wide variations in the actual markup of specific documents. For example, it allows variations in the maximum length of the sequence of characters specifying a name, in the case-sensitivity of names, and in markup that may be omitted altogether. This is specified in the SGML declaration. If the parser encounters errors in the DTD, you may be able to fix them by changing the quantity and capacity limits defined in the SGML declaration used by the current structure application.

Modify the SGML declaration using a text editor to correct these errors. Add the SGML declaration to the application definition. Rather than recreating the DTD with the modified application, you can manually invoke the SGML parser to validate your changes.

(13) Add format rules to the EDD and import it into the template.

If you started with a DTD, you (perhaps working with your document designer) now expand the EDD and FrameMaker template to include appropriate format rules.

FrameMaker supports context-sensitive formatting. An element definition can have one or more format rules that specify formatting applied to the element in a particular context in the document. For example, a Head element inside a single Section element might be formatted differently than a Head element inside a Section element that’s nested in another Section element. (That is, a first-level heading probably looks different from a second-level heading.)

(14) Test with sample documents.

You should test your application at various stages of its development and you should test your read/write rules thoroughly.

If end users will be opening markup documents in FrameMaker, invoke the software with sample documents that test your modifications in that direction. If users will be sa ving FrameMaker documents as markup, invoke the software with sample documents to test those modifications. If your e nd users have existing documents for you to use, that can be very helpful. In any case, you may want to create sample documents that test most features of your application.

Task 4. Finishing your application

Once you’ve progressed as far as you can with read/write rules and the application definition, you may find that FrameMaker still does not translate your documents as completely as you wish. If so, you’ll have to use the FDK to complete the translation. At this time, you may also decide to modify FrameMaker’s end-user interface to be more

Creating a Structure Application 38

The development process

appropriate to your end users. Finally, you put all the pieces of the application together to deliver to your end users.

The flowchart shows these steps. The notes below the chart give more detail on some of the steps, and numbers in the flowchart refer to the notes.

Is there more you can do with rules?

Use the FDK for more complex modifications, if needed. (15)

Modify the DTD for direct editing. (16)

Modify the end-user interface. (17)

Assemble application for delivery to end users. (18)

(15) Use the FDK for more complex modifications.

In some situations, read/write rules are not sufficient to describe the appropriate translations between markup and FrameM ake r. Fo r ex amp le, your SGML DTD may us e spe cial mark up minimization, and rules cannot specify creation of minimized markup during export of documents to SGML. In this case, you’d need to write a structure API client.

Even if you need to write a structure API client, you should use read/write rules for as much of the translation as possible. This will simplify what your client must do.

(16) Modify the DTD for direct editing.

If you’ve created a DTD from an EDD and your end users will be editing markup documents directly, you may want to make modifications to the DTD for ease of use. For example, you may choose to change some element definitions to allow tag omission. Furthermore, you may wish to add short reference mapping or to use additional declarations in the DTD to make it easier for your end users.

(17) Modify the end-user interface.

You can modify the menu items available to your end users. At the very least, you’ll probably want to remove the Developer Tools submenu from the File menu. This submenu contains only developer commands. You may wish to remove other menu items as well. For

Structure Application Developer’s Guide 39

The development process

example, if you want all formatting controlled by the format rules in your EDD, you can remove direct formatting commands from your users’ menus. In addition, you might write FDK clients to help your end users in other ways and provide access to those clients on the menus.

(18) Assemble your application for delivery to end users.

You need to make sure the pieces of your application are appropriately packaged for your end users. You may even choose to write scripts to make it easier for your end users to access the application. You should also be prepared to update your application as end users encounter bugs or request enhancements. In addition, be prepared to handle revisions of the EDD or DTD.

For more information

You can find more information on topics in the previous section in other parts of this manual and in other manuals. The table lists the topics by the notes that introduced them.

Note Topic Location

2 Installing FrameMaker Installing FrameMaker

Creating an application definition “Application definition file” on page 50

3, 4 Creating an EDD Part II, “Working with an EDD”

Working with log files “Log files” on page 71

7 Using document filters available with

FrameMaker

8 Creating an EDD and FrameMaker

template Creating an EDD for an existing set of

unstructured document s

9-14 How FrameMaker translates markup

documents and how you can modify that with rules

Writing format rules Chapter 10, “Text Format Rules for

Importing an EDD into a Frame Maker template

15 Using the FDK to create a struct ure

application

17 Modifying the user interface Customizing FrameMaker Products (for

18 Assembling your application “Pieces of a structure application,” next

Using Filters

Part II, “Working with an EDD”

Appendix A, “Conversion Tables for Adding Structure to Document s”

Part III, “Translating between markup

data and FrameMaker”

Containers, Tables, and Footnotes,” and Chapter 12, “Object Format Rules”

Chapter 8, “Developing an Element Definition Document (EDD)”

Structure Import/Export API Programmer’s Guide

Macintosh or WIndows®) or Changing Setup Files (for UNIX®)

Creating a Structure Application 40

Pieces of a structure application

A structure application created with FrameMaker includes an external DTD subset, a FrameMaker template, and a read/write rules document. Other files may be included, depending on the particular application.

The following sections describe the possible parts of a structure application and your options for assembling those parts into a working application. Although you can include a structure API client as part of your application, this section does not talk about what to do with such a client.

Application definition file

Your application requires several files, search paths for these files, and other information. You provide FrameMaker with these paths and other information by placing them in the structapps.fm file. In this file, you create a definition for your application that includes the names of other needed files.

If you provide your users with several structure applications, put information about all of them in a single structapps.fm file. FrameMaker reads this file on startup, so your end users can choose any applications defined in this file. You need to deliver this structapps.fm file to your end users.

For information on the structapps.fm file, see “Application definition file” on page 50

External DTD subset

A structure application pertains to a particular e xternal DTD subset that the software uses when writing markup documents. You specify the external DTD subset in the application definition. While it is optional, to take full advantage of FrameMaker we recommend that you specify a DTD for your application. Your application will use it to:

• Export a FrameMaker document as markup.

• Import a partial markup instance as a text inset in your FrameMaker document.

• Import an entity referenc e to a markup file a s a text inset in your FrameMaker do cument.

• Open an incomplete markup instance as a FrameMaker document.

SGML declaration

XML: The XML specification does not support user-defined SGML declarations.

The following discussion is for SGML, only.

An SGML structure application can use a particular SGML declaration. If it does, you specify the SGML declaration in the application definition.

The SGML declaration is an optional part of an application. Individual SGML documents can begin with a declaration. If ne ither the SGML structure applicatio n nor a particular SGML

Structure Application Developer’s Guide 41

Pieces of a structure application

document specifies a declaration, FrameMaker uses the SGML declaration described in Appendix D, “SGML Declaration.”

If you do specify an SGML declaration, you can deliver it to end users as a separate file.

FrameMaker template

A structure application is associated with a particular FrameMaker template that you can specify in the application definition. The software uses the template to specify the structure and formatting of FrameMaker documents it creates from markup documents. If you do not specify a template, it uses the formats you would get if you used the New command and specified Portrait, rather than a particular template.

As you create your application, you can work with a FrameMaker EDD in a separate file. However, FrameMaker does not use a separate EDD file to find information on structure when opening a markup document; it gets the information directly from the FrameMaker template. At some point during the creation of the FrameMaker template, you must import element definitions from the EDD to the template. Because of this, you don’t deliver the EDD to your end users as a separate file. For maintenance purposes, however, you should retain the EDD in a separate file.

Read/write rules document

You create read/write rules in a FrameMaker document and specify that document in the application definition. FrameMaker uses the rules document both when opening a markup document and when saving a FrameMaker as XML or SGML.

Because a read/write rules document can reference other documents, you can have more than one document containing rules. In the application definition, you specify only the primary file; the software locates the others through the #include mechanism in the primary file.

Your read/write rules document and any include files are separate files you deliver to your end users.

Entity catalogs

If your application requires special external entities or entity catalogs, you must deliver those as separate files to your end users. For information on entities and entity catalogs, see Chapter 17, “Translating Entities and Processing Instructions,” Special Files,” and Appendix F, “ISO Public Entities.”

Chapter 7, “Working with

Documentation

As part of your structure ap plication, y ou shou ld write documentation to explain to your end users how to use the application. It is your responsibility to deliver such documentation either in online or printed form.

Creating a Structure Application 42

Creating a FrameMaker template

This manual is written for developers creating structure applications. Refer end users to the FrameMaker and FrameMaker user guides. You can remove this manual from your end users’ installation directory.

Creating a FrameMaker template

You should deliver your FrameMaker template to end users as a separate file. The template is a FrameMaker document that includes element definitions and formatting information, but not the ultimate content of your docum ents. By using a t emplate, yo u ensure all docume nts for a specific application can have the same element definitions and formatting. For information about importing element definitions into your template, see “Creating an Element Catalog in a template” on page 103

For information on creating a FrameMaker template, see the FrameMaker and FrameMaker user guides. For information on creating the EDD for a template, see Ch apter 8, “Developing an Element Definition Document (EDD).”

Following are descriptions of information you can put in your template that takes advantage of document structure. Included are descriptions of building blocks that define crossreference formats, variable definitions, and format generated lists and indexes, as well as map FrameMaker elements for HTML export. For general informatio n abou t cro ss-re fe rence formats, variable definitions, generated lists and indexes, and HTML export, see the FrameMaker User Guide.

Cross-reference formats

Use the following building blocks to create cross-reference formats that refer to Fr ameMaker elements:

Building block Meaning

<$elempagenum> The page number of the source element <$elemtext> The text of the source elemen t (up to the first paragraph break),

excluding its autonumber, but including any prefix and suffix specified in the element definition

<$elemtextonly> The text of the source element (up to the first paragraph break),

excluding its autonumber and any prefix and suffix specified in the

element definition <$elemtag> The tag of the source element <$elemparanum> The entire autonumber of the source element’s first paragraph (or of the

paragraph containing the source element), including any text in the

autonumber format

Structure Application Developer’s Guide 43

Creating a FrameMaker template

Building block Meaning

<$elemparanumonly> The autonumber counters of the source element’s first paragraph (or of

the paragraph containing the source element), including any characters

between the counters <$attribute[name]> The value of the attribute with the specified name (or, if no value is

specified, the default value)

You can specify building blocks to refer to the ancestor of the source element. Including the tag of an element in the building block indicates that it will refer to the nearest ancestor with the specified tag. For example, a cross-reference to a subsection might also identify its parent section, as in the following: See “Types of plate boundaries” in “Plate tectonics.”

The following list shows how building blocks refer to ancestors of the source element:

Building block Meaning

<$elempagenum[tag]> The page number of the nearest ancestor with the specified tag <$elemtext[tag]> The text of the nearest ancestor (up to the first paragraph break)

with the specified tag, excluding its autonumber, but including any prefix and suffix specified in the element definition

<$elemtextonly[tag]> The text of the nearest ancestor (up to the first paragraph break)

with the specified tag, excluding its autonumber and any prefix

and suffix specified in the element definition <$elemtag[tag]> The tag of the nearest ancestor with the specified tag <$elemparanum[tag]> The entire autonumber of the first paragraph of the nearest

ancestor with the specified tag <$elemparanumonly[tag]> The autonumber counters of the first paragraph of the nearest

ancestor with the specified tag, including any characters between

the counters <$attribute[attrname:tag]> For the preceding elements that are first sib lings, then ancestors

of the source element, the value of the attribute with the specified

name (or, if no value is specified, the default value)

In each of the building blocks, enter the tag of the element to which you want to refer between brackets. For exam ple, if you want to refer to the text of the source’s nearest ancestor tagged Section, you would use:

<$elemtext[Section]>

Creating a Structure Application 44

Creating a FrameMaker template

Variables

If you’re defining running header/footer variables that will refer to elements in structured FrameMaker documents, you can use building blocks that refer to elements or element attributes rather than to paragraphs.

The following building blocks in running header/footer variables refer to an element tag:

Building block What it displays

<$elemtext[tag]> The text (up to the first paragraph break), excluding its

autonumber, but including any prefix and suffix specified in the element definition

<$elemtextonly[tag]> The text (up to the first paragraph break), excluding its

autonumber and any prefix and suffix specified in the element

definition <$elemtag[tag]> The tag <$elemparanum[tag]> The entire autonumber of the element’s first paragraph <$elemparanumonly[tag]> The first paragraph’s autonumber counters, including any

characters between them

Follow these guidelines for using element tag building blocks:

• Enter the tag of the eleme nt for which you want to dis play informat ion betwee n bracket s.

• You can include a context label with the element tag to provide additional information

about the element’s location in the document structure.

• You can include more than one element tag in the brackets, separated with commas.

With multiple tags, FrameMaker uses the first element it finds with one of the tags. An example building block is:

<$elemtext[Head(Level1),Head(Level2)]>

The following building blocks in running header/footer variables refer to element attribute values:

Building block What it displays

<$attribute[name]> The value of the attribute <$highchoice[name]> The highest value of the attribute that appears on the page (where

highest means the value closest to the bottom of the pop-up menu on the right side of the Attributes window)

<$lowchoice[name]> The lowest value of the attribute that appears on the page (where

lowest means the value clos est to the top of the pop-up menu on the right side of the Attributes window)

Structure Application Developer’s Guide 45

Creating a FrameMaker template

Follow these guidelines for using element attribute value building blocks:

• Enter the name of the attribute whose value you want to display between brackets. If a

list of possible values is not defined for the attribute used in a <$highchoice> or <$lowchoice> building block, the building block will be ignored.

• You can specify elements to consider when searching for an attribute value to include in

the running header or footer. To do so, place a colon after the attribute name, followed by one or more element tags separated by commas. For example, a variable with the following definition would display the highest value of the Security attribute of the firstlevel and second-level Section elements.

<$highchoice[Security:Section(Level1), Section(Level2)]>

Special text flows to format generated lists and indexes

Many formatting aspects of a list or index are controlled by a special text flow on a reference page in the generated file. T he name of the reference page ma tches the default filename suffix, such as TOC for a table of contents or IX for a standard index. These reference pages contain building blocks to specify formatting of the entries in the generated files.

The following building blocks apply only to structured documents in FrameMaker. If you use an element-based building block to refer to an unstructured paragra ph, th e informa tion wo n’t appear in the generated list. If you use a paragraph-based building block to refer to an element, the information included in the generated list will come from the paragraph that contains the beginning of the element.

Building block What it displays

<$elemtextonly> Displays the text of the first paragraph of the element, excluding any

autonumber, and the element’s prefix and suffix, if any. Note that prefix and suffix are only excluded for the specific element; if the paragraph text is in a child element that has a prefix or suffix, the prefix or suffix will be included.

<$elemtext> Displays the text of the first paragraph of the element, excluding any

autonumber, but including the element’s prefix and suffix, if any.

<$elemtag> Displays the element tag

For general information about how FrameMaker generates and formats lists and indexes, see the FrameMaker user’s manual.

HTML mapping for export

The FrameMaker User Guide includes instructions for converting a FrameMaker document to HTML. Converting FrameMaker documents to HTML uses nearly the same process, but there are some differences which take advantage of the structure in your documents.

Creating a Structure Application 46

Creating a FrameMaker template

When setting up an application, you should set up the mapping to HTML in advance so your users don’t need to do that work. After you build a template, you can use the process described in the FrameMaker user’s guide to set up the HTML mapping for it. The mapping information will be stored on the HTML reference page of your template.

You can also associate HTML mapping with an EDD. To do this, create a reference page in your EDD named EDD_HTML. Then copy the mapping information from the HTML reference page of your template to the EDD_HTML reference page. If your EDD includes the ImportHTMLMapping element, then the mapping information will be copied to any document that imports your EDD. For more information about including mapping information with an EDD, see “Specifying whether to transfer HTML mapping tables” on page 89

Mapping FrameMaker elements to HTML elements

You specify how to map FrameMaker elements and attributes to HTML elements in the HTML Mapping table on the HTM L reference page. For example, in the following table, Section elements map to HTML <Div>, and Head elements map to HTML <H1> through <H6>:

FrameMaker Source Item

E:Section Div 1,2,3 N E:Head H* Y E:List Ol N E:ListItem Li N A:Description alt

In the above example, the f ollowing syntax is used to specify Frame Maker elements and attributes in the column titled FrameMaker Source Item:

HTML Item Include Element New Web

Page?

Auto#?

Comments

•E:elementname, where elementname is the name of the element

•A:attributename, where attributename is the name of the attribute

Note the following points when mapping a structured document to HTML:

• In unstructured documents, there is a Headings reference page which maps specific

paragraph formats to HTML headings, and assigns a hierarchy to them. In a structured document there is no need for the Headings reference page. You map FrameMaker elements to HTML headings in the Mapping table. The hierarchy is determined by the context of the FrameMaker element, just as context can determine the formatting o f a FrameMaker element.

• The document can be divided into separate web pages at certain levels of hierarchy. In

the above example, HTML export will create a new web page for every section of a level 1, 2, or 3.

Structure Application Developer’s Guide 47

Creating a FrameMaker template

• In unstructured documents, you map paragraph formats to list items, and specify the list

type for that list item’s parent. In a structured document, you specify the list type for FrameMaker list element, and then you map FrameMaker list items to the HTML <Li> element. Also, you do not specify the nesting of lists, since that can be determined by the hierarchy in the FrameMaker document. In the above example, List maps to HTML <Ol>, and ListItem maps to HTML <Li>. If ListItem contains a List, on export to HTML the lists will nest correctly.

• In the above examp le, the Description attribute in FrameMaker maps to the alt

attribute for HTML elements. Every occurrence of a Description attribute will result in an alt attribute in HTML, whether it is valid for that HTML ele ment or not. The HTML specification says that User Agents should ignore attributes they don’t understand, so this is not a major problem unless you need to validate your HTML file. For HTML elements that use the alt attribute (<IMG>, for example) your description can appear in place of that element.

Building blocks for structured documents

You can create HTML conversion m acros that use information specific t o elements and attributes. The following building blocks can be used when defining macros for elements and cross-reference formats:

Building block Meaning

<$elemtext> The text of the source elemen t (up to the first paragraph break),

excluding its autonumber, but including any prefix and suffix specified in the element definition

<$elemtextonly> The text of the source element (up to the first paragraph break),

excluding its autonumber and any prefix and suffix specified in the

element definition <$elemtag> The tag of the source element <$elemparanum> The entire autonumber of the source element’s first paragraph (or of the

paragraph containing the source element), including any text in the

autonumber format <$elemparanumonly> The autonumber counters of the source element’s first paragraph (or of

the paragraph containing the source element), including any characters

between the counters <$attribute[name]> The value of the attribute with the specified name (or, if no value is

specified, the default value)

Creating a Structure Application 48

Working with Special Files 7

This chapter discusses the special files you need to create a structure application. It tells you where to look for them in yo ur directory tree; describes the work ings of two of them, the application definition file and the log file; and points you to the appropriate chapters for information on the other files.

Location of structure files

FrameMaker provides a locat ion for putting all of the special files associated with structure applications. Some files are provided with the software. Others are files you create and store at this location.

If you use FrameMaker on a UNIX platform, when the software needs one of these files it looks in several places. It searches directories in this order:

• curdir/fminit/uilanguage/structured where curdir is the directory from

which you start FrameMaker and uilanguage indicates a particular user-interface language, such as usenglish or ukenglish

•fminit/uilanguage/structured in the user’s home directory

•$FMHOME/fminit/uilanguage/structured, where $FMHOME is the directory in which

FrameMaker is installed

If you use FrameMaker on a Macintosh or Window s platfo rm, when the software needs on e of these files it looks in a directory named structure in the home directory for FrameMaker. On a Windows platform, you can specify an alternate structure directory in the maker.ini file. For information about the maker.ini file, se e the FrameMaker use r’s manual.

On all platforms, you can use the variable $STRUCTDIR to refer to the structure directory. The rest of this chapter follows this convention.

When you install FrameMaker, the structure directory contains the following files and subdirectories:

default.rw The default read/write rules file. FrameMaker uses this file in the

absence of a rules file in the c urrent application. It also uses the file as the template when you create a new rules file with the Developer Tools>New Read/Write Rules File command on the File menu.

structapps.fm The default version of the application definition file. You edit this file so

that it contains the definitions of any applications you create.

Structure Application Developer’s Guide 49

Application definition file

entfmts Default formats used for ISO public entities. For information on this file,

see Appendix F, “ISO Public Entities.”

sgml/ A directo ry containing SGML structure applic ations: sgml/docbook/ The SGML DocBook starter kit files. For information on this directory,

see the online manual Using the DocBook Starter Kit.

sgml/isoents/ Other ISO public entity files. For information on the contents of this

directory, see Appendix F, “ISO Public Entities.”

xml/ A directory containing XML structure applications. xml/xdocbook/ The XML DocBook starter kit files. For information on this directory, see

the online manual Using the XDocBook Starter Kit.

xml/isoents/ Other ISO public entity files. For information on the contents of this

directory, see Appendix F, “ISO Public Entities.”

xml/xhtml/ The XHTML starter kit files. For information on this directory, see the

online manual Using the XHTML Star ter Kit.

If you choose, you can creat e other directories under $STRUCTDIR to hold files for your applications.

Application definition file

You need to deliver a structapps.fm file to your end users. In some situations, you make more than one application available to your end users at the same time. For example, your end users may sometimes need an application based on the DocBook DTD for writing technical documentation and may at other times need an application based on a completely different DTD particular to your company. If so, you provide two applications in one structapps.fm file.

The structapps.fm file provides definitions for the available applications; it can also contain information relevant to all applications, such as a default place to look for entity files.

Important: Reinstalling FrameMaker can overwrite the current structapps.fm file with the default version that ships with the product. Be sure your end users understand this. To keep your site-specific structure applications file intact, they should make a copy of this file before reinstalling, and then use the copy to overwrite the fresh version of structapps.fm.

FrameMaker can associate a p articular document with a structure application in several ways:

• An EDD can explicitly associate itself with a structure application. If it does, all

FrameMaker documents tha t use that EDD are automatically associa ted with the application.

• A structure application can name one or more document types (identified in the markup

in the doctype declaration and in the document’s root element). If it does, all markup

Working with Special Files 50

Application definition file

documents that use one of those document elements are automatically associated with the application.

• If neither of the above occurs or if the associations are ambiguous, FrameMaker asks

the end user to pick a structu re application to use with a document.

Editing an application definition file

The structapps.fm file is a structured FrameMaker document. You edit this file by choosing Structure Tools>Edit Application File from the File menu and using standard FrameMaker editing techniques. FrameMaker reads this file on startup. While developing your application, you may need to change its contents. If you do so, have the software reread the file by using the Structure Tools>Reread Application File command.

The Reread Application File command rereads the current structapps.fm file that is open and has current focus. This command replaces the current list of structure applications stored in memory with the applications defined in the current structapps.fm file. This is true for all platforms.

On UNIX, when you edit the structapps.fm file, you may choose to write it to a directory other than the one in which Fr ameMaker found it. When you then use the Reread Application File command, the software again looks in the three directories mentioned in “Location of structure files” on page 49

Contents of structapps.fm

The highest-level element in an structapps.fm file is StructuredSetup. That element’s first child must be Version, to indicate the product version. The Version element is followed by zero or more SGMLApplication or XMLApplication elements, each of which defines the pie ces o f a struc tur e application. Finally, there can be an optional Defaults element, which specifies informat ion used unless overridden for a pa rticular application.

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

Element Discussed in

ApplicationName “Defining an application” on page 53 CharacterEncoding “Specifying the character encoding for SGML files” on

page 66

CssPreferences “Managing CSS generation” on page 62 ConditionalText “Modifications to the default translation” on page 344 in

Chapter 23, “Translating Conditional Text.”

Defaults “Providing default information” on page 54 DOCTYPE “Specifying a document element” on page 55

Structure Application Developer’s Guide 51

Application definition file

Element Discussed in

DTD “Specifying a DTD” on page 56 Entities “Specifying entities” on page 57 Entity “Specifying the location of individual entities” on page 59 EntityCatalogFile “Specifying entities through an entity catalog” on page 58 EntityName “Specifying the location of indiv idual entities” on page 59 EntitySearchPaths “Specifying a search path for exte rnal entity files” on

page 63

ExternalXRef “Translating external cross-references to and from XML”

on page 326

FileName “Specifying the location of indiv idual entities” on page 59

“Specifying public identifiers” on page 61

FileExtensionOverride “Specifying filename extensions” on page 56 FileNamePattern “Specifying names for external entity files” on page 60 FrameDefaultAPIClient “Specifying a structure API client” on page 66 MaxErrorMessages “Limiting the length of a log file” on page 70 Namespace “Enabling namespaces” on page 56 Path “Specifying a search path for exte rnal entity files” on

page 63 “Specifying a search path for including files in rules

documents” on page 64

Public “Specifying public identifiers” on page 61 PublicId “Specifying public identifiers” on page 61 ReadWriteRules “Specifying a read/write rules document” on page 55 RulesSearchPaths “Specifying a search path for including files in rules

documents” on page 64

SGMLApplication “Defining an application” on page 53 SGMLDeclaration “Specifying an SGML declaration” on page 57 Template “Specifying a FrameMaker template” on page 57 UseAPIClient “Specifying a structure API client” on page 66 UseDefaultAPIClient “Specifying a structure API client” on page 66 Graphic “How FrameMaker searches filename patterns” on

page 60

Mapping “Specifying entities through an entity catalog” on page 58 Notation “Specifying names for external entity files” on page 60 FmTranslator “Specifying a structure API client” on page 66 XMLApplication “Defining an application” on page 53

Working with Special Files 52

Application definition file

Element Discussed in

XMLDisplayEncoding “Specifying the character encoding for XM L files” on

page 68

XMLExportEncoding “Specifying the character encod ing for XML files” on

page 68

Defining an application

FrameMaker collects all informatio n pertaining to conversion of a related set of documents into an SGMLApplication or XMLApplication element. This element has one required child element and several optional child elements.

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

Application Name: name

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

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

Element Discussed in

DOCTYPE “Specifying a document element” on page 55 FileExtensionOverride “Specifying filename extensions” on page 56 ReadWriteRules “Specifying a read/write rules document” on page 55 DTD “Specifying a DTD” on page 56 Template “Specifying a FrameMaker template” on page 57 SGMLDeclaration “Specifying an SGML declaration” on page 57 Entities “Specifying entities” on page 57 RulesSearchPaths “Specifying a search path for including files in rules

documents” on page 64

UseAPIClient “Specifying a structure API client” on page 66 UseDefaultAPIClient “Specifying a structure API client” on page 66 CharacterEncoding “Specifying the character encod ing for XML files” on

page 68

Several of these elements provide pathnam es. If a relative pathna me is given, the soft ware looks for the file in several places (entities and read/write rules files only; hence

RulesSearchPaths and EntitySearchPaths elements):

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

the software first searches the directory in which it found the DTD only. If the pathname

Structure Application Developer’s Guide 53

Application definition file

is absolute, it looks there. If it can’t find it via the specified path, the log reports an error and the operation is aborted.

• $STRUCTDIR (for information on what directory this is, see “Location of structure files”

on page 49)

• The directory from which you started FrameMaker

The following is a typical application; note that these pathnames are for Unix systems:

Application name: ReportNumeric DOCTYPE: Report Read/write rules: reports/rules/repnumer.rul DTD: reports/repnumer.dtd Template: reports/repnumer Rules search paths 1: $STRUCTDIR/reports/rules Use default API client.

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

Providing default information

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

If present, the optional child ele ments of Defaults can occur in any order (with the exception of the Graphics element, it must be the last child) and can include the following elements, discussed in the nam ed sections:

Element Discussed in

ReadWriteRules “Specifying a read/write rules document” on page 55 DTD “Specifying a DTD” on page 56 Namespace “Enabling namespaces” on page 56 Template “Specifying a FrameMaker template” on page 57 SGMLDeclaration “Specifying an SGML declaration” on page 57 Entities “Specifying entities” on page 57 RulesSearchPaths “Specifying a search path for including files in rules

documents” on page 64

FrameDefaultAPIClient “Specifying a structure API client” on page 66 UseAPIClient “Specifying a structure API client” on page 66 MaxErrorMessages “Limiting the length of a log file” on page 70

Working with Special Files 54

Application definition file

Element Discussed in

CharacterEncoding “Specifying the character encod ing for XML files” on

page 68

Graphics “How FrameMaker searches filename patterns” on

page 60

Specifying a document element

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

DOCTYPE: doctype

where doctype identifies a document element. For example,

DOCTYPE: chapter

matches a markup document with the following declaration:

<!DOCTYPE chapter ...>

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

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

Application name: Book DOCTYPE: chapter DOCTYPE: appendix . . .

The DOCTYPE element can be a child of a pa rent SGMLApplication or XMLApplication element only.

Specifying a read/write rules document

The ReadWriteRules element specifies the read/wri te ru les docume nt asso ciated with the application. It looks like:

ReadWriteRules: rules

where rules is the pathname of a FrameMaker read/write rules document.

Structure Application Developer’s Guide 55

Application definition file

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

Specifying a DTD

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

DTD: dtd

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

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

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

Instead, it should simply have the form:

<!element book . . .> . . .

For more information on external DTD subsets, see “XML and SGML DTDs” on page 13 You can have only one DTD element for each application. It can also be a child of the

Defaults element.

Enabling namespaces

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

Namespace

Enable

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

Specifying filename extensions

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

Working with Special Files 56

Application definition file

a .htm extension when saving a document as XHTML. The FileExtensionOverride element looks like this:

FileExtensionOverride: extension

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

Specifying a FrameMaker template

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

Template: template

where template is the pathnam e of a FrameMaker template. The software uses this template to create new FrameMaker documents from markup

documents, which may be single documents resulting from the Open or Import command or documents in a book create d through the Open command.

If this element is not present, the software creates new portrait documents as needed. When you import a markup doc ument into an existing document, the software uses the import template only to access reference elements that are stored on the template’s reference page. (For information about reference elements, see , “Translating SDATA entities as FrameMaker r eference elements.”

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

Specifying an SGML declaration

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

SGMLDeclaration: declaration

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

child of the Defaults element.

Specifying entities

To specify the location of various entities, you use the Entities element. The possible child elements of a parent Entities element are:

Element Discussed in

EntityCatalogFile “Specifying entities through an entity catalog” on page 58 Entity “Specifying the location of individual entities” on page 59 FileNamePattern “Specifying names for external entity files” on page 60

Structure Application Developer’s Guide 57

Application definition file

Element Discussed in

Public “Specifying public identifiers” on page 61 EntitySearchPaths “Specifying a search path for exte rnal entity files” on

page 63

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

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

Specifying entities through an entity catalog

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

Entity locations Entity catalog file: fname

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

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

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

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

Why use entity catalogs

Technical Resolution 9401:1994 published by SGML Open relates to entity mana gement issues affecting how SGML documents work with each other:

• Interpreting external iden tifiers in entity declarations so that an SGML document ca n be

processed by different tools on a single computer system

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

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

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

Working with Special Files 58

Application definition file

Entity catalog format

Each entry in the entity catalog file associat es a filenam e wi th inform atio n abou t an ex tern al entity that appears in a markup document. For example, the following are catalog entries that associate a public identifier with a filename:

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

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

ENTITY "chips" "graphics\chips.tif"

A single catalog can contain both types of entry. If the specified filename in a catalog entry is a relative pathname, the path is relative to the

location of the catalog entry file. For a complete description of the syntax of a catalog entry, see Technical Resolution

9401:1994 Entity Management published by SGML Open.

How FrameMaker searches entity catalogs

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

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

Specifying the location of individual entities

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

Entity locations Entity name: ename Filename: fname

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

the FilenamePattern and EntitySearchPaths elements to help the software find these files.

The Entity element can be a child of a parent Entities element in the Defaults element to set default entity information and of a parent SGMLApplication or

Structure Application Developer’s Guide 59

Application definition file

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

Specifying names for external entity files

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

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

Entity locations: FilenamePattern: pattern

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

Variable Interpretation

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

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

There can be multiple child FilenamePattern elements in a parent Entities element. The software assumes the last pattern in the Entities element is:

FilenamePattern: $(System)

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

How FrameMaker searches filename patterns

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

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

Working with Special Files 60

Application definition file

Example

Suppose the Entities element looks like:

Entity locations: FilenamePattern: $(System).sgm FilenamePattern: $(System).$(Notation)

and the markup document contains:

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

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

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

Important: The NAMECASE GENERAL parameter of th e SGML declaration determines the case-sensitivity of notation names. For XML, the implied setting for this parameter is NO, which means that names are case-sensitive.

For SGML, the value of this parameter in the reference co ncrete syntax is NAMECASE GENERAL YES. With this declaration, the SGML parser forces notation names to uppercase. Because of this, and because the UNIX file system is case-sensitive, on a UNIX system, if you have the default SGML declaration and you use the $(notation) variable with the filename element, that portion of the name must be uppercase.

Specifying public identifiers

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

Entity locations: Public ID: pid

Filename: fname

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

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

Structure Application Developer’s Guide 61

Application definition file

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

Managing CSS generation

The Stylesheets element of an XML structure application tells the software how to treat the use of stylesheets for a given XML document. You can specify whether to use an existing stylesheet, or whether FrameMaker should generate a new one and use that for the exported XML. This element also contains instructions concerning the use of attributes and stylesheet processing instructions. The Stylesheets element looks like:

Stylesheets: CssPreferences: Generate CSS2: enable/disable AddFmCSSAttrToXML: enable/disable RetainStylesheetPIs: enable/disable XmlStylesheet: Type: stylesheet_type URI: path

An XML application can have only one Stylesheets element. It can also be a child of the Defaults element. You can specify any number of stylesheets, and the exported XML will include references to each one.

How the Stylesheets elements CSS generation

When you save a document to XML, FrameMaker can either use an existing stylesheet, or generate a new one from the current EDD. How FrameMaker generates a stylesheet is determined by the values of the children of the Stylesheet element. For more information about how FrameMaker converts EDD information into a stylesheet, see Chapter 15, “Saving EDD Formatting Information as a CSS Stylesheet.”

GenerateCSS2 Specifies whether FrameMaker will generate a CSS when you save the document as XML. It can be set to Enable or Disable. When this is set to Enable, FrameMaker generates a CSS. If a path is provided in StylesheetURI, FrameMaker saves the stylesheet to that location, with that filename. Otherwise, it saves the stylesheet to the same location as the XML document with a filename xmldoc.css, where xmldoc is the name of the XML document you’re saving.

AddFmCSSAttrToXml Specifies whether FrameMaker will write instances of the fmcssattr attribute to elements in the XML document. It can be set to Enable or Disable. An EDD can include context selectors as criteria to assign format rules. CSS has no equivalent to this. When this is set to Enable, Frame Maker use s the fmcssattribute in ce rtain elemen ts so the CSS can achieve the same formatting as the EDD.

Working with Special Files 62

Application definition file

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

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

document.

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

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

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

Specifying a search path for external entity files

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

Entity locations: EntitySearchPaths 1: directory

. . .

N: directory

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

Variable Abbreviation Interpretation

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

processed

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

directory this is, see “Location of structure files” on page 49)

Each directory

How FrameMaker searches for entity files

To locate an external entity, FrameMaker searches the specified directories in the order listed. You can use the EntitySearchPaths element both in the Entities element of the Defaults element and in an XMLApplication or SGMLApplication element. Whe n searching for an external entit y, FrameMaker searches the director ies named in the

EntitySearchPaths element for the application before it searches those in a default EntitySearchPaths element.

Structure Application Developer’s Guide 63

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

Application definition file

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

EntitySearchPaths

. . . N: $SRCDIR

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

Example

Assume the Defaults element is defined as follows:

Defaults Entity locations: FilenamePattern: $(System).sgm FilenamePattern: $(System).$(Notation) EntitySearchPaths 1: $HOME 2: $SRCDIR

and the markup document contains:

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

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

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

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

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

Specifying a search path for including files in rules documents

The RulesSearchPaths element is analogous to the EntitySearchPaths element, but it pertains to additional files you include in a read/write rules document rather than to

Working with Special Files 64

Application definition file

external entities referenced wit hin a markup document. Its Path child elements indicate individual directories. It looks like:

RulesSearchPaths: 1: directory

. . .

N: directory

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

Structure Application Developer’s Guide 65

Application definition file

Variable Abbreviation Interpretation

$HOME ~ The user’s home directory $RULESDIR . The directory containing the current read/write rules

document (for Macintosh and Unix, only)

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

directory this is, see “Location of structure files” on page 49)

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

How FrameMaker searches for rules files

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

searching for a file you includ e in an read/write rules document, FrameMaker sea rches the directories named in the RulesSearchPaths element for the application before it search es those in the RulesSearchPaths element of the Defaults element.

The software assumes RulesSearchPaths ends in this way:

RulesSearchpaths:

. . . N: $RULESDIR

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

Specifying a structure API client

In an application definition, the UseDefaultAPIClient element tells the software that your application does not use a special client for markup translation. In the defau lts sectio n, the FrameDefaultAPIClient element serves the same purpose. The default client is named FmTranslator.

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

Specifying the character encoding for SGML files

The CharacterEncoding element tells the software which encoding to use for the SGML text. Typically, this is only important on non-Western systems, or in SGML applications that encounter SGML files using double-byte text. It can contain one of the following child elements: ISOLatin1, ASCII, ANSI, MacASCII, ShiftJIS, KSC8EUC, GB8EUC, CNSEUC, Big5, JIS8EUC. The CharacterEncoding element looks like this:

CharacterEncoding:

ShiftJIS

Working with Special Files 66

Application definition file

On a non-Western system, the text for an SGML file can contain double-byte text. This text can be in any one of a number of different text encodings. For example, Japanese text on a Unix system is typically in EUC, while on the Macintosh it is typically in Shift-JIS.

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

Important: For SGML documents, you should not use accented characters in element tag names nor attribute names. If you use suc h characters, FrameMaker may not be able to correctly import or export the document.

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

Windows 95/NT Macintosh Unix

Roman languages ANSI Macintosh ASCII ISOLatin-1 Japanese Shift-JIS Shift-JIS JIS8 EUC Simplified Chinese GB8 EUC GB8 EUC GB8 EUC Traditional Chinese Big5 Big5 CNS EUC Korean KSC8 EUC KSC8 EUC KSC8 EUC

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

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

Structure Application Developer’s Guide 67

Application definition file

Specifying the character encoding for XML files

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

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

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

Big5 KSC_5601 EUC-CN macintosh EUC-JP Shift_JIS EUC-KR US-ASCII EUC-TW UTF-16 GB2312 UTF-8 ISO-8859-1 windows-1252

You can add other encodings to your FrameMaker installation—see “Unicode and cha racter encodings” on page 27.

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

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

Display encoding

On import, FrameMaker converts the XML encoding to a display encoding that is appropriate for a given language. However, FrameMaker cannot automatically determine which conversion to make. A lthough the XML document prolog specifies an encoding, the document may contain elements or other constructs that override the language implied by

Working with Special Files 68

Application definition file

that encoding. As a result, you s hould specify a display encoding for the structure application. The display encodings you can specify are:

Display encoding: For this language:

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

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

The display encoding also determines how FrameMaker interprets the cha racters in markup tokens such as GIs and attribute names. If FrameMaker encounters such a token with an unknown character, FrameMaker drops the token. For more information, see “Supported characters in element and attribute names” on page 26.

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

XmlDisplayEncoding:

JISX0208.ShiftJIS

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

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

Note that XML the XML standard includes the xml:lang a ttribute. This attribute can spe cify a change of language for an element and its content. If that language is one of those listed in the table of display encodings, a ch ange mad e by this a ttribute ta ke prec edence over th e setting made via XmlDisplayEncoding.

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

Structure Application Developer’s Guide 69

Application definition file

Exporting XML

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

If: FrameMaker uses:

1. The structure application specifies a value for XmlExportEncoding, and that encoding is supported

2. 1 is not true, and the original XML source specified an encoding, and that encoding is supported

3. 1 and 2 are not true UTF-8

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

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

XmlExportEncoding:

ISO-8859-1

The specified encoding

The encoding that was specified in the original XML source

Limiting the length of a log file

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

MaxErrorMessages: n

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

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

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

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

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

Working with Special Files 70

Log files

FrameMaker log files give you information used to identify and correct errors in your application.

Generating log files

FrameMaker can produce a log file of errors and warnings for each file it processes. If it runs without encountering errors or other conditions requiring messages, it does not create a log file. The one exception to this is that the UNIX batch utilities always produce a log file so that you know what files were processed.

FrameMaker generates messages for conditions such as:

• Markup syntax errors

• Read/write rule syntax errors

• Missing or otherwise unavailable files

• Missing entities

• Inconsistencies betwee n read/write rules and the relevant EDD or DTD

Messages in a log file

Messages written to the log file include warnings, errors, and fatal errors. Warnings are notifications of potential problems; a warning does not necessarily mean

something is wrong with the input. For example, when the softwar e creates an EDD from a DTD, it issues a warning if it encounters an element rule in a read/write rules document for a generic identifier that does n’t exist in the DTD . This situation is lega l, but the software warns you in case you have misspelled the generic identifier in the rules document. For all warnings, the software writes a message and continues processing.

Errors indicate actual problems in the processing. For example, when FrameMaker updates an existing EDD, it reports an error for a FrameMaker element definition that has no counterpart in the DTD. For most errors, the software writes a message and continues processing.

The third category of message indicates fatal errors. These errors cause processing to stop. For example, if FrameMaker encounters a syntax error in a rules document, it stops processing.

To aid in debugging your structure application, FrameMaker provides a facility for locating certain problems. Choose Check Read/Write Rules from the Developer Tools menu. FrameMaker uses the current application to check the validity of the rules document in that application. The command can find many potential problems and most fatal errors.

Structure Application Developer’s Guide 71

Other special files

Using hypertext links

When FrameMaker creates a log file, where possible it includes hypertext links as an additional debugging tool. Each message in a log file has one of the forms shown in the following examples:

-> /usr/vpg/ch1.fm; Invalid property specified for element "AFrame".

/usr/vpg/ch1.sgm; line 25; Required attribute "lang" is missing for element "list".

The first part of the message indicates the location of the problem in the source document; it always includes the source document’s filename. If the source is a Frame Maker document, such as a rules document or a FrameMaker document being imported or exported, there is an arrow to the left as in the first example. The arrow indicates a hypertext link. If you activate the link, the software opens the document to the page containing the problem. If the source isn’t a FrameMaker document, there is no hypertext link. In this situation, the description includes the line number in the file, as in the second example. You must open the file in an appropriate editor.

The second part of the message describes the particular problem encountered. This part of the message always contains a hypertext link to an explanation of the message.

Setting the length of a log file

Processing documents can produce extremely large log files. In practice, you are unlikely to look at all pages of an extr emely large log file. For this reaso n and to save space and time, FrameMaker limits the number of messages it sends to the log file for a given document. For information on how to change that number, see “Limiting the length of a log file” on page 70.

Other special files

There are several other file types you must work with in creating a structure application. These files are discussed in other chapters. For information on creating an EDD, see Part II, “Working with an EDD.” For information on creating read/write rules files, see Chapter 14, “Read/Write Rules and Their Syntax.” For information on ISO public entity set files , see Appendix F, “ISO Public Entities.”

Working with Special Files 72

Part II Working with an EDD

Part II explains how to develop an element definition document (EDD) and define elements in it. If you’re developing an EDD as part of a larger structure application, you should be familiar with Part I, “Developing a FrameMaker structure application,” material in this part.

The chapters in this part are:

• Chapter 8, “Developing an Element Definition Document (EDD)”

Discusses the process of developing an EDD—from creating a new EDD through building a structured template from your element definitions. Read this chapter first for an overall understanding of the process. The chapter also has a list of all elements in an EDD’s Element Catalog, with links to sections where the elements are covered in the syntax chapters.

before using the

• Chapter 9, “Structure Rules for Contain ers, Tables, and Footnotes”

Chapter 11, “Attribute Definitions” Chapter 10, “Text Format Rules for Containers, Tables, and Footnotes” Chapter 12, “Object Format Rules”

The four syntax chapters describe structure rules, attribute definitions, text format rules, and object format rules, and show examples of these constructs in element definitions.

Structure Application Developer’s Guide 73

Working with an EDD 74

Developing an Element Definition Document (EDD) 8

An element definition document (EDD) contains the structure rules, attribute definitions, and format rules for all of the elements in a group of FrameMaker documents. You write and maintain the definitions in the EDD and then convert them to an Element Catalog in a structured template. To work with the elements, end users create documents from the template or exporting from, then importing into a new document.

You can start a new EDD in two ways. If you have a DTD that your end users’ documents will follow, you can begin with the DTD and create an EDD with element definitions that correspond to constructs in the DTD. If you do not have a DTD, or if you do not plan to translate structured documents to markup, you can create an EDD and write its definitions entirely in FrameMaker.

An EDD is a regular structured FrameMaker document—it has an Element Catalog already set up with everything you need to define elements for end-users’ documents. When developing the EDD, you insert elements from the catalog and in most cases provide values to fill out the definitions. For general information on working in structured documents, see the FrameMaker User Guide.

In this chapter

This chapter explains the process of developing an EDD and provides a summary of the elements in the EDD’s Element Catalog. In the outline below, click a topic to go to its page.

A first look at the steps for developing an EDD:

• “Overview of the deve lopment process” on page 76

How to start or update an EDD:

• “Creating or updating an EDD from a DTD” on page 77

• “Starting an EDD without using a DTD” on page 80

Summary of the elements you w ork with in an EDD:

• “The Element Catalog in an EDD” on page 81

How to define elements and supply other information about them:

• “Defining preliminary settin gs in an EDD” on page 88

• “Organizing and commenting an EDD” on page 90

• “Writing element definitions” on page 91

• “Keyboard shortcuts for working in an EDD” on page 102

Structure Application Developer’s Guide 75

Overview of the development process

What to do when you’re finished deve loping an EDD:

• “Creating an Element Catalog in a template” on page 103

• “Saving an EDD as a DTD for export” on page 105

Where to find structured documents and EDDs to review:

• “Sample documents and EDDs” on page 107

Overview of the development process

These are the basic steps you go through to create an EDD and to develop it as part of a workable template for your end users:

Start a new EDD from a DTD.

Update an existing EDD from a DTD.

Create a new EDD (without definitions).

Export the element catalog from an existing structured EDD.

Write or edit element definitions in the EDD.

Repeat the process until you have a final template and EDD.

Deliver the final template to end users.

If you start the process with a DTD, FrameMaker creates a new EDD with definitions that correspond to the declaration s in the DTD. In most cases, as part of this conversion you need to analyze the EDD and DTD together, develop read/write rules, and repeat the process until the translation is complete. You’ll probably at least need to add format rules to the definitions in the EDD.

Developing an Element Definition Document (EDD) 76

Import the element definitions into a template.

Save the final EDD as a DTD (optional).

Test the template on sample documents.

Creating or updating an EDD from a DTD

If you do not have a DTD, you can either export the Element Catalog from an existing FrameMaker document to cr eate a new EDD or create a new empty EDD by selecting File>Developer Tools>New EDD. Then you either edit the definitions of the exported elements or write new element definitions from scratch.

When you’re finished writing and editing element definitions in the EDD, you import the definitions into a FrameMaker template that also stores formats which may be referenced in your format rules. (You may need to coordinate this part of the process with a template designer responsible for formatting information.) Then you test the template on sample XML or SGML documents, revise the definitions in the EDD, reimport the definitions into the template, and repeat the process as necessary until you have a template that works the way you want it to.

Finally, you deliver the structured template to end users—in many cases, along with other pieces of a larger XML or SGML application. If you didn’t start from a DTD but your users will export documents to markup data, you also need to save the EDD as a DTD.

At the end of the process, even though you are finished developing the EDD, you should normally keep it as a separate document to use for maintaining the element definitions.

Creating or updating an EDD from a DTD

If your documents need to conform to a DTD, you can use the DTD as a starting point for your EDD. FrameMaker creates a new EDD with element and attribute definitions that correspond to element declarations and attribute definition list declarations in the DTD. If the declarations in the DTD change, you can update the EDD to match.

About the DTD

A DTD is required in the prolog of an SGML document, and may be in the prolog of an XML document. The DTD provides element and attribute definition list declarations. The markup document can contain these declarations directly, or it can have an identifier that references a set of declarations stored separately in an external entity. This entity is sometimes called an external DTD subset.

If you start an EDD from a DTD, the DTD you use can be either a complete DTD at the beginning of a markup document or an external DTD subset stored in a separate file. In this section, the term DTD can mean either case.

For more information on DTDs and how they can be stored, see “XML and SGML DTDs” on page 13.

Read/write rules and the new EDD

When starting from a DTD, we recommend that you first create an initial EDD with no read/ write rules—or with only a subset of the rules if you have some already developed. This

lets you see how FrameMaker translates the DTD with little or no help from your rules.

Structure Application Developer’s Guide 77

Creating or updating an EDD from a DTD

Once you have both a DTD and an EDD, you can refine the translation in an iterative process of developing read/write rules. First a nalyze the DTD and new EDD tog ether to plan how to modify the translation with rules. Then develop at least some of your rules, update the EDD from the DTD using the rules (see “Updating an EDD from a DTD” on page 79 test the results on sample mark up documents, and repeat the pr ocess as many times as necessary. You may find it easies t to write and test only a few rules dur ing each iteration. For a more detailed discussion of this process, see “Task 3. Creating read/write rules” on page 35.

You develop read/write rules in a special rules document that is part of a structure application. When you create an EDD from a DTD, you can specify which application (and hence which set of rules) to use with the EDD. For information on developing a read/write rules document, see Chapter 14, “Read/Write Rules and Their Syntax.”

An application definition file (such as structapps.fm) describes what files are used in each structure application you deliver to an end user. If necessary, update an application definition in this file so that the application uses the appropriate read/write rules document. To do this, insert a ReadWriteRules element in the definition and type the pathname of the document. For more information, see “Application definition file” on page 50

Creating an EDD from a DTD

To create an EDD from a DTD, choose Open DT D from the File>Structure T ools submenu in any open FrameMaker document. Select the DTD in the Open DTD dialog box, and then select an application in the Use Application dialog box.

The name of the application you select is stored in an SGMLApplication or XMLApplication element in the EDD for future updates and exports. All FrameMaker documents with an Element Catalog derived from the EDD use the application by default.

If you are creating an initial EDD without read/write rules, select <No Application>. This specifies a default structure application with no rules. When you open a DTD with <No Application>, FrameMaker displays a dialog box with the choice to specify whether the EDD will be for an XML or an SGML To specify a structure application for the EDD later, update the EDD from the DTD (see “Updatin g an EDD from a DTD” on page 79 select the application, or insert and fill in an SGMLApplication or XMLApplication element in the EDD. For information on filling in the element, see “Setting a structure application” on page 89.

), and this time

What happens during translation

A DTD has element and attribute definition list declarations that correspond to element and attribute definitions in an EDD. When you translate a DTD to an EDD, FrameMaker makes assumptions about how the constructs from the DTD should be represented. FrameMaker reads through the entire DTD, processing elements and their attributes one at a time. In the absence of read/write rules, th e software translates an element declaration from the DTD

Developing an Element Definition Document (EDD) 78

Creating or updating an EDD from a DTD

to a FrameMaker element definition of the same name, and it produces an attribute definition for each attribute defined for the element.

Note that DTDs contain syntactic information about the structure of a class of documents, but they do not address the semantics of elements they define. For example, DTDs do not distinguish between an element used to define an equation and one used to define a marker. For this reason, the defa ult translation may not convert all of the markup elements correctly. (An exception to this is CALS tables. If your DTD uses the CALS table model, FrameMaker does recognize those elements as table elements.) You can modify the default translation using read/write rules.

For details on the translation of each type of element, see Part III, “Translating between markup data and FrameMaker.”

Updating an EDD from a DTD

These are two of the reasons you may need to update an EDD:

• If you started the EDD from a DTD, in most cases you need to modify the translation by

developing and testing read/wri te rules in an iterative process . As part of each iteration, you update the EDD using the DTD and your current set of read/write rules.

• If any element or attribute declarations in the DTD change, you update the EDD to revise

the corresponding definitions in the EDD.

To update an EDD from a DTD, choose Import DTD from the File>Structure Tools submenu in the EDD. Select the DTD in the Import DTD dialog box. If the Use Application dialog box appears, select a structure ap plication for the EDD. (Use Application appears only if no application is specified in the EDD.)

In the updated EDD, FrameMaker adds definitions for new elements from the DTD, removes definitions for elements that ar e no longer defined, and revises the content rules and attribute definitions for the remaining elements to match changes in the DT D and the current read/write rules. Any format rules and comments in th e EDD are not affected, except for those in definitions that have been removed. (The software records these changes in a log file.) You can save the modified EDD if you want to keep the changes.

Log files for a translated DTD

If FrameMaker encounters any problems while starting or updating an EDD from a DTD, it produces a log file of warnings and errors. A warning is a notification of a potential problem, but it does not necessarily mean something is wrong with the DTD or the resulting EDD. An error indicates an actual pro blem in the processing; some error s can cause the processing to stop altogether.

A log file can have warning messages for conditions such as name changes, and it can have error messages for markup syntax errors, read/write rule errors, and missing files. If you’re updating an EDD from a DTD, the log file also includes a list of changes made to

Structure Application Developer’s Guide 79

Starting an EDD without using a DTD

the EDD and may include error messa ges for inconsistencies between the DTD and the EDD.

This is an example of a message in a log file:

/usr/struct/tutorial/chapter.dtd; line 63 Parameter entity name longer than (NAMELEN-1); truncated

The first line in the message gives the location of the problem in the DTD. The second line describes the problem; you can click this line to see a longer explanation.

A log file is initially locked so that you can click in it to use the hypertext links . If you want to save the log file, you must first unlock it by pressing Esc Flk. (Press Esc Flk again to relock the file.) For general information on FrameMaker log files, see “Log files” on page 71

Starting an EDD without using a DTD

If you do not have a DTD, or if you do not plan to translate structured documents to markup, you can start an EDD without using a DTD. You either create a new EDD and define the elements from scratch or create an EDD that has the element definitions from an existing FrameMaker document. When you start an EDD without a DTD, you can still save the EDD as a DTD later.

If you plan to translate documents to XML or SGML but do not yet have a DTD, we recommend that you begin with an EDD and then continue the development process from there. An EDD has richer semantics than a DTD and a set of tools that facilitate defining elements, so you will probably find it easier to develop an environment for your end users in an EDD.

Creating a new EDD

You can create a new EDD and enter all of the element definitions from scratch. The new EDD has a highest-level element called ElementCatalog, a Version element with the number of the current FrameMaker release, and one empty Element element.

To create a new EDD, choose New EDD from the File>Developer Tools submenu.

Exporting an Element Catalog to a new EDD

You can export the Element Catalog o f an existing structured document to create an EDD. The new EDD has:

• a highest-level element called ElementCatalog

• a Version element with the number of the current FrameMaker release

• a Para element with the name of the structured document and the current date and time

• element definitions for all of the elements from the document’s catalog

Developing an Element Definition Document (EDD) 80

The Element Catalog in an EDD

Exporting an Element Catalog is helpful when you already have a structured document that you’d like to use as a basis for other documents. You will probably need to add or edit element definitions in the new EDD.

To export an Element Catalog to a new EDD, choose Export Element Catalog as EDD from the File>Developer Tools menu in the structured document with the Element Catalog.

The exported EDD and the EDD from which it was created are equivalent in that they have the same element definitions . Th e two EDDs may differ, however, in th e or de r and grouping of definitions. Section, Head, and Para elements from the original EDD are also not preserved in the exported EDD.

The Element Catalog in an EDD

An EDD is a regular structured FrameMaker document. It comes with an Element Catalog that has everything you need to define elements and to specify related information for your end users’ documents. You insert elements from the catalog as you do in any other structured document, and in most cases provide values to fill out the rules.

High-level elements

The highest-level element in an EDD is ElementCatalog. It can have the following child elements, in the order shown. Only the Version element is required. ElementCatalog and the required Version are inserted automatically, along with the optional CreateFormats and Element, when you start a new EDD.

Version

ElementCatalog

StructuredApplication (0 or 1 of this)

CreateFormats or DoNotCreateFormats (0 or 1 of these)

ImportHTMLMapping or DoNotImportHTMLMapping (0 or 1 of these)

Element or FormatChangeList or Para (any number of any of these, including 0, in any order)

Section (any number of these, including 0)

FormatChangeListLimits (0 or 1 of these)

Structure Application Developer’s Guide 81

The Element Catalog in an EDD

The Version element displays the number of the FrameMaker release used when the EDD was created; the number is not editable. The following list describes what the optional child elements are for and where you can find more discussion of them in this manual:

• StructuredApplication: Specifies an SGML or XML application for the EDD and for

documents that use the EDD. You need to type the name of the application. See “Setting a structure application” on page 89

• CreateFormats or DoNotCreateFormats: Specifies whether or not to create formats

automatically when you import e lement definitions into a template or other document. CreateFormats is inserted automatically in a new EDD. See “Specifying whether to create formats automatically” on page 89.

• ImportHTMLMapping or DoNotImportHTMLMapping: Specifies whether or not to

import the EDD’s HTML mapping table into a document when you import the element definitions into template or other document. See “Specifying whether to transfer HTML mapping tables” on page 89.

• Element: Begins the definition of an element. See “Writing element definitions” on

page 91.

• FormatChangeList: Begins the definition of a named format change list. You can use

one of these lists to describe a set of changes to format properties and then refer to the list from element definitions. This is helpful when two or more elements use the same set of changes because you need to describe the changes only once. See “Defining a format change list” on page 163.

• Para: Inserts a paragraph so that you can comment the EDD. This is useful for adding

descriptions of groups of elements or sections of the EDD. See “Organizing and commenting an EDD” on page 90.

• Section: Creates a section so that you can group element definitions or format change

lists in the EDD. By using sections, you can divide a large EDD into more manageable parts. A Head child element is inserted automatically with Section. See “Organizing and commenting an EDD” on page 90.

• FormatChangeListLimits: Begins a specification of minimum and maximum limits on

relative values used in format change lists and text format rules in the EDD. See “Setting minimum and maximum limits on properties” on page 165.

All elements in the catalog

This section lists all of the elements in an EDD’s Element Catalog—except for a few very low-level elements for completing a formatting specification, such as Left and Right (for Alignment) and Yes and No (for ChangeBars). Click an element tag to go to the discussion of the element in one of the EDD chapters.

Developing an Element Definition Document (EDD) 82

Macromedia FrameMaker - 7.1 User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Before You Begin

XML and SGML

Developing structured FrameMaker templates

Developing XML and SGML applications

Prerequisites

Using FrameMaker documentation

Using this manual

Using other FrameMaker documentation

Using FDK manuals

What’s New in FrameMaker 1

What’s new in FrameMaker 7.1

Conditional text

External cross-references

Preserving the XML extension

What’s new in FrameMaker 7.0

Priority of variable definitions

Path and filename changes

Application development

Read/write rules

Namespaces

CSS support

Exporting variables to markup

New starter kits

Structure Application Basics 2

Where to begin

Structure application scenarios

Translating in one or two directions?

Can you simplify when translating in only one direction?

Do you have an existing DTD or EDD?

Structure application development

The starting point: an EDD or DTD

Translation between DTDs and EDDs

Formatting information in FrameMaker

Changing the default translation

How you modify the translation

What your end users do

A General Comparison of Markup and FrameMaker Documents 3

Structure descriptions

FrameMaker EDDs

XML and SGML DTDs

Elements

FrameMaker element types

XML and SGML elements

Attributes

Element declarations and definitions

Element content

Inclusions and exclusions

Entities

Documents

Markup documents

Multiple-file documents

FrameMaker documents

Format rules

Graphics

Equations

Tables

Cross-references

Processing instructions

Parameter entity declarations

The SGML and FrameMaker Models 4

SGML declaration

SGML features with no counterparts

Marked sections and conditional text

Unsupported optional SGML features

The XML and FrameMaker Models5

Namespace declaration

Rubi text

Element and attribute definition

Supported characters in element and attribute names

Unicode and character encodings

Multiple attribute lists for an element

Supported encodings

FrameMaker display encodings

Encoding for XML files

Creating a Structure Application 6