How to convert existing FM to DITA 1.2? Any documentation?

Report · Nov 11, 2013

I watched a webinar posted on the adobe website called "How to Optimize content for smooth migration into XML/DITA" and in the conversion, it showed an element called dita (root) and elements called topic before the main content. I took a class in DITA authoring last month and we learned about elements such as reference and then refbody and concept and conbody. The class I took did not go into how to use DITA in FrameMaker which is what I need to figure out now.

I'm using FM 10. I have a conversion table that is working pretty well, however, I understand that I need to import an EDD and a template into the files I convert.

My questions are:

What template and EDD file do I use? There are so many of them in the Adobe\AdobeFrameMaker10\Structure\xml\DITA_1.2\app folder. In the DITA folder there are folders for concept, and reference and task that look correct. However, in the DITA_1.2 folder I have no idea where to start.

Is there any documentation for DITA_1.2 for FrameMaker 10? Or books or Help or anything for someone new to using DITA in FrameMaker. I looked at the FM 10 Help for DITA, but it does not really cover when you are converting existing documents, just creating new topics.

Thank you for any information you can provide.

Karene

Report · Nov 11, 2013

Hello,

Hoepfully, I understand your questions correctly. Once converted to DITA (regardless of version), each file with have a DOCTYPE. That will be the root element in the file. For example:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd"

In this file, the doctype is <task>. After DOCTYPE you have the public identifier followed by the DTD. FrameMaker uses all this info to determine what template to open the file in, what DTD to parse against, and what read/write rules file to use.

Unlike DITA 1.1, which uses one EDD and template, DITA 1.2 uses multiple template and EDDs. If you open the Application Definition file by selecting StructureTool > Edit Application Definitions, you can find the template, DTD, and r/w rules filesthat are associated with each doctype. For example:

$STRUCTDIR\xml\DITA_1.2\app\technicalContent\dtd\task.dtd

This says, the DTD for doctype <task> is, by default, here:

C:\Program Files (x86)\Adobe\AdobeFrameMaker10\Structure\xml\DITA_1.2\app\technicalContent\dtd\task.dtd

As for the template, it is here

$STRUCTDIR\xml\DITA_1.2\app\technicalContent\template\task.template.fm

C:\Program Files (x86)\Adobe\AdobeFrameMaker11\Structure\xml\DITA_1.2\app\technicalContent\template\task.template.fm

You want to get the Structured Application Developers Guide. I am not sure there is one for FM10, but the one for FM9 will work.

http://help.adobe.com/en_US/FrameMaker/9.0/StructuredDev/Structure_Dev_Guide.pdf

It's not a quick and easy learning process for developing and EDD. The out-of-the-box EDD does have a lot of formatting covered. It says in the EDD that not everything is covered. For example, I think it only has two levels of bullet <ul> and numbered lists <ol> covered.

As I mentioned FM uses multible EDDs. Each top-level EDD uses several levels of nested EDDs (text insets). It is set up in much the same way as the DTDs. It makes editing the EDDs a time-consuming process.

Hope this helps,

Stan

Report · Nov 11, 2013

Hi Karene...

To follow on to the good info provided by Stan .. I'd point out that unless you're actually using DITA 1.2 elements in your converted files (which is typically not the case), you might be better off importing the DITA 1.1 EDD and template into your structured files. The biggest change in DITA 1.2 are the referencing features (keyref, conkeyref, etc), which you're not likely to have the ability to convert directly into from unstructured FM, so there's no need to convert directly to 1.2.

I would apply your conversion table, then import the DITA 1.1 template and EDD, and complete the conversion with that. When you're done, you can always open the DITA 1.1 files with the DITA 1.2 apps and treat them as 1.2 files from there on out.

To answer your question abotu the <dita> root element .. a typical conversion from unstructured FM to DITA involves starting with a "chapter" FM file which will likely contain multiple "topics" of various types (concept, task, possibly reference). In DITA, to create a file that contains multiple topic types, you wrap them all in a <dita> element. If your file just has one "topic", you can have that topic type as the root element without the need for a <dita> element.

The biggest problem with a FM to DITA conversion is splitting up the single "chapter" file into multiple separate topic files, and getting the cross references that used to point to the heading in the chapter file to now point to the new topic file. Without some type of scripting to handle this complex "shredding and mapping", it's often best to just do this manually, and relink the cross-refs manually.

The tool used in that webinar to perform this processing is called FM2DITA, and is available here ..

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

Even if you aren't interested in buying this tool, you might consider downloading and installing it just to play with the 30-day trial. It contains some sample files that may be helpful as well as some info in the documentation that may help you on your way.

Cheers,

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

Report · Nov 11, 2013

Thank you both Stan and Scott.Your information is very helpful!

My starting document has one chapter with multiple maps. I actually split the single unstructured FM file into one file for each map which I convert to a concept topic. It would be nice to not have to split the original file up. I'll give the single file a go with the dita element now. I am still in the itterative process of creating the conversion table.

I will be using conrefs but have not created them yet so I assume I can safely use DITA 1.1 for the conversion.

I do have the Structured Application Developers Guide but it does not cover DITA in FM.

I obviously still have more experimenting and learning to do. Once I get the conversion working well, then I will copy the DITA_1.1 app as my-DITA and work on some formatting.

Thanks again for your help.