README from the FrameMaker-7.1-DocBook-XML-4.4 project
Last updated on 24 February 2008.
I tested this structured application on FrameMaker version 8.0p273. With respect to the FrameMaker bugs discussed below, there is no change compared to using any patch level of FrameMaker 7.1 or FrameMaker 7.2.
Introduction
------------
The following is a lengthy description of my experience developing
the DocBook XML version 4.4 structured FrameMaker 7.1 application this
README accompanies. It is an account of the details of my second
effort to use FrameMaker with DocBook XML.
Intended Audience
-----------------
This project is intended to help new users of structured FrameMaker with
DocBook XML. It is not intended to provide technical publications
department managers or those exploring XML "single-source" document
production solutions with a quick and easy evaluation of structured
FrameMaker. Most of the email I receive as a result of making this
structured application available comes from just such people. Thus, it is
necessary that I clearly state this: I urge those who have been tasked with
evaluating structured FrameMaker to read the documentation provided by
Adobe, create your own structured FrameMaker applications, and see for
yourself if structured FrameMaker satisfies your needs. I understand the
frustration involved with exploring new technologies; however, if you have
yet to create your first structured FrameMaker application using a complex
DTD such as DocBook, DITA, etc., please do that before sending me email
expressing your disbelief or disapproval with what I state here. That said,
I invite those with experience to suggest corrections or improvements to
either this README or the actual structured FrameMaker application.
Suggested Use
-------------
FrameMaker's XML DocBook Starter Kit provides an EDD, a rules file, and
a structapps.fm file you can experiment with, but it does not provide
any valid DocBook XML to experiment with round-tripping and it does not
provide an example of how you would create a FrameMaker book from an
imported DocBook XML book. This example project provides material where
the DocBook Starter Kit falls short. You might benefit by examining the
read/write rules, the EDD, or the structapps.fm file. You might experiment
with importing or exporting the XML. Or, you might try structured
authoring in FrameMaker using an already-defined, working, structured
DocBook XML application. I think the most benefit one can gain by
experimenting with this example project comes through seeing structured
FrameMaker's quirks and limitations with DocBook XML. In particular, it
is useful to see FrameMaker's DocBook XML import/export limitations without
a custom client other than the one provided by Adobe. It is also useful to
see how FrameMaker-generated lists don't fit in with the round-tripped XML.
To see these things, you need a FrameMaker book produced from valid DocBook
XML. That is what this example project provides. I provide in this project
all the files necessary to do these things, but I do not provide explicit
instructions on how to install, edit, or use a structured FrameMaker
application or the DocBook XML DTD. The Adobe docs, the DocBook XML docs,
and a book on FrameMaker can provide you with that information.
The FrameMaker documents in this project and the SVG graphics they
reference use system fonts that may not be available on your system,
mostly Garamond and GilSans. You may need to change the referenced
fonts to something you have, and to do that you may need a graphics
program that supports SVG. Open-source software and google may help.
Notes
-----
I've made every effort to be accurate in the notes below; however, it
is possible that anything stated below could be wrong. In fact, I've
said enough in these notes that it's likely something I said is wrong.
I can be reached at steve_142857@q.com.
1. Creating an EDD from the DocBook XML DTD.
--------------------------------------------
Creating an EDD from the DocBook XML 4.4 DTD is mostly a point and
click process, but not entirely. In the EDD FrameMaker creates, it
assigns each element a type used for FrameMaker internal purposes
(Container, Marker, etc.). It is often necessary to adjust the default
EDD FrameMaker creates. You must adjust the FrameMaker element type
for some elements. In many cases, you can imitate what is done in the
FrameMaker DocBook Starter Kit's EDD, but not always.
When validating XML within FrameMaker, FrameMaker does not adhere to
exactly the same criteria for determining validity as do most of the
usual XML tools, such as xmllint, nsgmls, etc. When FrameMaker
validates a document, it validates it in FrameMaker's own special way
against the document's EDD. Depending on the modifications you make
to an EDD, a DocBook XML document within FrameMaker may not validate
against its original DTD upon export. Thus, it is important to keep
the EDD synchronized with the original DocBook XML DTD.
1.1 Table Elements in the EDD
-----------------------------
As of version 4.3, the DocBook XML DTD supports the HTML table model
in addition to the CALS table model. FrameMaker supports only the
CALS table model. Thus, unlike when creating an EDD from the DocBook
XML DTD version 4.2, creating an EDD from DocBook XML DTD versions
4.3 and later produces the following error messages:
**********************
Element table in your DTD appears to be a non-standard table definition.
Please check the translation of this element in your EDD. In a valid
FrameMaker table, the heading must precede the body and the body must
precede the footing.
Element informaltable in your DTD appears to be a non-standard table
definition. Please check the translation of this element in your EDD.
In a valid FrameMaker table, the heading must precede the body and the
body must precede the footing.
**********************
The content model for the table element in the DocBook XML DTD for
version 4.2 is:
table ::= ((blockinfo?,(title,titleabbrev?),(indexterm)*,
textobject*,(graphic+|mediaobject+|tgroup+)))
The content model for the table element in the DocBook XML DTD for
versions 4.3 and 4.4 is:
table ::= (((blockinfo?,(title,titleabbrev?),(indexterm)*,
textobject*,(graphic+|mediaobject+|tgroup+))|
(caption,(col*|colgroup*),thead?,tfoot?,(tbody+|tr+))))
My interpretation of the above listed FrameMaker error messages
produced upon EDD generation from the DocBook XML DTD is that they
are simply stating that FrameMaker has detected DTD support for a
table model other than CALS, and that FrameMaker does not support
this additional table model. A quick check to the Structure
Application Developer's Guide validates this interpretation. From
page 39 of the FrameMaker 7.1 edition, "When you create an EDD from
a DTD, FrameMaker automatically recognizes the CALS table model and
creates elements of the appropriate type. If you have a different
table model in your DTD, you’ll need to supply rules to identify the
table structure."
It may be good to use only CALS tables in DocBook XML targeted for
import to FrameMaker. Without special read/write rules, tables that
adhere to other table models won't be automatically recognized.
1.2 Xref Elements in the EDD
----------------------------
I changed the element type for "xref" from FrameMaker element type
"Container" to FrameMaker element type "CrossReference" and deleted
the FrameMaker EDD's "General rule" for the xref element.
1.3 ParagraphFormat-Element Associations in the EDD
---------------------------------------------------
I included paragraphFormat-element associations only for those
elements the project's XML uses, which is a very small percentage of
the total elements available in the DocBook XML DTD. The DocBook XML
DTD includes more than 350 elements.
Tables. Some special mention must be made concerning table formats
in the EDD. FrameMaker does a nice job of automatically importing
DocBook XML tables that adhere to the CALS table model. FrameMaker
recognizes the DocBook XML "tgroup" element as a CALS table when
creating the EDD. Upon XML import, FrameMaker creates rudimentary
tables using very simple formatting. To associate a FrameMaker table
format with the table element in the EDD, or to create complex rules
for associating table formats with tables in the EDD, you must associate
the table format with the "tgroup" element, not the "table" element.
When FrameMaker creates the EDD from the DocBook DTD, it creates the
DocBook XML "table" element as FrameMaker "table" element of type
Container. You can't associate a table format with an element of
FrameMaker type Container. FrameMaker creates the EDD with the
"tgroup" element of FrameMaker type Table. So, that's where the table
format associations must go.
1.4 Indexterm Elements in the EDD
---------------------------------
I changed the element type for indexterm from FrameMaker element
type "Container" to FrameMaker element type "Marker" and deleted the
FrameMaker EDD's "General rule" for the indexterm element.
1.5 ValidHighestLevel in the EDD
--------------------------------
I included a FrameMaker child element "ValidHighestLevel" for the
following FrameMaker elements: book, bookinfo, toc, lot, chapter.
The "ValidHighestLevel" element is specific to FrameMaker. It is
not a DocBook XML element. FrameMaker uses it internally to designate
certain elements as being valid at the highest level within an
individual file.
1.6 Inclusions/Exclusions in the EDD
------------------------------------
FrameMaker EDDs allow a content model construct not available to XML
DTDs called "inclusions/exclusions." This construct is left over from
FrameMaker's SGML support. An "inclusion" allows a child element to
appear anywhere within a parent element, including all of the parent
element's child elements. An "exclusion" excludes an element from
appearing anywhere within some parent element, including all of that
element's child elements. I avoided inclusions/exclusions because they
would cause trouble when attempting to round-trip the XML. You should
probably do the same.
1.7 Misc. EDD Details
---------------------
I changed the default FrameMaker element type generated by FrameMaker
in the EDD and deleted the "General rule" where appropriate for the
following elements:
- "footnote" from type Container to type Footnote
- "graphic" from type Container to type Graphic
- "inlinegraphic" from type Container to type Graphic
- "imagedata" from type Container to type Graphic
DocBook XML elements "shortaffil", "jobtitle", "orgdiv", "orgname",
and "productnumber" were correctly created as FrameMaker elements of
type Container. When using FrameMaker 7.0 and DocBook 4.2, FrameMaker
incorrectly created these elements in the EDD as FrameMaker element
type Marker.
FrameMaker created the EDD with "EDD Version 7.0" at its top,
rather than the expected version of 7.1.
2.0 Importing Element Definitions to the Formatting Template
------------------------------------------------------------
Upon importing element definitions from the EDD into the formatting
template, FrameMaker presents an Element Catalog Manager Report. In
that report, it lists the following messages:
[1] Default value specified for attribute definition (sepchar) is
empty; ignoring the default value.
[2] Element (tr) referenced in the general rule for the element
(thead) has an illegal object type.
[3] Element (tr) referenced in the general rule for the element
(tfoot) has an illegal object type.
[4] Element (tr) referenced in the general rule for the element
(tbody) has an illegal object type.
[5] Element (entrytbl) referenced in the general rule for element
(row) has an illegal object type.
[6] Elements that are defined but not referenced.
seealso
see
tertiary
secondary
primary
Taking these error messages in order, I have no explanation of the
first. The DocBook XML DTD specifies a space as the default character
for the "cmdsynopsis" element's "sepchar" attribute. I know of no
reason why FrameMaker should complain about that. The second, third,
and fourth messages are almost certainly related to FrameMaker's lack
of support for the HTML table model. The fifth is on account of
FrameMaker not supporting embedded tables (a table in a table). The
sixth seems to not be a problem at all. I don't know why FrameMaker
reports this. These elements are child elements of the "indexterm"
element and seem to be working as expected in FrameMaker.
3. Creating Read/Write Rules
----------------------------
The project's rules file probably contains more of interest to you than
I discuss here. So, check that file too.
Most of the read/write rules I used came from the DocBook Starter Kit's
rules file. Rules files do not accommodate context-sensitive, fine-tuned
import/export rules. For example, an import/export rule that applies to
a "title" element applies to all "title" elements regardless of a
"title" element's parents. Thus, the rule applies equally to a "title"
element within a "table" element, a "figure" element, a "book" element,
a "chapter" element, etc. When associating paragraphFormats with elements
in the EDD, one can specify context-sensitive rules, but not in the
import/export rules file. To use context-sensitive import/export rules,
one must write a custom client using the FrameMaker Developer's Kit (FDK)
and the FrameMaker Structured API (both free downloads from Adobe).
3.1 Table Read/Write Rules
--------------------------
FrameMaker recognizes the "tgroup" element as a table conforming
with the CALS table model, not the "table" element. Thus, FrameMaker
assigns an element type of "Table" to the "tgroup" element and an
element type of "Container" to the "table" element. Here's the
read/write rule needed to apply table formats to CALS tables imported
from DocBook XML 4.4:
element "tgroup"
{
is fm table element "tgroup";
attribute "tgroupstyle" is fm property table format;
}
In the import XML, you assign a string value representing a
pre-defined FrameMaker table format to the "tgroup" element's
"tgroupstyle" attribute . FrameMaker then automatically applies the
table format upon XML import.
3.2 Graphics Read/Write Rules
-----------------------------
Sizing graphics in DocBook XML is done fairly easily with a few
attributes on "imagedata" elements. In FrameMaker, sizing graphics
is slightly more difficult and requires that you use some unused
"imagedata" element attributes to map values to FrameMaker property
values for elements of FrameMaker type "Graphic". The solution I chose
abuses the "role" attribute by changing its semantics. I map the "role"
attribute's string value to the FrameMaker "Graphic" element type's
property value for "import size". But it is also necessary to specify
whether the anchored frame FrameMaker creates for imported graphics
should be cropped. Here's the read/write rule for the "imagedata"
element in the project's rules file:
element "imagedata"
{
is fm graphic element "imagedata";
notation attribute "align"
{
is fm property alignment;
value "left" is fm property value align left;
value "center" is fm property value align center;
value "right" is fm property value align right;
}
attribute "fileref" is fm property file;
attribute "entityref"
{
is fm property entity;
is fm attribute;
}
attribute "width" is fm property width;
attribute "depth" is fm property height;
attribute "role" is fm property import size;
attribute "condition" is fm property cropped;
}
Consult the rules file for comments and explanations. The above
read/write rule, along with the EDD specifications for a DocBook XML
"imagedata" element and appropriate attribute values in the import
XML will get you automatically sized and positioned graphics upon
XML import
3.3 Cross Reference Read/Write Rules
------------------------------------
DocBook XML xref elements in this project's import XML use the
"role" attribute to specify the name of the FrameMaker cross reference
format to use. The linkend attribute defines the element to which the
xref refers. The rule is:
element "xref"
{
is fm cross-reference element "xref";
attribute "role" is fm property cross-reference format;
attribute "linkend" is fm property cross-reference id;
}
3.4 Public and System Identifiers
----------------------------------
The rules file contains the following valid rule, which FrameMaker
completely ignores:
writer external dtd is public "-//OASIS//DTD DocBook XML V4.4//EN"
"/usr/share/xml/docbook/xml-dtd-4.4/docbookx.dtd";
Not only does FrameMaker ignore this rule, FrameMaker incorrectly
reaches into the structapps.fm file and substitutes the Public and
System ID for a completely separate structured application. On my
system, FrameMaker writes out the following as the exported XML's
Public and System ID:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"/usr/share/docbook-xml42/docbookx.dtd">
If you check the structapps.fm file provided with this project, you
will see that, although a Public and System ID is specified for this
project, the above is the Public and System ID listed for a completely
different structured application.
4. Importing DocBook XML into FrameMaker
----------------------------------------
The XML is valid before import according to xmllint, the EDD is valid
according to FrameMaker, the rules file is valid according to FrameMaker,
and the template is as valid as an unstructured template can be. But
still, FrameMaker 7.1 creates invalid XML out of valid XML. Specifically,
upon XML import, FrameMaker:
- adds an SGML syntax "Mark" attribute with a value of "ndash" to the
"itemizedlist" element in chapter4.fm whose first "listitem" element
value is "Installation setup". The valid XML "itemizedlist" element
properly contains a "mark" attribute with a value of "ndash".
FrameMaker adds the extra "Mark" attribute to the XML upon import.
The EDD FrameMaker creates from the DocBook XML 4.4 DTD does not
specify any "Mark" attribute; however, it does properly specify a
"mark" attribute.
- same problem as listed above, but this time FrameMaker commits this
error seven times in the itemized lists in chapter5.fm. FrameMaker
consistently creates invalid XML from valid XML in this way every
time it encounters an "itemizedlist" element embedded in an
"itemizedlist" element. This construct of a list in a list is quite
common. FrameMaker's error here is quite egregious. It makes the XML
invalid both against the EDD and the DTD and destroys automatic
formatting of embedded lists upon import. Watch for this FrameMaker
error with DocBook XML. Expect it. It's consistent.
- duplicates all "xref" element "linkend" attribute values as "endterm"
attribute values. FrameMaker does this upon XML import even though
the read/write rules do not include this instruction, even when
the "xref" element's "endterm" attribute is removed from the EDD,
and even though the custom client does not manipulate "xref" element
"endterm" attributes or attribute values.
5. Formatting and Authoring DocBook XML in FrameMaker
-----------------------------------------------------
Formatting can be applied in different ways. Elements can be associated
with FrameMaker paragraph formats in the EDD; elements can inherit
formatting from parent elements (specified with complex rules in the
EDD); elements can be individually formatted manually in FrameMaker;
any mix of the preceding can be used. As much as possible, I applied
all formatting through element-paragraphFormat associations in the EDD.
The actual paragraph formats are defined in a template file specified
in the application definition in the structapps.fm file.
5.1 Applying Formats
--------------------
At first, I thought it was necessary to re-import the XML and wait for
FrameMaker to convert the XML to a FrameMaker document (actually a
group of documents constituting a FrameMaker book) every time I wanted
to see the affect of changes to element-paragraphFormat associations
defined in the EDD, but that is not necessary. Thanks to Dave Nillson
for pointing this out to me on the xml-doc@yahoogroups.com mailing
list. I had simply forgotten that FrameMaker books make this procedure
possible. After making changes in a structured application's EDD or
formatting template, to propagate the changes across all files in a
book, do this:
1) Open the EDD or formatting template that contains the changes.
2) Open the book file.
3) Select all the files in the book.
4) With the book file active, open the import dialog box
(File>Import>Element Definitions).
5) Make sure you've selected the correct file in the drop-down menu,
the EDD to import element definitions, the formatting template
to import paragraph formats.
6) Click "Import". Frame then opens and closes every file in the
book, one by one, importing the element definitions or paragraph
formats into each one.
5.2 Generating Lists
--------------------
Generated lists are not automatically created upon DocBook XML import.
Creating them takes a bit of time and is done in the usual FrameMaker
way. Upon exporting the XML, FrameMaker creates a file for each of the
book's generated lists. These files are produced from unstructured data
and have no counterpart in the originally imported XML. I just deleted
them.
5.3 Creating FrameMaker Books
-----------------------------
For each main component in a DocBook XML book, such as "chapter"
elements, the FrameMaker EDD allows one to specify a child element
"ValidatHighestLevel". Upon import of DocBook XML, each DocBook
element corresponding with an EDD element that has a
"ValidatHighestLevel" child element becomes a separate file in the
FrameMaker book. FrameMaker converts each element and all of that
element's child elements into a single FrameMaker file. DocBook "toc"
elements, "index" elements, and other DocBook elements that correspond
to FrameMaker generated lists can be created as separate files, but
those files cannot be used as FrameMaker generated lists. So, there
is no good reason to make them "ValidatHighestLevel". FrameMaker
TOCs, Indexes, etc., must be generated manually in the usual FrameMaker
way. If for some reason one needs to re-import the XML, perhaps because
it has been updated, the procedure for re-importing XML while retaining
a book's generated lists goes something like this:
1) Open the book file and note the book's component files.
2) Close the book file.
3) Delete from the file system the book's non-generated-list files.
Do not delete from the file system the files containing the TOC,
LOT, etc.
4) Select File > Open and choose the XML file you wish to import.
5) Select a structured application from the Use Structured Application
dialog.
6) FrameMaker starts to create a new book. Give the new book some name
other than the name of the original book.
7) After giving the new book a name, FrameMaker automatically converts
the XML to one or more FrameMaker files using the structured
application you selected. FrameMaker names each newly converted
file the same as it did when creating the original book.
8) Delete the book file FrameMaker just created. Do not delete the
original book file.
9) Open the original book file. All the generated lists are as they
were and the book file now references the newly imported XML
converted to FrameMaker's format. You have re-imported the XML
without needing to re-create any of the generated lists. Of course,
you may now want to re-generate the lists to reflect changes in the
re-imported XML.
5.4 Adding new Cross References
-------------------------------
Given implementation of the EDD adjustments and read/writes rules
described previously, DocBook XML xrefs import correctly, work as
expected in FrameMaker using ctrl+alt+click, and work as expected
in the final PDF. All this without using FrameMaker 7.1's new
"srcfile" attribute. However, once the XML is imported, any attempt
to include additional "xref" elements does not work as expected. An
"xref" element can be inserted easily enough. But attempting to
enter a value for the required "linkend" attribute in the series
of dialog boxes FrameMaker presents results in FrameMaker incorrectly
assigning the value entered to the "xref" element's "endterm"
attribute. The xref element's "endterm" attribute is optional, but
its "linkend" attribute is not. Consequently, the XML becomes invalid.
Repeated attempts to correct the problem by assigning a value to an
"xref" element's "linkend" attribute always result in the value being
incorrectly assigned to the "xref" element's "endterm" element. The
new cross-references work as expected, but the XML becomes invalid.
5.5 Regarding Seemingly Random Carriage Returns Placed in the Formatted
Output by FrameMaker
-----------------------------------------------------------------------
Some of these unwanted carriage returns accompany FrameMaker markers
of type "DOC PI" with content "pagebreak". FrameMaker creates these
markers from the import XML's "pagebreak" processing instructions.
These processing instructions are necessary when using FOP
(version 0.20.5) because FOP does not yet support the various
"keep-with" XSL options. If FrameMaker were to create these markers
without creating the carriage returns, that would be better. The cost
of dropping them upon XML import is that they are unavailable to be
included in output XML when round tripping. Since a good argument can
be made that "pagebreak" processing instructions shouldn't be in the
input XML to begin with, I chose to drop them upon XML import. An
alternative would be to import them to some other marker type that
does not create the carriage return, and then include them in exported
XML. However, FrameMaker sometimes creates unwanted carriage returns
for other types of markers too. For example, FrameMaker creates a
carriage return when it encounters "indexterm" elements within a
"para" element but following an "itemizedlist" element. This
parent-child element relationship is valid DocBook XML and is quite
common. Formatting the XML with DocBook XSL, xsltproc, and FOP does
not make the same error. In many other cases, FrameMaker creates
unwanted carriage returns when it encounters "indexterm" elements,
such as when the indexterm is at the end of a list, at the end of
a "para" element, etc. But then there are even more unwanted carriage
returns FrameMaker generates in other situations. For example,
FrameMaker creates a carriage return after nearly every "itemizedlist"
element, but not all. I believe these are all FrameMaker bugs, but I
could be wrong. These unwanted carriage returns may be caused by
something I'm doing, perhaps something that has escaped me in the
formatting template's paragraph formats. Note though, the same XML
does not create the unwanted carriage returns when formatting with
DocBook XSL, xsltproc, and FOP.
6. Exporting DocBook XML from FrameMaker
----------------------------------------
- FrameMaker attempts to output its generated lists into the XML tree.
The book component files for generated lists (TOC, LOT, LOF, Index)
contain unstructured data that does not belong in the XML tree.
While FrameMaker attempts to export the generated lists' unstructured
data, FrameMaker also tries to validate the unstructured data
against either the actual DocBook XML 4.4 DTD or its own EDD. I'm
not sure which. Either way, FrameMaker creates a mess of the
exported XML tree. While FrameMaker outputs the XML, it issues
literally hundreds of error messages in the "Save as XML" log it
presents, so many that it eventually states "Number of messages has
exceeded the maximum. Processing of this document or book component
will proceed without additional messages." So, FrameMaker commits
some errors, tells you about them, and eventually says "I've got so
many error conditions right now I'm not even going to tell you about
them anymore." Perhaps I should be using a read/write rule or a
custom client to force FrameMaker to not export the unstructured
generated lists' data into the XML tree. I think FrameMaker should be
smart enough to identify its own generated lists and not export them
into the output XML. Obviously, part of the post-processing before
validation of the exported XML must include removing the unstructured
data from the XML tree.
- On my system, FrameMaker writes the exported XML document's Public
ID and System ID using values not connected with this structured
application, but rather with a different structured application
(a DocBook XML 4.2 structured application on this machine). FrameMaker
must be misreading the structapps.fm file, finding the other structured
application's rules file, and using that rules file's "writer external
dtd is public" rule. However, FrameMaker is using the correct rules
file for everything else. This is a bizarre error. Before attempting
to validate the exported XML, it is necessary to specify the correct
Public Identifier and System Identifier for the DocBook XML 4.4 DTD.
- Even if you prevent the unstructured generated list data from being
exported into the output XML tree, FrameMaker still issues hundreds
of error messages upon export, at least one for every "indexterm"
element used in the XML. This is another case in which FrameMaker
commits some errors and then tells you about them. Specifically,
FrameMaker prematurely closes all opening "indexterm" element tags as
if they were empty elements in SGML. This is a well-known structured
FrameMaker XML error. To correct it you must change in the exported
XML all "<indexterm/>" occurrences to "<indexterm>". This
issue has been discussed at length on the various Internet mailing
lists for XML and/or structured FrameMaker. It's a FrameMaker bug,
and it's not caused by any code in the custom client Adobe ships with
its DocBook Starter Kit, so don't try to correct it there. Rather, to
solve this problem, you must write code in a custom client to override
FrameMaker's default buggy behavior. Or, you can post-process the XML
after export from FrameMaker using some text manipulation tool such
as Perl. I chose to simply use search and replace in GNU Emacs.
- FrameMaker inserts many processing instructions in the output XML
for its own use in expectation that the XML will be going back into
FrameMaker.
- FrameMaker duplicates all values for "xref" element "linkend"
attributes as values for "endterm" attributes. By experimentation,
I discovered that FrameMaker does this even if the "endterm"
attribute is removed from the EDD, even if all mention of an
"endterm" attribute is removed from the read/write rules file, even
though the code for the custom client does nothing with any "endterm"
attribute, even when the import XML contains no values for any
"endterm" attribute, and even when all these things are true at once.
Alistair Christie explains a solution he uses to overcome FrameMaker's
difficulties with DocBook XML "xref" elements at:
http://www.itauthor.com/authtools/framemaker/FMexternalXrefs
It involves using the new "srcfile" attribute Adobe provides in
FrameMaker 7.1. DocBook XML does not include a "srcfile" attribute
for the "xref" element, so using it requires overcoming some
import/export validity problems it introduces, which would be true
with any DTD, not just DocBook XML. It seems the import/export
validity problems the "srcfile" attribute introduces could be
easily overcome with read/write rules. Unfortunately, Adobe provides
no means for modifying the "srcfile" attribute. On page 322 of the
FrameMaker Structure Application Developer's Guide, it states about
the "srcfile" attribute: "This attribute is used for external
cross-references and cannot be modified by read/write rules."
Regardless, Alistair Christie's solution may help, and the Structure
Application Developer's Guide contains more information on the new
"srcfile" attribute.
- Once I made the necessary adjustments to the XML output by
FrameMaker, I validated it with xmllint and ran it through xsltproc
using the DocBook XSL stylesheets. The result included a surprise
that did not happen before round-tripping through FrameMaker. Xsltproc
starts as usual, but then issues "removing id" messages for about
fifteen minutes and consumes about 175 MB RAM and all the CPU cycles
my system can feed it. Xsltproc then seg faults and dumps core.
Nonetheless, xsltproc produces an FO file that FOP successfully
processes. The resultant PDF is almost the same as the one produced
prior to sending the XML through FrameMaker, but contains some
glitches and errors that did not exist previously. So, can FrameMaker
round-trip DocBook XML? Yes, and No, depending on your prejudices and
and the amount of intervention you allow on the "yes" side. The
fairest answer would be something like: "No, not without significant
intervention." In fact, if your DocBook XML uses an "itemizedlist"
element within an "itemizedlist" element (a list in a list),
FrameMaker creates invalid XML from valid XML, and that XML is invalid
both with respect to the DocBook XML 4.4 DTD and the EDD FrameMaker
creates from that DTD.
Upon XML export:
1) Lots of fairly ordinary ascii characters are changed to internal
general entities (such as hyphens, etc.).
2) "imagedata" element "fileref" attributes became external parameter
entities
3) Each structured file in the FrameMaker book became an external
file referenced by an external parameter entity, but so did the
unstructured files (TOC, LOF, LOT, and Index). The unstructured
files had to be removed from the exported XML tree before
validating.
4) Many (all?) default attribute values not explicit in the input
XML were made explicit in the output XML.
<rant>
I suppose all import/export behavior could be changed with a
"custom client," but that is like selling someone a piece of software
as "able to do _anything_ you want," and adding "you just have to do
some programming." What is this fabulous piece of software that is so
versatile it can do anything I want? Well, of course, it's a compiler!
</rant>
7. Miscellaneous
----------------
Custom clients. Not all of FrameMaker's XML import/export behavior can
be controlled with just a rules file. I inspected some of the code Adobe
provides in the DocBook XML Starter Kit's custom client and recompiled
it. Adobe provides a Visual Studio project and workspace files along
with the source code for the Starter Kit custom client. All I had to do
to get it to compile was include project/workspace paths to the FDK
header files and struct.lib. Using an Intel 7 compiler, the resultant
file, docbook.dll, was about %60 the size of the docbook.dll file
shipped with FrameMaker 7.1. Each source file contains a big,
restrictive copyright statement at its top. As for the code, it's not
easy for me to follow. The FrameMaker Developer Kit (FDK) uses an
abstraction layer wherein the usual data types (int, etc.) are
redefined and renamed. I expect this helps Adobe to use a single code
base for FrameMaker while allowing the code to compile on multiple
platforms. For me, it just made understanding or modifying the custom
client's code more difficult. However, note, this is not something that
would trouble an experienced, competent C programmer.
Element order. Without the correct code in a custom client, the order
in which the elements occur in the XML is the order in which they appear
in the formatted FrameMaker document. For example, to get a DocBook XML
figure title to appear below the figure in a formatted, structured
FrameMaker document requires programming a custom client using the FDK
and the FrameMaker Structure Import/Export API. All the necessary
documentation is downloadable from the Adobe web site, literally
thousands of pages.
Hiding element text. I didn't hide any element text in this project, but
to do so you would declare the elements in the EDD as FrameMaker
"Marker" elements of type "CustomMarker". Then you would leave the
"CustomMarker" name blank in the EDD. It's a kludge, but it works.
8. Performance
--------------
More than any other application I've ever run on this machine,
FrameMaker's performance degrades when I activate a very high number
of PostScript fonts. When using mostly True Type and Open Type fonts
along with a handful of PostScript fonts, FrameMaker runs OK. When
scrolling, FrameMaker slows when it reaches an SVG graphic, but not
too badly. That's to be expected. However, when using a very high
number of PostScript fonts made active within Windows 2000,
FrameMaker 7.1's performance deteriorates significantly.
Originally, I used FrameMaker 7.0 under Windows 2000 Server. Because
that system had so many PostScript fonts activated, performance was
horrendous. Here are those mostly original comments:
**************************
I'm running FrameMaker 7.0 on an IBM IntelliStation, dual CPUs at
733MHz, 1GB of PC 800 RDRAM, 15K SCSI, with a 32MB Nvidia card. The
machine is running Windows 2000 Server with all the patches and
updates. FrameMaker 5.5.6 runs very nicely on this machine, as does
every program I have ever run on it. Nothing has ever bogged down,
except FrameMaker 7.0. Previous FrameMaker versions do not support
XML, and FrameMaker 7.0 is so slow on this machine it is nearly
unusable. Virtually any action in FrameMaker 7.0 uses %50 of the
maximum CPU cycles this machine can provide. Task Manager shows
FrameMaker using both CPUs [I think this is incorrect now], and
performance does get a little better if I shut down every other
program. But even then, FrameMaker 7.0's performance is very bad. How
bad? It is not uncommon for FrameMaker 7.0 to suck up %50 of max CPU
for 30 to 60 seconds in response to just switching between two open
documents inside FrameMaker. Even with FrameMaker the only program
running, and with only one FrameMaker file open, it still takes about
3 to 5 seconds to iconify or display an already opened file. Like I
said, nearly unusable. I watched a lot of TV while waiting. Additional
information: Microsoft's multi-part security fix issued on
14 April 2004 seems to have fixed some of the performance problems I
was experiencing with FrameMaker 7.0, which indicates that the
performance problems may not be wholly attributable to FrameMaker.
However, performance is still very bad. I am now wondering if
FrameMaker's astoundingly bad performance on this machine is caused
by using a server operating system (Windows 2000 Server) and by
having installed a very high number of fonts. However, if that is the
case, then why are there no performance problems with any other
applications? Time permitting, I'll investigate this further.
**************************
Now I know I can attribute FrameMaker's bad performance to the very
high number of PostScript fonts; however, I saw no other application's
performance similarly degrade. Thus, the question as to why FrameMaker
suffers an extreme performance hit under such circumstances is still
open, and it can't be ignored that FrameMaker seems to suffer
singularly in this respect.