Exporting an existing EDD to a DTD

[theGavMan]

I am completely new to Fm, using Fm 11, have a limited understanding of XML and trying to show a proof of concept for a task I was given. In a nutshell, I was given an existing EDD and a publication that contains txt and graphics; these files are Fm files. I am trying to export the valid EDD to a DTD using the Fm  StructureTools -> Save As DTD function and get an error saying the Application "X" does not exist. Reset the app name for the EDD or define a new application. I see at the top of the EDD the tag Structured Application: X , but I cannot figure out what I need to do with this tag/element to get the EDD to save as a DTD. My thought is to use Fm to export the EDD and publication files as XML, then use a script, eventually, to insert new elements throughout the publication, import the marked up XML files back into Fm. I have searched the web, adobe user guides, and various tutorials trying to understand this problem but so far notta. Can someone point me to an example or provide some insight as to what I need to do to export this EDD as a DTD? I am also wondering if anyone can point me to a good tutorial on Fm 11 that might help me with this SW in general.

Many Thanks in advance for any help/info on this matter!

[Gorly]

Hi,

to get that EDD translated to a DTD, you need to specify a structured application for it in your stuctapps.fm file. This is pretty easy, once you take a look at the other applications in that file.

You can open your current structapps.fm via the Structure Tools menu (Edit).

After defining the application, your DTD can be created.

Problem with this automatically generated DTD is, that it needs some manual tweaking afterwards to do exactly what you need.

So before you start messing around with that, I'd suggest you take a closer look on the FM guides here: http://helpx.adobe.com/framemaker.html - specifically the Structured Application Developer Guide.

Then you should also get familiar with the creation of DTDs and XML in general, to get a grasp of what needs to be done to set the export up correctly.

As you mentioned that you want to embed the XML files in an automatic process to insert elements to the document, you should also learn about XSLT and XPATH, which will be most probably the tools you'll be using to accomplish that task.

Still following me? Ok, if you have a slight clue - at least enough, so you can get an idea of a problem and ask the appropriate questions - about all that, you can then start to work on your implementation.

From there on, you'll find lots of useful information on these forums and on stackoverflow (when it comes down to XSLT).

But for now, the most pressing questions should be (in that order):

- What is a Structured Application in FM and how does it work?

- How does a DTD work and how does it impact my work? 

- What is a Read/Write-Ruleset and how does it impact my file export?

- How does roundtripping FM->XML->FM work and what are the odds and ends with it?

- Do my files roundtrip correctly and how can I assure, they will do so in future?

- What are XSLT and XPATH, and how do they work in general?

- What are identity transformations and how do I do them correctly (whitespaces in mind)?

- Is this worth it, or will ExtendScript work better for my buisness case?

I hope you have the time and budget to invest on the effort needed to get a clear vision about what is happening in the process and to get a closer looks on the mechanics of this.

It's nothing that can be done over night, but it's worth it! The better you understand all that, the better your result will be.

Hope that helps you getting started.

-Alex

[theGavMan]

Thank you Alex! I really appreciate the time you put into the response and for pointing me in the right direction for Fm resources. It has been clear to me from the moment I was thrown into this task that there were a lot of unknowns and a very steep learning curve lie ahead of me. The questions you outlined should also help us deliver a better product in the end which will benefit us as well as our customer. I do know that FM is a SW program that our customer is using so we are locked into using this SW as well.

Again, Thank You for your time. Happy New Year!

[Gorly]

Merry X-Mas and Happy New Year to you, too.

It is indeed a quite steep learning curve, but it is also a rewarding one.

Once you've managed to establish a clean process, it makes so many things much more easy and pays off by saving you literally tons of time.

Especially when it comes to XSLT, you can do quite some impressive "magic" to those documents.

-Cheers Alex

[theGavMan]

Hello Alex -

I have spent some time reading up on FM and XML and have a bit better of an understanding on what I am supposed to be doing. When we spoke last I was under the impression that I needed to do a XML export in order to mark up my documents. I think that eventually we will develop a script that marks up the XML data for us but for now we are going to do it manually. So, to do a manual markup within FM - once I have modified an existing EDD, within FM itself then export my FM documents to XML for use with various programs that process XML data/files. I have a few questions regarding the EDD. I have been given an EDD that I need to modify to include new Elements. Assuming that I am able to define my new Elements correctly and get a valid EDD - I will still need to get FM to 'resource' the newly modified EDD so I can actually add the new Elements to my Doc - Correct? I am assuming that there is an easy way to do this 'resourcing' by either placing the modified EDD in some directory that FM reads or by selecting something on the main menu - am I on the right track there?

In my newly defined Element, I have an attribute defined that needs to be a unique GUID for every instance of my Element inserted into the marked up doc. Is there a way within FM to do this or do I have to use some external tool to generate this ID and then just modify the Element's attribute manually. I was thinking that there was possibly an extension or something within FM that would allow me to make a function call to automatically populate this attribute. Using a script to populate those attributes on the exported XML files would work as well I suppose.

Thank you very much for any help - Have a great day!

[theGavMan]

Update:

Seems I was mistaken and the EDD being given to us...I came late onto this project late and someone had apparently created an EDD from a PDF - perhaps? Im not exactly sure how it was created and no one seems to know exactly where it came from - ha. Anyway, I now know that i have to actually create the EDD which is a much bigger task than I originally thought. If I have a doc (given pdf or text files and together make up the pdf) should I create the EDD from those docs via FM or do I really have to define the entire EDD from scratch? 

[Russ Ward]

GavMan,

My XRefWizard plugin can populate unique IDs automatically. You can try it for free:

XRef Wizard - West Street Consulting

Also, it would be reasonably elementary to write an ExtendScript for that, if you have some knowledge of scripting.

Regarding some of your other questions, I'm having trouble figuring out exactly what you want to do. An EDD is to FrameMaker what a DTD is to XML (loosely)... that is, it defines the structure definition for a structured FM document. Unlike XML, which references a DTD from a separate file and then a parser has to figure out the rest, an EDD is imported into a structured FM document and lives there indefinitely unless replaced. Once an EDD is imported into a file, the "hidden" copy within the file does all the work and there is no further linkage to the original, standalone file. So in summary, EDD import is entirely manual and there is no concept of automatic "resourcing" or similar.

An FM document without an EDD is an unstructured document. Once an EDD is imported, any flow within the document is a candidate to contain structured text, but does not have to. You import an EDD with File > Import > Element Definitions. Also, note that a structured  FM document is not native XML and never has to be if you don't need XML. It can live in binary FM format forever. If you do decide to convert it to XML, the process is more like an export, rather than a save. Likewise, when you open XML in FM, it is more like an import, because it gets converted to a structured FM document during the process.

I don't quite get what you mean when you are referring to PDFs. An EDD is a structured FM document itself and is authored strictly within FM. There is a feature to import an XML DTD and convert it to an EDD, but I would personally not trust it, as an EDD is a somewhat different animal. Perhaps I'd try it as a baseline, but ultimately any EDD will require lots of manual work.

If you do not have the EDD in its original, structured FM form, then you need to create it. One thing, though... if you have any structured document with that EDD imported already, you do have it. You can export a full copy of the original with StructureTools > Export Element Catalog as EDD. The copy may be reorganized (mostly alphabetized), but will have all the original data.

As a general note, this is complicated stuff that can take months to understand well. As Alex mentions, the rewards are well worth it, but you should not expect to be throwing all this together in the near future. I always think it is much better to start from the beginning and build your own EDD, rather than diving into some existing document and trying to figure it out. In any case, keep studying and experimenting. You'll get it. Once you have a stronger general knowledge, you'll be able to ask more focused questions and likely get better answers on these forums.

Hope this helps,

Russ

[theGavMan]

Thanks Russ -

Yes this is complicated stuff and I just got thrown into this and of course management wants it done like 3 weeks ago - of course. Anyway, your right my questions arent not that focused as Im not totally sure of what I am doing yet. Maybe if I laid out what exactly im trying to do you or someone out there could point in the right direction or tell me if this is a valid model for accomplishing my goals?

Here is the project in a nut shell: We are given a bunch of files - im assuming that are unstructured as they dont come with an EDD or a DTD. We are also given a PDF file of the entire document - i.e. one that is not broken up into many individual files. I pull one of the smaller (non PDF) files into FM and use the structureTools->Export Element Catalog to EDD. This is all fine and good and seems to work as I do get an EDD generated by FM, but I need to add a few new Elements in the EDD so I can add them to the files. In other words, I am supposed to create and add these new Elements, at various places, to the documents content. So, I modify the EDD (that FM created from the document) to include my new element and then validate the EDD within FM. FM says the EDD is valid. I thought that I could add my new Elements into the doc at this point using the structure view but my newly defined elements do not show up in the Elements catalog within FM. (This is where I got the resourcing the EDD idea from) I was thinking that I needed to show FM that I modified the EDD somehow so that it would recognize the new Elements and then I could insert them into my doc by using the Element catalog. Once I added the new elements, I need to export everything to XML so that our customer can use the XML versions of the marked up files however they want.

So my thinking at this point was to export the EDD out to an XML file and then import it back into FM to see if my newly created Elements would show up in FM so I could use them to markup the file, but FM cannot parse the DTD that I exported from it. It barely makes it through the first few lines then barfs. SO, Im currently stuck trying to find out my FM cannot parse the DTD that it created, AND Im not even sure if I am on the right track.

Years ago I wrote shell scripts on a UNIX platform when I was a developer, now I am working in GIS on a Windows platform and have been away from the developer world for a while, so I am rusty to say the least. Again, thank you for your time and Happy New Year!!!

Gavin

[Gorly]

Hi Gavin,

seeing now, what you have at hand and what you need to achieve, there's a bit more help I can offer

First off, it seems, that you already have a structured document to start with. You can easily recognize this, if you place the cursor in a text line within the document and see the structure view populated with elements.

When this is the case, there's an EDD underlying in your FM binary document file, that you can use and modify. I suspect you already did that, as you already inserted the new elements to it.

Now, having done that, all you need is to re-import the modified EDD back into your document. Russ already stated, that the EDD is ALWAYS tied to the binary FM file, once it has been imported to it.

The external EDD does also have its place in this. Think of it as the "master copy" of your structure (very much like a template). If you are doing changes to the structure, always do that in the external EDD and then propagate it to the binary FM document files when needed.

Now, on a side note, there's also the possibility to have some different workflow.

As your customer is working with XML files only, you could also re-organize your own workflow to be XML based.

FM from version 11 on supports this. In that case FM would only be a wysiwyg editor for XML, and the EDD would become self-propagating (as it creates only a temporary FM binary file, that is scrapped when the wysiwyg view is closed).

But this is quite some different beast to tame. You could evaluate this as a long term goal (once you got a better understanding what you are doing).

So, back to the business problem you are trying to solve at the moment.

After having modified the EDD, this is your todo list for the next steps:

1. re-import the modified EDD to your document file.

2. create a structured application for your documents (if there's not already one used).

3. create a DTD from the new EDD and modify it, so it supports additional information that is needed (like table properties).

4. modify the read/write rules of the structured application you have created in step 2, according to the EDD/ DTD,

5. see, if your document exports correctly to XML.

6. see, if the so created XML file imports back into FM correctly (this step will also need the "master" EDD).

7. fix the issues that occurred during roundtripping (this will most probably be issues with images, tables and whitespacing) in EDD, DTD and RWR.

8. repeat steps 4-7, until you have a working roundtripping solution.

9. fix the issues with UIDs (those will most certainly arise in the process) by FM scripting or with XSLT (depending on what solution you prefer or fits best to your current workflow).

10. explain to the management the you expect a rise in salary, now that you are an expert on document structure management

11. care about further document processing in XSLT and/ or XSL:FO.

12. explain to the management, that you could have matched the deadline, if they had given you training on all this a year _before_ they wanted to see results.

13. see, if you can streamline the process you've set up (check the possibilities of an "XML only" workflow and see if your authors would support it).

14. add new features to the creation process (such as automatic language dependent quote marks, color encoding and other ease of use stuff) - this is where the process you've set up/ knowledge you gained starts to pay off.

Hope this helps your case and gets you going

-Alex

[theGavMan]

Happy New Year Alex!

Thank you very much for the response. This should help out a lot as I have now have a good workflow to follow. I had a good laugh with your cracks about management as that is way too true! I feel like I am starting to get a better understanding of what I need to do now I just have to get the pieces figured out for the steps you listed.

I cant stress enough my gratitude to both you and Russ for taking the time to help me along in this process. I still have a long way to go but you both have helped me out and I thank you very much for doing so.

Best,

Gavin

[Russ Ward]

Gavin,

The forum emailed me a response from you but I don't see it here. I'll respond anyway. I think you might be making this way more complicated than it is. The EDD that controls any given document is embedded within it, placed there by a manual import action. It never changes unless you reimport it. So, with your FM document active (the one you are actually authoring in), select File > Import > Element Definitions, then select the modified EDD file.  And then import, usually with the option to remove format overrides. That's all there is to it. Then, the document's element catalog will reflect the new changes.

There is no automatic linkage between a standalone EDD file and a structured document. You have to do the import to make the update.

Russ