creative autonumbering vs migration to structure – best practice?

[FieryPantone]

First admission – while I'm currently migrating a lot of content from unstructured .fm to DITA, I'm not using structured .fm to do it; all sorts of reasons.

That said, here's my current challenge. A bit of creative autonumbering plus thoughtful use of NextPgfTag made reference information like this very easy to deal with.

I have, however, no idea of which DITA tools to reach for. Specialisation + extended .xslt won't be an option, and even the thought of (mis)using tables for layout brings me out in a rash. Are there elements in the programming domain that would help? Thanks in advance for any tips.

[ScottPrentice]

I don't see anything there that would be particularly challenging to map to basic DITA elements. I'm a fan of using conversion tables, which maps FM objects (para and char tags in particular) to elements, then allows you to wrap those elements in more elements .. building up a valid structure, which you then save to XML. But I'm pretty sure you have to do this using structured FM. When in Structured mode, you can edit both structured and unstructured files, so there's really no reason not to be in that mode all the time (IMHO).

I'm assuming your "notes" and "purpose" paras are different para tags, so this overall structure would map to a <dl>. The subheads would be the <dt>, and the notes and purpose paras would map to <p> tags with the outputclass attribute set to "notes" and "purpose". These <p> tags would get wrapped in a <dd>, then the <dt><dd> pair would wrap in a <dlentry>, which in turn would be wrapped in the <dl>. That's what conversion tables do .. you start with a para to element mapping, then proceed to element wrapping until the structure is good.

There's no need to worry about specializations at this point. Figure it out using base elements, then once that works, you can consider something more specific .. but definitely not the place to start.

The basic element mapping/wrapping will work reasonably well as long as your unstructured tagging model has enough "unique" tags to provide a nice one-to-one mapping. If you overuse "body" for various situations, you may find it easier to do some retagging. Also, as you proceed in the project (tasks can be particluarly challenging), you'll find that cross-refs and images and tables (and other objects) may be trickier than you though to handle. Then, assuming you are converting FM chapter files into multiple DITA topics, you'll need some way to "shred" them into those topics. (In that process your cross-refs will likely break unless you have some automation to remap them to the new topic files.)

I offer a FM plugin that helps to automate much of these tasks. You might want to download and play with the trial of FM2DITA. Read the documentation to get a better idea of the issues you may run into. It also provides a sample conversion table that might help to get you started. Even if you don't buy it, the docs, samples, and ideas may help get you further down the road.

     http://leximation.com/tools/info/fm2dita.php

Good luck!

Scott Prentice

Leximation, Inc.

www.leximation.com

[FieryPantone]

Thanks, Scott – I was beginning to think it would make DITA-ish sense to 'shred' this content, and now you confirm that I can live with a <dl> even if that's not so specific to this sort of programming information.

Corporate policy is moving us (well, me – lone author where there should be a department of six) away from FM, but I did manage to get some training on FM2DITA eighteen months back and enjoyed it. In an ideal world …