RE: [docbook-apps] Framemaker to DocBook conversion

["Steve Blair" <sblair@vocera.com>]

We successfully converted seven unstructured FM books to DocBook at the beginning of this year. We used a conversion table, as Frame recommends, to map FM styles to DocBook tags. The basic idea is fairly simple--it's a lot like other third party FM conversions (WebWorks, for example). The devil's in the details, of course.

Take your best guess at the conversion table, pick a single FM source file that is representative of some of your most complex formatting, and then convert it. Look at the resulting DocBook source for problems, tweak the conversion table, and convert the file again. Go through as many iterations as you need until you get a fairly clean conversion.

Since we had only seven books, we reached the point of diminishing returns fairly quickly. That is, you can continue to tweak the conversion table over and over again, but at a certain point you look at the resulting DocBook source and realize that it is going to be faster to clean it up than to continue working on the conversion table.

I created a checklist of the remaining problems in the DocBook output, then wrote regular expressions to fix all of them directly in the XML source. We used a text editor with search/replace across multiple files to fix the output, but a Perl script would work also. As with the conversion table itself, the degree of automation you need depends upon the number and length of books you have to convert.

It took two of us about three months to convert our seven books, but we were only working on it about 1/3 time. We spent more time creating XSL style sheets to format the cleaned-up XML so we could see what it looked like. We found numerous bugs in the way we chose to apply DocBook tags in the XML (because we were novices), that were only apparent when we looked at the formatted output. So make sure you also allow time to re-tag your DocBook output, even after you think you're done. ;-)

Finally, make sure you go through your DocBook output fairly closely to find things that didn't convert at all. We found that when the FM conversion table encountered FM markup it didn't know how to convert, it skipped it--we had holes in our output that we had to find manually. There were not many holes, and they were not large, but it may have actually been worse that way, because we had to scrutinize the docs paragraph-by-paragraph.

HTH,

Steve Blair
Director of Technical Publications
Vocera Communications
sblair@vocera.com

-----Original Message-----
From: Camille Bégnis [mailto:camille@neodoc.biz] 
Sent: Wednesday, October 25, 2006 3:51 AM
To: apps docbook
Subject: [docbook-apps] Framemaker to DocBook conversion

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi all,

I've been crawling archives and websites, found 2 threads dating back from 1999 and 2005, but nothing definitive. FM hacking looks not quite appealing.

We have to migrate FM docs to DocBook, and using intermediate formats like HTML or RTF give quite poor results.

Looking at the XML output from FM, it looks quite decent, the hierarchical structure could even be reconstructed with a bit of XSL neurons burning I believe.

So did someone found a reliable FM -> DocBook conversion method?

Thanks for your help,

Camille.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: Using GnuPG with Mandriva - http://enigmail.mozdev.org

iD8DBQFFP0Gnjv9P65BfOUMRAmH5AJ9E8b6/MLTBE96yj5/xblHd/TagVwCfaYAc
zcXYh8ptezlHVBb8F5JfrZA=
=kk0M
-----END PGP SIGNATURE-----