RE: [docbook-apps] Framemaker to DocBook conversion

["Peter Ring" <PRI@magnus.dk>]

Steve's experience stress the importance of knowing the target format and having some means of testing how the conversions deviates from the intended result.

If the unstructured FrameMaker documents are already consistently marked up, I'd suggest:
- Be prepared for a learning experience
- Create DocBook representations by hand of some representative documents, so that you test the quality of your conversion process
- Set up logistics so that you can track versions of documents as well as issues and progress in conversion quality
- Rely on on FrameMaker conversion tables to do the grunt work, and fix up the result with whatever means you are comfortable with
- Clean up the unstructured FrameMaker documents to facilitate conversion.

If the unstructured FrameMaker documents are a mess, you could give CambridgeDocs a try. CambridgeDocs rely on the visual formatting to infer the structure of the document.

If the unstructured FrameMaker documents rely on deep mojo and dirty tricks, avoid doing the conversion, or simplify the documents before conversion.

Kind regards
Peter Ring

> -----Original Message-----
> From: Steve Blair [mailto:sblair@vocera.com]
> Sent: 25. oktober 2006 21:31
> To: Camille Bégnis; apps docbook
> Subject: RE: [docbook-apps] Framemaker to DocBook conversion
> 
> 
> 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-----
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: 
> docbook-apps-help@lists.oasis-open.org
> 
>