Help with importing XML, using EDD and DTD

[UIspecs]

Let me explain the situation in case there are multiple solutions.  I have a Framemaker setup that is inherited.  We use FM to write docs that we filter with conditional attributes.  Everything is fine there except for the "black box" nature of the thing... which leads up to now.

We are receiving documents that need to get integrated with our current system.  This documentation lives on a website.  We tried importing HTML, and now we are looking at importing it as XML.  The closest we've gotten to being able to make this work is by using the Book structure that is within the Framemaker installation files (Program Files\Adobe\Framemaker9\Structure\xml\Book\app_xml).  I should mention that I'm not exactly sure how the guy on the other end is creating the XML file.  I'm just trying to get what he gives me working in FM.

So the latest thing is opening successfully, but has **completely different elements and style than our docs**.  I've tried importing our EDD, but quite a few things break.  I've been studying EDDs and Template files to try to troubleshoot this, but I have only gotten so far.  I realized this morning that the XML file I'm being given is pointing to the Book.DTD... so I started looking at that.

I don't have the slightest of how to generate a DTD or get my docs to use a different one.

1. is there a way to automate a conversion from one EDD to another?  otherwise I have to go through and change elements by hand.  this will work but is incredbily time consuming and we are expecting a large volume of documents.

2. how does the DTD figure in with this?  I opened it in a text editor and it seems to have the same stuff as the EDD in a different format.

Any ideas are appreciated.

[Michael_Müller-Hillebrand]

UIspecs,

It seems you tried very hard up to this point, but unfortunately you seem to have got some concepts wrong. My first suggestion would be to invite a FrameMaker pro for a workshop, clearing up the misconceptions and paving the way to a solid solution.

Please remember: XML is just a way of coding structured information, it does not specify this structure. There is no guarantee that one XML file is compatible with another XML file.

Assuming your own material is all fine, then importing material based on a different structure usually involves changing that foreign structure into your structure. The technology for this is XSLT and FrameMaker comes with a feature that allows XSLT preprocessing when opening an XML file.

But try to get a deeper understanding of what happens behind the scenes.

- Michael

[Van Kurtz]

I echo Michael's response.

You seem to have an established EDD for your documents. The EDD, in a sense, contains the DTD and the formatting of your documents. There is probably other formatting contained in your templates (paragraph styles, etc). So, I assume you want this EDD and formatting to be the EDD and formatting for all your documents.

Given that, then the best way to get documents that have a different structure (that is, a different EDD and/or DTD) is to create an XSLT file that transforms the different structure into YOUR structure. Then all your documents have the same structure and formatting. Note that it is of little importance what the formatting of the "foreign" documents is; the important point is its structure. You said you opened the foreign XML file and its structure is different from yours. So, you will need to ascertain what the structure is and how you want it to translate into your structure. An XSLT file is the thing you need to do this. Once created, it will automate the opening of the many foreign files you will be getting. It may take sometime to create, but it does its job very quickly. Of course, it is hoped that all these files coming in use the same structure; if each one is different, you will have to create an XSLT file for each kind of structure.

The alternative to creating an XSLT is to create a new EDD that mirrors the foreign structure but applies the formatting that you want. This is much more difficult than creating an XSLT file. Moreove, you end up with two different EDDs to maintain.

XSLT is easy to learn; I have done it. Go to your local bookstore and get a good book on XSLT, but be sure to limit your reading to version 1 of XSL, because that is what FrameMaker understands.

Good luck,

Van

[UIspecs]

I had been trying the alternative you mention of creating a new EDD... yes, very tough lol.  I'm glad to hear XSLT will be easier.  The analysis I've already done will probably play right into the XSLT conversion.  Thanks.

[Lynne A. Price]

1. is there a way to automate a conversion from one EDD to another?�  otherwise I have to go through and change elements by hand.�  this will work but is incredbily time consuming and we are expecting a large volume of documents.

I concur with the advice you've been given to use XSLT. I caution you, however, that how successfully you can automate the conversion depends on the nature of the two EDDs. For example, suppose that EDD 1 has an element for numbered lists that writers use for both procedures (sequences of steps for someone to perform) and for other material while EDD 2 has different elements for procedures and other numbered lists. It will be easier to convert material using EDD 2 to EDD 1 than the other way around. Or EDD 1 may simply indicate when text is to be displayed as bold while EDD 2 defines different elements for different reasons that text may be bold (e.g., product names and emphasized phrases). There may not even be a one-to-one correspondence between elements. For example, one EDD might treat a step in a procedure as undivided text, while the other divides it into two parts: one for what the user does, one for what happens as a result. Even two EDDs that recognize these two subunits, might group them differently, consider, for example:

   a.  Perform action one. Response one will happen.

   b.  Perform action two. Response two will happen...as opposed to:   a. Perform action one.
   b. When response one occurs, perform action two.
   c. When response two occurs, ...By the way, while XSLT is a programming language specifically designed to transform XML documents from one form to another, with output that may or may not be XML. You are faced with moving XML material using one structure into FrameMaker using a different structure. XSLT is a natural tool for helping with that transformation, but it is not the only possible tool. For example, depending on the conventions used in the original XML and the tools you already know how to use, you might be able to use Perl script to modify the XML before opening it in FrameMaker.Or, if all you need to do is rename some elements, you can do that with a global Find/Change in FrameMaker. Suppose, for instance that you need to change <li> to <item>. In FrameMaker, you can search for elements named "li" and change their element tags to "item".You could also develop a FrameScript or FrameMaker plug-in to make further modifications once the data has been brought into FrameMaker.Van recommended that you stick to XSLT 1.0. You could use XSLT 2.0, but the workflow would be slighly different.  When you use any scripting tool to modify the XML data before bringing it into FrameMaker, the data goes through three stages:a. The original XML
b. The modified XML (say, result of processing by XSLT or Perl)
c. FrameMakerForm b. is a temporary file that you can discard once it's been opened in FrameMaker. The use of XSLT is so common, that you can configure FrameMaker to open the original XML, apply XSLT to it, and read the result. Van is correct that FrameMaker only supports use of XSLT 1.0 in doing so. However, while it may seem that you are simply opening the original XML in FrameMaker, all that's really happening is that FrameMaker is creating the temporary file for you, using it, and then discarding it. If you are willing to keep track of the temporary file yourself, you can use XSLT 2.0, just as you would if you were using Perl, macros in a text editor, or any other scripting tool. Of course, you'd need to get an XSLT 2.0 processor that you can run outside of FrameMaker.

2. how does the DTD figure in with this?�  I opened it in a text editor and it seems to have the same stuff as the EDD in a different format.

There is a great deal of overlap between a DTD and an EDD--so much, in fact, that FrameMaker can automatically create a DTD from an EDD (with StructureTools > Save as DTD) and an EDD from a DTD (with StructureTools > Open DTD).An EDD is specific to FrameMaker. A DTD is specific to XML (or SGML).XML is a generic markup language. It is an open text format for describing hierarchical data. A DTD is one way of defining the elements and attributes to be used in a class of documents as well as the permitted arrangements of the defined elements. A DTD has no formatting information. An EDD is the logical equivalent of a DTD with added formatting information.Structured FrameMaker can be used with or without XML. If you need both, the specification for the elements and attributes to be used in XML may exist at the start of a FrameMaker project. In this case, there is likely to be a DTD (or a schema that can be converted into a DTD) before the FrameMaker work starts. One of the first steps in such a project would be to create an EDD from the DTD. The result will define elements and attributes but not contain information on how to format those elements. Another possibility is for the FrameMaker environment to be created before XML is generated. In this case, FrameMaker can create a DTD from the EDD. The result will define the elements to be used with their permitted/required content and attributes, but will not contain formatting information.        --Lynne

[UIspecs]

Lynne,

Thanks for answering my DTD question.  I'm going to try generating a DTD from my EDD to send my counterpart.  Perhaps he can structure the XML files he is sending appropriately with that file and save me all the trouble!!