Re: DOCBOOK-APPS: Experience with Framemaker 7.o anyone?

[Bob Stayton <bobs@caldera.com>]

On Tue, Jun 18, 2002 at 11:33:43AM +0200, Doc Team Lingua Tedesca2 wrote:
> 
>         Hello docbook-apps,
>         
>         since  the new Framemaker 7.o is supposed to import and export
>         XML,  and  is  even  said  to  ship  with  DocBook stylesheets
>         included, my question is:
> 
>         Has  anybody  yet  any  experience with this version? Does FM7
>         stands up to the promise to edit DocBook?

The new FrameMaker can indeed open DocBook 4.1.2 XML
documents, and save to DocBook 4.1.2 XML.  That is a big
improvement over Frame+SGML 6, which would crash when
trying to do so.

However, I can't say I would recommend FM7 as an XML
*editor* for DocBook yet, because the round trip experience
is not what you would expect.  I'm investigating using it
as a final format engine for PDF or print output, where
it only imports the final XML for printing.

When FrameMaker "opens" an XML document, it actually runs a
conversion process that maps DocBook XML elements to
FrameMaker structured document elements.  You then have a
FrameMaker structured document (.fm file) that closely
parallels your original XML file.  But it is not your
original XML file.  When you do Save As XML, it runs
another conversion process in the other direction to
generate an XML file from the structured FrameMaker
document.  Needless to say, the generated XML file is
similar but not identical to your original.

The conversion is handled by a set of FrameMaker read/write
rules, and some compiled C code written using the
FrameMaker API.  The quality of the round trip conversion
therefore depends on these rules, and I have to say that
they are not yet complete for the DocBook application
included with FrameMaker 7.

I did a test by opening a Docbook chapter file and
immediately doing Save As XML to another filename,
to compare the results.
This revealed a number of issues:

1.  The DOCTYPE declaration is changed from one with
a PUBLIC identifier to one with a SYSTEM identifier,
pointing to the FrameMaker copy of the DocBook DTD.
The PUBLIC identifier is lost.

2.  Default attributes are actually filled in on every
element that has them.  So every <filename> becomes
<filename moreinfo="none">, etc.  It's certainly valid, but
mostly a lot of clutter since the DTD provides the same
information.

3.  Many ASCII characters are inexplicably converted to
character entities.  "C++" becomes "C&plus;&plus;", and
http://localhost becomes "http:&sol;&sol;localhost".

4.  When Saving As XML, I got a long error report
about the xml:space attribute not being declared
for <literallayout> and other elements.  Turns out
that the export rules add that attribute.  It appears
the left hand is complaining about the right hand.

5.  My <ulink> elements inside my <literallayout>
elements disappeared.  

6.  Blank lines at the end of a <literallayout>
or <programlisting> disappeared.


I suspect that most of these problems can be solved
by working with the read/write rules or writing to
the Frame API.  But don't expect to just use it
out of the box for round trip DocBook XML editing.

I think Adobe expects you to create your own application
using their product as a toolkit.  They seem to have
provided a sample DocBook application as a starting point,
not a finished point.

If you decide to use FM7 as a formatting engine for DocBook
XML, you'll still need to work with the FrameMaker XML
application files if you want to alter the format.  In
structured FrameMaker, formatting styles can be defined in
either the traditional Frame style tags, or as format rules
in the EDD.  In the sample DocBook application, most of the
element formats are defined in the EDD.  So you can't just
use the style dialog boxes to change your template, you
have to learn the EDD formatting rules.  Be sure to
print out the 562 page "Structure Application Developer's
Guide Online Manual" (PDF) provided with the product.

BTW, I have no affiliation with Adobe, I'm just trying to
use their product.
  
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com