Re: Illustrations in FrameMaker+SGML

[Dan Emory <danemory@xxxxxxxxxxxx>]

At 03:49 PM 11/28/01 -0800, Simon Bate wrote:
>Over the years, we've become quite comfortable with building illustrations
>in plain ol' FrameMaker.  We have many illustrations that contain one or
>more screenshots (imported by reference), callouts in text frames, and
>leader lines from the callouts to the areas of the screenshot to which they
>refer.
>
>We're now investigating FrameMaker+SGML, but I notice that the
>FrameMaker+SGML documentation says "for best results put only one graphic in
>each (anchored) frame." The doc goes on to say that text in a frame is not
>maintained as part of a document's structure.  Thus I presume, the text
>doesn't get exported to SGML.

The statement is correct as far as it goes, but that doesn't mean that such 
text (as well as other graphic objects you add with the Graphic Tool) don't 
get exported. Let's say, for instance, you have imported graphic XYZ by 
reference into an anchored frame, and then use the FrameMaker graphic tool 
to add objects (e.g., leader lines, test frames) that are all within the 
same anchored frame as the imported graphic. This, in FM+SGML parlance, 
becomes a multi-faceted graphic. Following the creation of such a 
multi-faceted graphic, the next time thereafter that you export the 
document to SGML, FM+SGML will write out a new graphic which is a composite 
of the imported graphic and the objects you created with the Graphic tool. 
This action converts the multi-faceted graphic to a single-faceted graphic 
file that is in the graphic format you specify in a read/write rule.

Here is the relevant extract from the FM+SGML Developer's Guide:
-================================================
For example, assume you use the Graphic element for all graphic elements. 
If the graphic contains any single facet, you assume the graphic was 
imported as an entity and you want the default behavior. However, if the 
author used FrameMaker+SGML graphic tools to create the objects in the 
graphic element, and you want the file written in QuickDraw PICT format.
To accomplish all this, you would use this read/write rule:

element "graphic" {
is fm graphic element;
writer anchored frame export to file "$(entity).pic" as
"PICT";
}
========================================================
Of course, if you prefer instead of PICT to write out the new graphic in 
some other format supported by FM+SGML, the read/write rule above would be 
modified to specify that format, and the corresponding filename extension. 
Note however, that this read/write rule will be used for exporting 
multi-faceted graphics to SGML from ALL FM+SGML documents which use the 
SGML application definition where that read/write rule is included. 
Remember this, because it is important.

The result of this rule is that, on export to SGML, an entity declaration 
for the new graphic will be written out in the internal DTD subset of the 
SGML document instance, and the entity name in that entity declaration will 
be written into the entity attribute of the exported SGML graphic element 
instance. You may find that some graphic formats are better than others in 
replicating, with minimal degradation, the original graphic. You may have 
to experiment by trying several different formats in order to determine 
which format is the best one to use for exporting such multi-faceted 
graphics. Remember, however, that the graphic format you finally decide to 
use in that read/write rule will be used to write out on export ALL 
multi-faceted graphics in ALL FM+SGML documents that use the SGML 
application definition in which that read/write rule is specified.

Now, let's examine some of the effects, most of them bad, of this approach:

EFFECT 1. Once you export a multi-facet graphic to SGML, the graphic that 
you originally imported by reference into FM+SGML still exists in the 
FM+SGML document, but, in the exported SGML document instance, it is 
replaced by a new graphic file that was produced by FM+SGML according to 
the above read/write rule. But let's assume that the original graphic 
subsequently gets updated. For example, suppose the original graphic is a 
screenshot of a dialog box in some software program being documented. Each 
time that dialog box gets changed, you must create a new screen shot and 
save it out under the same filename as the original screenshot. (i.e., you 
overwrite the old version with the new version in the same file. Now, the 
next time you open the FM+SGML document, the new version of the graphic 
will be imported by reference. The difference may be subtle, and it may not 
be apparent that there has been a change (you get no warning from 
FrameMaker that the graphic has changed).

To understand the implications of this, go to EFFECT 2 below.

EFFECT 21: Each time you execute an export to SGML action, all multi-facet 
graphics must be written out again, regardless of whether or not they have 
changed since the last SGML export.

Now, go to EFFECT 3 to understand the implications of this.

EFFECT 3. In the original version of FM+SGML, you had access to the entity 
attribute in the graphic element. Thus, you had the option of assigning an 
unique value to the entity attribute in each graphic element, and a 
read/write rule was provided in that initial version of FM+SGML which 
assured that each time a multi-facet graphic was written out on export to 
SGML, it would be written out to the same graphic file, overwriting the 
previous version. In later versions (beginning with V5.5) Adobe, for some 
inexplicable reason, removed that capability. That is, you are denied 
access to the entity attribute. This leaves you with two options:

    OPTION 1. Specify in the read/write rule that the graphic filename will 
have, as its stemname, the name of the FM+SGML graphic element, followed by 
an unique number assigned by FM+SGML identifying the particular graphic. 
That stemname also becomes the value of the entity attribute in the 
exported graphic element instance

    OPTION 2. Specify in the read/write rule that the graphic filename will 
have, as its stemname, the name of the FM+SGML graphic element, followed by 
an unique number assigned by FM+SGML identifying the particular graphic. 
That stemname also becomes the value of the entity attribute in the 
exported graphic element instance.

Now, go to EFFECT 4 to see what this means.

EFFECT 4. Each time you export an FM+SGML document to SGML, FM+SGML looks 
in the target directory where exported graphics are written out (by 
default, this is the same directory that contains the FM+SGML document 
instance). Let's say you have an FM+SGML document in which there are 5 
multi-faceted graphics which must be written out each time you export to 
SGML, and that the read/write rule specifies that each graphic filename 
will consist of the graphic element name (let's say the name of the graphic 
element is "Graphic"), followed by an FM+SGML-assigned unique number. So 
the first time you export to SGML there are no graphic files having a 
stemname of GraphixNN (where NN is an unique number assigned by FM+SGML). 
Consequently, FM+SGML will write out the 5 graphics with filenames 
Gaphic1.eee thru Graphic2.eee (where eee is the extension that identifies 
the graphic format specified in the read/write rule. But then, the second 
time you export to SGML, FM+SGML recognizes that stemnames Graphic1 thru 
Graphic5 are already taken, so this time FM+SGML will write out the same 5 
graphics (whether or not they've changed since the last SGML export action) 
with new filenames Graphic6.eee thru Graphic10.eee.. Thus, the 
corresponding entity names (written into the entity attribute of the 
Graphic element for each of those  5 exported graphics) will change to 
Graphic5 thru Graphic10, and those same new names will appear in the new 
entity declarations written into the SGML instance's internal DTD subset.

Now, go to EFFECT 5 to understand the implications

EFFECT 5. Each time you export to SGML, the old exported graphic files 
don't get overwritten. They remain in the target directory where those 
graphics are being written out. Multiple export actions for a document with 
many multi-faceted graphics that must be written out each time you export 
to SGML will quickly fill the directory with old versions of the graphics, 
which are no longer valid. The obvious answer is to wipe out all the old 
graphics before each new export action. But suppose (as will normally be 
the case) that there are multiple FM+SGML document files (all using the 
same SGML application definition) that all use the same target directory 
for writing out multi-faceted graphics? If some or all of those files have 
multi-faceted graphics which must be written out each time an export to 
SGML action is performed, they will all use the same read/write rule, thus 
all the graphics for all of those FM+SGML files will have filenames of the 
form GraphicNN.eee.

How, then do you determine which ones should be deleted and which ones must 
be retained? The answer is you can't if Option 1 (under EFFECT 3, in which 
the graphic element name is used in the stemname for exported graphic 
files). Instead, ALWAYS use Option 2 under EFFECT 3 (stemname of the 
FM+SGML document file is used in the stemname for exported graphic files). 
This, at least, will let you determine which graphics to delete (i.e., all 
of the graphics having filenames whose stemname includes the stemname of 
the FM+SGML document file which is to be re-exported to SGML.. Even though 
Option 2 provides a way out of the dilemma, it is still inferior to the 
method that was available in the original version of FM+SGML (see EFFECT 3 
above). When I discovered that this original capability had been removed 
from V5.5, I yelled long and loud at Adobe, to no avail. They just didn't 
seem to get it. They should have at least added the kind of explanation 
I've given above to the Developer's Guide so that everyone would understand 
what had to be done, and they should have never provided Option 1, which is 
a deathtrap.

====================
| Nullius in Verba |
====================
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory@primenet.com
177 Riverside Ave., STE F, #1151, Newport Beach, CA 92663


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **