Macromedia FrameMaker - 12.0 User Guide

ADOBE® FRAMEMAKER® 12

STRUCTURED APPLICATION DEVELOPER REFERENCE

Structured Application Developer Reference Online Manual

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Contents

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

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

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

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

Providing default information . . . . . . . 11

Specifying the character encoding for SGML files . 11

Specifying conditional text output . . . . . . 13

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

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

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

Specifying entities through an entity catalog . 15

Specifying the location of individual entities . 16

Specifying names for external entity files. . . 17

Specifying public identifiers . . . . . . . 18

Specifying a search path for external entity files 19

Specifying external cross reference behavior . . 20

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

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

Specifying filename extensions . . . . . . . 21

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

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

Specifying a search path for included files in rules

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

How FrameMaker searches for rules files. . . 23

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

Specifying an SGML declaration . . . . . . 24

Managing CSS import/export and XSL transformation 24

How the Stylesheets element affects CSS

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

How the Stylesheets element affects CSS import 25

How the Stylesheets element affects XSL

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

Specifying a FrameMaker template . . . . . 26

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

Specifying the character encoding for XML files . 27

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

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

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

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

Mapping graphic notations to file types . . . . 30

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

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

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

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

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

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

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

Structured Application Developer Reference 1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

do not output book processing instructions. . . 51

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

output book processing instructions . . . . . 143

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

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

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

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

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

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

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

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

reformat using target document catalogs . . . 151

retain source document formatting . . . . . 152

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

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

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

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

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

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

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

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

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

write structured document instance only . . . 163

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

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

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

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

Generating an initial conversion table. . . . 169

Setting up a conversion table from scratch . . 170

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

Adding or modifying rules in a conversion table . 171

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

Specifying the root element for a structured

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

Identifying a document object to wrap . . . 173

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

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

Providing an attribute for an element. . . . 177

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

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

Promoting an anchored object . . . . . . 179

Flagging format overrides . . . . . . . 180

Wrapping untagged formatted text . . . . 180

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

Building table structure from paragraph format tags 182

Testing and correcting a conversion table . . . 182

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

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

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

CSS color and backgrounds properties . . . . 189

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

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

CSS generated content, automatic numbering, and

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

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

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

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

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

Namespace and Schema location attributes. . 200

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

Structured Application Developer Reference 3

Attributes of simple type elements . . . . 201

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

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

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

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

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

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

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

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

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

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

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

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

Extension and restriction of complex types . . 209

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

Unsupported Schema features . . . . . . . 211

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

FrameMaker properties that DO NOT have

corresponding CALS attributes . . . . . . . 213

Element and attribute definition list declarations . 214

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

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

Inheriting attribute values . . . . . . . 217

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

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

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

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

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

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

Unsupported optional SGML features. . . . . 226

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

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

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

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

What happens with the declarations and rules. . 232

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

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

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

Before You Begin

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

XML and SGML

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

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

Developing structured FrameMaker templates

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

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

Developing XML and SGML applications

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

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

Structured Application Developer Reference 5

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

A structure application primarily consists of:

• A structured template

• DTD or schema

• Read/Write rules (described in this manual)

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

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

Prerequisites

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

• Structured document authoring in FrameMaker

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

• FrameMaker end-user concepts and command syntax

• FrameMaker template design.

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

• XSLT 1.0

• C programming

• FDK API usage.

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

Using FrameMaker documentation

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

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

Before You Begin 6

Using this manual

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

Typographical conventions

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

Italics Variables or placeholders in code. For example, in

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

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

rules, filenames, and pathnames.

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

book or to a URL in your web browser.

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

Validate... item in the Element menu.

Using other FrameMaker documentation

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

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

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

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

Structured Application Developer Reference 7

Using FDK manuals

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

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

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

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

Programmer’s Guide.

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

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

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

Programmer’s Guide.

Before You Begin 8

Structure Application Definition Reference 1

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

Contents of an application definition file

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

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

Element Discussed in

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

Define an application

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

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

Application name: name

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

applications.

Structured Application Developer Reference 9

Define an application

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

Element Discussed in

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

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

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

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

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

on page 22

page 24

“Specifying a structure API client” on page 27

page HIDDEN

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

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

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

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

Location of structure files).

• The directory from which you started FrameMaker.

Structure Application Definition Reference 10

Providing default information

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

Providing default information

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

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

Element Discussed in

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

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

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

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

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

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

“Specifying a structure API client” on page 27

on page 22

page 24

page HIDDEN

Specifying the character encoding for SGML files

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

Structured Application Developer Reference 11

Specifying the character encoding for SGML files

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

SGML character encoding: Iso Latin1

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

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

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

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

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

Languages Windows

Roman languages ANSI

Japanese Shift-JIS

Simplified Chinese GB8 EUC

Traditional Chinese Big5

Korean KSC8 EUC

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

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

Structure Application Definition Reference 12

Specifying conditional text output

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

Child of OutputTextPi FrameMaker outputs

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

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

Specifying a DOCTYPE element

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

DOCTYPE: doctype

where doctype identifies a document element.

hidden conditional text

Processing instructions delimit conditional text

For example,

DOCTYPE: chapter

matches a markup document with the following declaration:

<!DOCTYPE chapter ...>

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

Structured Application Developer Reference 13

Specifying a DTD

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

Application name: Book DOCTYPE: chapter appendix . . .

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

Specifying a DTD

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

DTD: dtd

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

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

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

Instead, it should simply have the form:

<!element book . . .> . . .

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

DTDs.

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

Specifying entities

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

Entity locations

The possible child elements of a parent Entities element are:

Element Discussed in

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

Structure Application Definition Reference 14

Specifying entities

Element Discussed in

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

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

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

Specifying entities through an entity catalog

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

Entity locations Entity catalog file: fname

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

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

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

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

Why use entity catalogs

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

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

processed by different tools on a single computer system

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

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

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

Structured Application Developer Reference 15

Specifying entities

Entity catalog format

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

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

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

ENTITY "chips" "graphics\chips.tif"

A single catalog can contain both types of entry.

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

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

How FrameMaker searches entity catalogs

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

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

Specifying the location of individual entities

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

Entity locations Entity name: ename Filename: fname

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

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

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

Structure Application Definition Reference 16

Specifying entities

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

Specifying names for external entity files

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

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

Entity locations: Filename pattern: pattern

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

Variable Interpretation

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

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

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

Filename pattern: $(System)

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

How FrameMaker searches filename patterns

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

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

Structured Application Developer Reference 17

Specifying entities

Example

Suppose the Entities element looks like:

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

and the markup document contains:

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

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

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

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

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

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

Specifying public identifiers

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

Entity locations: Public ID: pid

Filename: fname

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

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

Structure Application Definition Reference 18

Specifying entities

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

Specifying a search path for external entity files

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

Entity locations: Entity search paths 1: directory

. . .

N: directory

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

Variable Abbreviation Interpretation

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

processed

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

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

of structure files)

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

How FrameMaker searches for entity files

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

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

Entity search paths

. . . N: $SRCDIR

Structured Application Developer Reference 19

Specifying external cross reference behavior

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

Example

Assume the Defaults element is defined as follows:

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

and the markup document contains:

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

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

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

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

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

Specifying external cross reference behavior

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

Change file extension to .XML

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

External X-Ref:

Change Reference To .XML: Enable

Structure Application Definition Reference 20

Specifying filename extensions

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

Where:

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

• filename is the name of the saved source XML file

• elemID is the ID of the referenced element.

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

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

Try alternative extensions

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

External X-Ref:

Try Alternative Extensions: Enable

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

Specifying filename extensions

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

File Extension Override: extension

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

Structured Application Developer Reference 21

Enabling namespaces

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

Namespace: Enable

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

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

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

Specifying a read/write rules document

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

Read/write rules: rules

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

the Defaults element.

Specifying a search path for included files in rules documents

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

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

. . .

N: directory

Structure Application Definition Reference 22

Specifying a Schema for XML

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

Variable Abbreviation Interpretation

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

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

structure files)

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

How FrameMaker searches for rules files

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

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

The software assumes RulesSearchPaths ends in this way:

Search paths for included read/write rules files:

. . . N: $RULESDIR

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

Specifying a Schema for XML

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

Schema: schema_path

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

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

Structured Application Developer Reference 23

Specifying an SGML declaration

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

SGML declaration: declaration

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

child of the Defaults element.

Managing CSS import/export and XSL transformation

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

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

How the Stylesheets element affects CSS generation

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

CSS2 Preferences:

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

Retain Stylesheet Information: enable/disable XML Stylesheet:

Type: stylesheet_type URI: path

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

EDD Formatting Information as a CSS Stylesheet

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

Structure Application Definition Reference 24

Managing CSS import/export and XSL transformation

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

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

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

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

document.

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

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

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

How the Stylesheets element affects CSS import

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

CSS2 Preferences:

ProcessStylesheetPI: enable/disable

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

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

How the Stylesheets element affects XSL transformation

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

Structured Application Developer Reference 25

Specifying a FrameMaker template

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

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

Stylesheet: path Stylesheet Parameters

Name: parameter name Expression: exp

Postprocessing:

Stylesheet: path Stylesheet Parameters

Name: parameter name Expression: exp

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

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

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

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

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

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

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

XSL Transformation for XML.

Specifying a FrameMaker template

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

Template: template

where template is the pathname of a FrameMaker template.

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

Structure Application Definition Reference 26

+ 230 hidden pages