Best XML output Instruction Manual

Report · May 18, 2009

Fellow forum members,

Can anyone point me to the best instruction manual Adobe has to offer that would show me how to convert Framemaker Documents to XML format. I need a manual that will be written for a newbie as it relates to the process of outputting a Framemaker Structured document to XML tagged data. I am using FrameMaker Version 8. Any help will be greatly appreciated.

Thanks.

Report · May 19, 2009

Binar0101,

The only comprehensive document from Adobe is the Structure Developers Guide, installed with Frame 8 in the Documents directory. There used to be a tutorial called the XML Cookbook which was a good introduction, but I don't see it anymore. Otherwise, there are a number of third-party books on the subject.

You didn't really say what you are a "newbie" at, whether it is FrameMaker, XML, or both. You'll likely find that there is no single document that leads you through the process from start to finish, because all things considered this is a complex and highly extensible subject. Existing documentation necessarily assumes some prerequisite knowledge. Furthermore, you should expect that lots of experimentation will be required to make sense of it all. In other words, a 1, 2, 3 step procedure for conversion to XML is not really possible, hence is something that you will not find. Having said that, if you choose an existing standard such as DITA or DocBook, the path might be more straightforward.

Another important point that adds complexity is the consideration of your end goals. You should have some reason for conversion to XML, a reason which plays heavily into decisions made when building the conversion process. In other words, the techniques you use will vary according to your specific needs, especially if you have developed a clear understanding of the role you intend the XML to play. No "off-the-shelf" document would be able to anticipate those needs... it is up to you to take the building blocks, figure out how they fit together, then build something that works for you.

Russ

Report · May 19, 2009

Russ,

Thanks a lot for your post. I too have noticed that Adobe has not updated the XML Cookbook for version 8 or 9. This is a shame.

I think of myself as a "newbie" as it relates to XML output from FrameMaker. Otherwise, my skills with FrameMaker are pretty good. The reason I'm trying to grab a handle on the fastest way to learn XML output from FrameMaker is because I interviewed for a job that requires I output to XML a bunch of DoD manuals that were structurally and unstructurally authored in past versions of FrameMaker. I agree with you that "all things considered this is a complex and highly extensible subject". Nevertheless, right now my focus is just to figure out what STEP ONE is for the task I have at hand. Once I figure this out, I'm thinking I would at least know what the proper starting point in my case is for learning the complex subject of XML output from FrameMaker. In short, I don't want to waste time learning stuff that is outside of the task I have at hand.

You mention DocBook, currently I don't know how it ties in with XML output from FrameMaker. Therefore I'm going to make learning about DocBook my STEP ONE for right now, unless you or someone out there in this forum tells me I should focus my learning effort on something else first. Again thanks for your post.

Report · May 20, 2009

Binar0101,

I really think that XML Cookbook would have been excellent for you to understand the basic pieces of XML import/export. It's really just a translation process and Frame needs a bunch of pieces to make it work, mainly an EDD, a DTD/schema, and read/write rules. Once these are in place, there is only one step and that is File > Save As The thing about the DITA and DocBook standards is that these pieces are already built for you, so if you are willing to use their structure definition, there is less that you need to do in Frame to make it work.

Do you have an older copy of the cookbook? I would highly recommend it, at least for a quick intro. I bet it could be made to work for FM 8 or 9 if you reformat all the files for the new version and are willing to search around for any menu paths which may have changed through the versions.

Russ

Report · May 20, 2009

Binar0101,

You mentioned that some of your documents are already structured. Are they all structured using the same template and EDD (DTD)? If so, maybe your STEP ONE should be to export the structured documents to XML. The resulting XML will then have the same elements as the structured Frame documents from which they came, that is, they will be described by the same DTD (or nearly the same DTD) as the original documents. Then step two would be to convert the UNstructured Frame documents into structured Frame documents, maybe using the same EDD as the structured ones. Then export these to XML.

The underlying question in this suggestion is whether there is any requirement that the XML documents be consistent with an existing DTD or schema? Is the EDD (DTD) of the structured documents good enough for the exported XML? Note that DocBook and DITA use specific DTDs, which are more than likely NOT the same as the DTDs (EDDs) underlying your already structured Frame documents. Thus, to use DocBook or DITA to structure the XML files requires the extra step of converting the structured Frame documents to a DocBook/DITA structure.

I would emphasize one of Russ's points in an earlier post. You need to think more about the requirements of the exported XML. Does it need to satisfy an existing (DOD?) DTD or schema? Can it satisfy ANY DTD or schema? Is the DTD already used by the structured Frame documents good enough?

If you determine that the DTD or schema of the XML needs to be something other than the DTD of the structured Frame documents, then I suggest that your STEP ONE should be converting the UNstructured Frame files to a structure consistent with the DTD or schema. That will allow you to learn about the XML export process before having to tackle the additional step of transforming (XSLT) the structured Frame files into documents that satisfy your required DTD or schema.

Good luck. It can be a fun project, and you will learn a lot.

Van

Report · May 20, 2009

Binar,

You may also want to have a look at the "Migrating from Unstructured to
Structured FrameMaker" guide available as a pdf: < http://www.adobe.com/devnet/framemaker/pdfs/migrationguide.pdf >

It's for FM7.2, but the info on setting up the mapping tables is still the best available out there.

Report · May 20, 2009

Arnis, Van and Russ,

Thanks for all of your posts. Some of the FOG in my head is clearing out and at least I now have some idea where to start. Again thanks for your posts.