Home » Adobe Manuals » Computer Software » Adobe 65030365 » Manual Viewer

Adobe 65030365 Developer's Guide - Page 269

On import to FrameMaker, Internal text entities

UPC - 883919170923

Add to My Manuals
Save this manual to your list of manuals

Page 269 highlights

17 D e f a u l t t r a n s l a t i o n On import to FrameMaker By default, FrameMaker interprets entity references as appropriate document objects, and saves enough information to recreate the associated entity declarations on export. The software stores information about the entity declaration in the following ways: • The entity name is stored with the FrameMaker document object that corresponds with the original entity reference (as it was in the XML or SGM). • If the entity was declared in the internal DTD subset of the document instance, the software stores that information on the Entity Declarations reference page of the resulting FrameMaker document. • If the entity was declared in the external DTD subset, the software assumes it will be declared in your structure application's DTD. No entity declaration information is stored with the FrameMaker document. In this way, the software can import and export entity references correctly. You can also modify your DTD or use read/write rules to have FrameMaker treat some entities differently. The rest of this section describes how FrameMaker imports various entities and unknown processing instructions in the absence of rules or clients. Internal text entities XML: The XML specification doesn't treat markup data as literals in an internal text entity. For example, a reference to the following entity: appears in a document as: An ampersand (&) may be escaped numerically (&) or with a general entity (&). Internal XML or SGML text entities are text entities whose replacement text is determined solely by information in their declarations. For SGML, the parser recognizes any markup within the entity text as such. The following are examples of declarations of internal text entities-The first example is valid in XML and SGML, while the second and third examples are only valid in SGML: On import, FrameMaker tests the entity text to make sure it has no characters which can be recognized as markup in any context (within the SGML reference delimiter set). Structure Application Developer's Guide 251

Section	Page
Contents	3
Before You Begin	15
XML and SGML	15
Developing structured FrameMaker templates	15
Developing XML and SGML applications	15
Prerequisites	16
Using FrameMaker documentation	16
Using this manual	16
Using other FrameMaker documentation	17
Using FDK manuals	17
Part I Developing a FrameMaker structure application	19
What’s New in FrameMaker	21
What’s new in FrameMaker 7.1	21
Conditional text	21
External cross-references	21
Preserving the XML extension	21
Priority of variable definitions	22
What’s new in FrameMaker 7.0	22
Path and filename changes	22
Application development	23
Read/write rules	23
Namespaces	23
CSS support	23
Exporting variables to markup	23
New starter kits	24
Structure Application Basics	25
Where to begin	25
Structure application scenarios	25
Translating in one or two directions?	25
Can you simplify when translating in only one direction?	26
Do you have an existing DTD or EDD?	26
Structure application development	27
The starting point: an EDD or DTD	29
Translation between DTDs and EDDs	29
Formatting information in FrameMaker	29
Changing the default translation	29
How you modify the translation	30
What your end users do	30
A General Comparison of Markup and FrameMaker Documents	31
Structure descriptions	31
FrameMaker EDDs	31
XML and SGML DTDs	31
Elements	32
FrameMaker element types	33
XML and SGML elements	33
Element declarations and definitions	34
Element content	34
Inclusions and exclusions	34
Attributes	34
Entities	35
Documents	36
Markup documents	36
FrameMaker documents	37
Multiple-file documents	37
Format rules	37
Graphics	38
Equations	38
Tables	39
Cross-references	39
Processing instructions	40
Parameter entity declarations	40
The SGML and FrameMaker Models	41
SGML declaration	41
SGML features with no counterparts	41
Marked sections and conditional text	41
Unsupported optional SGML features	42
The XML and FrameMaker Models	43
Namespace declaration	43
Rubi text	44
Element and attribute definition	44
Supported characters in element and attribute names	44
Multiple attribute lists for an element	45
Unicode and character encodings	45
Supported encodings	45
FrameMaker display encodings	46
Encoding for XML files	46
Creating a Structure Application	47
The development process	48
Task 1. Producing an initial EDD and DTD	48
(1) Consider the main design issues.	49
(2) Set up the development environment.	49
(3) Create an initial EDD from your DTD, if you have one.	50
(4) Create an EDD, if you’re starting from scratch.	50
(5) Create an initial DTD from your EDD.	50
Task 2. Getting sample documents	51
(6) Create sample documents if you have none.	52
(7) Use document import filters to get FrameMaker documents.	53
(8) Structure unstructured FrameMaker documents if necessary.	53
Task 3. Creating read/write rules	53
(9) Analyze the details of what your application must do.	54
(10) Write rules and modify the application definition.	55
(11) Create a new version of the EDD or the DTD.	55
(12) Correct syntax errors uncovered by the parser.	55
(13) Add format rules to the EDD and import it into the template.	56
(14) Test with sample documents.	56
Task 4. Finishing your application	56
(15) Use the FDK for more complex modifications.	57
(16) Modify the DTD for direct editing.	57
(17) Modify the end-user interface.	57
(18) Assemble your application for delivery to end users.	58
For more information	58
Pieces of a structure application	59
Application definition file	59
External DTD subset	59
SGML declaration	59
FrameMaker template	60
Read/write rules document	60
Entity catalogs	60
Documentation	60
Creating a FrameMaker template	61
Cross-reference formats	61
Variables	63
Special text flows to format generated lists and indexes	64
HTML mapping for export	64
Mapping FrameMaker elements to HTML elements	65
Building blocks for structured documents	66
Working with Special Files	67
Location of structure files	67
Application definition file	68
Editing an application definition file	69
Contents of structapps.fm	69
Defining an application	71
Providing default information	72
Specifying a document element	73
Specifying a read/write rules document	73
Specifying a DTD	74
Enabling namespaces	74
Specifying filename extensions	74
Specifying a FrameMaker template	75
Specifying an SGML declaration	75
Specifying entities	75
Specifying entities through an entity catalog	76
Why use entity catalogs	76
Entity catalog format	77
How FrameMaker searches entity catalogs	77
Specifying the location of individual entities	77
Specifying names for external entity files	78
How FrameMaker searches filename patterns	78
Example	79
Specifying public identifiers	79
Managing CSS generation	80
How the Stylesheets elements CSS generation	80
Specifying a search path for external entity files	81
How FrameMaker searches for entity files	81
Example	82
Specifying a search path for including files in rules documents	82
How FrameMaker searches for rules files	84
Specifying a structure API client	84
Specifying the character encoding for SGML files	84
Specifying the character encoding for XML files	86
Display encoding	86
Exporting XML	88
Limiting the length of a log file	88
Log files	89
Generating log files	89
Messages in a log file	89
Using hypertext links	90
Setting the length of a log file	90
Other special files	90
Part II Working with an EDD	91
Developing an Element Definition Document (EDD)	93
In this chapter	93
Overview of the development process	94
Creating or updating an EDD from a DTD	95
About the DTD	95
Read/write rules and the new EDD	95
Creating an EDD from a DTD	96
What happens during translation	96
Updating an EDD from a DTD	97
Log files for a translated DTD	97
Starting an EDD without using a DTD	98
Creating a new EDD	98
Exporting an Element Catalog to a new EDD	98
The Element Catalog in an EDD	99
High-level elements	99
All elements in the catalog	100
Defining preliminary settings in an EDD	106
Specifying whether to create formats automatically	107
Specifying whether to transfer HTML mapping tables	107
Setting a structure application	107
Organizing and commenting an EDD	108
Writing element definitions	109
About element tags	110
Guidelines for writing element definitions	110
Defining a container, table or footnote element	111
Examples	112
Basic steps	113
Defining a Rubi group element	115
Examples	116
Basic steps	116
Defining an object element	117
Examples	117
Basic steps	118
Keyboard shortcuts for working in an EDD	120
Editing structure	120
Moving around the structure	121
Creating an Element Catalog in a template	121
Importing element definitions	122
Log files for imported element definitions	122
Debugging element definitions	122
Saving an EDD as a DTD for export	123
Read/write rules and the new DTD	123
Creating a DTD from an EDD	124
What happens during translation	124
SGML declarations	125
Log files for a translated EDD	125
Sample documents and EDDs	125
Structure Rules for Containers, Tables, and Footnotes	127
In this chapter	127
Overview of EDD structure rules	128
Writing an EDD general rule	129
Syntax of a general rule for EDD elements	130
Occurrence indicators and connectors	130
Content symbols	131
Parentheses	131
Restrictions on general rules for tables	132
Default general rules for EDD elements	133
Specifying validity at the highest level in a flow	134
Adding inclusions and exclusions	134
Inclusions	135
Exclusions	136
How content rules translate to markup data	136
Inserting descendants automatically in containers	137
Inserting table parts automatically in tables	138
Initial structure pattern	139
Default initial structure	140
Inserting Rubi elements automatically in Rubi groups	141
Initial structure pattern	141
Debugging structure rules	141
Text Format Rules for Containers, Tables, and Footnotes	143
In this chapter	143
Overview of text format rules	144
How elements inherit formatting information	145
The general case	146
Inheritance in a table or footnote	148
Inheritance in a document within a book	149
Specifying an element paragraph format	150
Writing context-dependent format rules	150
All-contexts rules	151
Context-specific rules	152
Defining a context	152
Wildcards for ancestors	153
OR indicators	153
Sibling indicators	153
Attribute indicators	154
Order of context clauses	155
Level rules	156
Using the current element in the count	157
Stopping the count at an ancestor	158
Nested format rules	158
Multiple format rules	159
Context labels	160
Defining the formatting changes in a rule	161
Paragraph formatting	161
Text range formatting	162
No additional formatting	163
Specifications for individual format properties	164
Basic properties	165
Indentation, spacing, and alignment	165
Tab stops	167
Font properties	168
Pagination properties	170
Numbering properties	171
Advanced properties	172
Table Cell properties	173
Asian Text Spacing properties	173
Writing first and last format rules	174
How first and last rules are applied	175
A first or last rule with an autonumber	175
Defining prefixes and suffixes	176
How prefix and suffix format rules are applied	176
A prefix or suffix for a text range	177
A prefix or suffix for a paragraph	177
A prefix or suffix for a sequence of paragraphs	178
A prefix or suffix for a text range or a paragraph	179
Attributes in a prefix or suffix rule	180
When to use an autonumber, prefix or suffix, or first or last rule	180
Defining a format change list	181
Setting minimum and maximum limits on properties	183
Debugging text format rules	184
Attribute Definitions	187
In this chapter	187
Some uses for attributes	187
How an end user works with attributes	188
Writing attribute definitions for an element	189
Attribute name	190
Attribute type	190
Specification for a required or optional value	191
Hidden and Read-only attributes	192
List of values for Choice attributes	193
Range of values for numeric attributes	193
Default value	194
Using UniqueID and IDReference attributes	194
UniqueID attributes	196
When an end user provides an ID	196
When FrameMaker generates an ID	197
IDReference attributes	197
Using attributes to format elements	198
Using attributes to provide a prefix or suffix	200
Object Format Rules	203
In this chapter	203
Overview of object format rules	204
Context specifications for object format rules	205
All-contexts rules	205
Context-specific rules	206
Defining a context	206
Wildcards for ancestors	206
OR indicators	206
Sibling indicators	207
Attribute indicators	207
Order of context clauses	208
Setting a table format	208
Specifying a graphic content type	209
Setting a marker type	210
Setting a cross-reference format	212
Setting an equation size	212
Specifying a system variable	213
Debugging object format rules	215
Part III Translating between markup data and FrameMaker	217
Introduction to Translating between Markup Data and FrameMaker	219
In this chapter	219
What you can do with read/write rules	219
What you can do with structure API clients	220
A detailed example	221
DTD fragment	221
Document instance	222
EDD fragment	223
Formatting and read/write rules	224
FrameMaker document	224
Opening XML documents	225
Read/Write Rules and Their Syntax	227
In this chapter	227
The rules document	227
Rule order	228
Rule syntax	229
Case conventions	230
Strings and constants	230
String syntax	230
Constant syntax	231
Variables in strings	231
Comments	232
Include files	232
Reserved element names	232
Commands for working with a rules document	233
Saving EDD Formatting Information as a CSS Stylesheet	235
In this chapter	235
Default translation	235
Comparison of EDD format rules and CSS	236
Differences in translation	240
Right and left indents	240
Context-specific format rules	240
If Else rules	241
Unsupported rules and statements	242
Generating a CSS	242
Generating a CSS on command	242
Generating a CSS on Save As XML	243
Specifying how FrameMaker generates a CSS	243
Stylesheet specifications in a structure application	243
Translating Elements and Their Attributes	245
In this chapter	245
Default translation	246
Translating model groups and general rules	246
Translating attributes	247
Attribute types and declared values	248
Naming elements and attributes	249
Inclusions and exclusions	251
Line breaks and record ends	251
Modifications to the default translation	252
Renaming elements	252
Renaming attributes	253
Renaming attribute values	253
Translating a markup element to a footnote element	254
Translating a markup element to a Rubi group element	255
Changing the declared content of a markup element associated with a text- only element	256
Retaining content but not structure of an element	256
Retaining structure but not content of an element	257
Formatting an element as a boxed set of paragraphs	258
Suppressing the display of an element’s content	258
Discarding a markup or FrameMaker element	258
Discarding a markup or FrameMaker attribute	259
Specifying a default value for an attribute	260
Changing an attribute’s type or declared value	261
Creating read-only attributes	262
Using markup attributes to specify FrameMaker formatting information	262
Translating Entities and Processing Instructions	265
In this chapter	265
Default translation	266
On export to markup	266
Generating processing instructions on export	267
Exporting special marker types as processing instructions and entity references	268
Exporting text insets	268
On import to FrameMaker	269
Internal text entities	269
Internal character data (CDATA) entities	270
Internal special character data (SDATA) entities	270
External data entities	272
External text entities	273
Parameter entities	273
Subdocument (SUBDOC) entities	273
PI entities	274
Processing instructions	274
Limitations to Writing Processing Instructions	275
Modifications to the default translation	275
Specifying the location of entity declarations	276
Renaming entities that become variables	276
Translating entity references on import and export	276
Translating entities as FrameMaker variables	277
Translating SDATA entities as special characters in FrameMaker	278
Translating SDATA entities as FrameMaker text insets	280
Translating SDATA entities as FrameMaker reference elements	281
Translating external text entities as text insets	282
Translating internal text entities as text insets	283
Changing the structure and formatting of a text inset on import	284
Discarding external data entity references	285
Translating ISO public entities	285
Facilitating entry of special characters that translate as entities	286
Creating book components from general entities	286
Discarding unknown processing instructions	286
Using entities for storing graphics or equations	287
Translating Tables	289
In this chapter	289
Default translation	290
On import to FrameMaker	290
How CALS elements translate	291
How CALS attributes translate	292
How colspec and spanspec elements translate	292
On export to markup	293
Modifications to the default translation	293
Formatting properties for tables	294
Properties for general table formatting	294
Formatting properties for straddles	296
Formatting properties for cell paragraph formatting	297
Identifying and renaming table parts	297
Representing FrameMaker table properties as attributes in markup	298
Representing FrameMaker table properties implicitly in markup	299
Adding format rules that use CALS attributes (CALS only)	300
Working with colspecs and spanspecs (CALS only)	301
Specifying which part of a table a row or cell occurs in	301
Specifying which column a table cell occurs in	302
Omitting explicit representation of table parts	303
Creating parts of a table even when those parts have no content	305
Specifying the ruling style for a table	307
Exporting table widths proportionally	308
Creating vertical straddles	308
Using a table to format an element as a boxed set of paragraphs	311
Creating tables inside other tables	313
Rotating tables on the page	313
Translating Graphics and Equations	315
In this chapter	315
Default translation	316
Supported graphic file formats	316
General import and export of graphic elements	317
On export to markup	318
Text of default graphics and equations declarations	318
Element and attribute structure	320
Entity and file attributes	320
Anchored frame properties	320
Other graphic properties	322
Exporting entity declarations	323
Creating graphic files on export	324
On import to FrameMaker	325
Importing graphic entities	325
Graphic attributes and properties	326
Graphic file formats	326
Modifications to the default translation	326
Identifying and renaming graphic and equation elements	327
Exporting graphic and equation elements	327
Representing the internal structure of equations	329
Renaming markup attributes that correspond to graphic properties	329
Omitting representation of graphic properties in markup	330
Omitting optional elements and attributes from the default DTD declarations	331
Specifying the data content notation on export	331
Changing the name of the graphic file on export	332
Changing the file format of the graphic file on export	334
Changing the file format for graphics imported by reference	335
Specifying the entity name on export	336
Changing how FrameMaker writes out the size of a graphic	337
Translating Cross-References	339
In this chapter	339
Default translation	339
On export to markup	340
On import to FrameMaker	341
Modifications to the default translation	342
Translating markup elements as FrameMaker cross-reference elements	342
Renaming the markup attributes used with cross-references	343
Translating FrameMaker cross-reference elements to text in markup	344
Maintaining attribute values with FrameMaker	344
Translating external cross-references to and from XML	344
Translating Variables and System Variable Elements	347
In this chapter	347
Default translation	347
On export to markup	348
On import to FrameMaker	349
Modifications to the default translation	349
Renaming or changing the type of entities when translating to variables	350
Translating markup elements as system variable elements	351
Translating FrameMaker system variable elements to text in markup	351
Translating FrameMaker variables as SDATA entities	352
Discarding FrameMaker variables	352
Translating Markers	353

Match case Limit results 1 per page

Default translation

Structure Application Developer’s Guide

251

On import to FrameMaker

By default, FrameMaker interprets entity references as appropriate document objects, and

saves enough information to recreate the associated entity declarations on export. The

software stores information about the entity declaration in the following ways:

•

The entity name is stored with the FrameMaker document object that corresponds with

the original entity reference (as it was in the XML or SGM).

•

If the entity was declared in the internal DTD subset of the document instance, the

software stores that information on the Entity Declarations reference page of the resulting

FrameMaker document.

•

If the entity was declared in the external DTD subset, the software assumes it will be

declared in your structure application’s DTD. No entity declaration information is stored

with the FrameMaker document.

In this way, the software can import and export entity references correctly. You can also

modify your DTD or use read/write rules to have FrameMaker treat some entities differently.

The rest of this section describes how FrameMaker imports various entities and unknown

processing instructions in the absence of rules or clients.

Internal text entities

Internal XML or SGML text entities are text entities whose replacement text is determined

solely by information in their declarations. For SGML, the parser recognizes any markup

within the entity text as such. The following are examples of declarations of internal text

entities—The first example is valid in XML and SGML, while the second and third examples

are only valid in SGML:

<!ENTITY product "FrameMaker">

<!ENTITY blist "<list type=bulleted>">

<!ENTITY blist STARTTAG "list type=bulleted">

On import, FrameMaker tests the entity text to make sure it has no characters which can

be recognized as markup in any context (within the SGML reference delimiter set).

XML:

The XML specification doesn’t treat markup data as literals in an internal text

entity. For example, a reference to the following entity:

<!ENTITY example "<p>An ampersand (&#38;) may be escaped

numerically (&#38;#38;) or with a general entity

(&amp;).</p>" >

appears in a document as:

An ampersand (&) may be escaped numerically (&) or with a general entity

(&).</p>