Help generating DTD and Read/Write Rules

Report · Nov 30, 2011

Hi all,

I’m trying to structure a large number of unstructured FM8 files using DITA 1.2 and FM10. I’m having some trouble with the EDD/DTD/Read Write Rules and was hoping someone could help me out.

My current understanding of how to set things up for structured authoring is the following:

Create a structured template.
Use that template to export an EDD.
Use the EDD to save a DTD.
Generate Read/Write Rules using the DTD.

I’m having trouble with steps 3-4. My main concerns are how to generate a legal DTD and how to use the Structured Application Designer to get RW Rules. At the moment, the only way I can generate a legal DTD from my EDD is to remove the Structured Application specification at the beginning of the EDD (see below).

I attended a webinar that said the Structured Application did not have to be specified to extract the DTD. Is this accurate? Will it impact my DTD?

Once I get the DTD, I’ve been trying to use the Structured Application Designer to generate the RW Rules.

I select Add Element Map With Name > dtd. When the list of elements appears, I select all of them and add them to the Import-Export Settings and Save the new Structured Application; however, this does not seem to have any impact on the files I’m trying to structure and save as xml.

Am I missing something? If anyone can identify some key steps I’m missing or has experience using the Structured Application Designer that could give me some tips, I would really appreciate it. This is my first time working with xml and structure, so any guidance would be great!

Thanks,

D'Arcy

Report · Nov 30, 2011

Hi D'Arcy...

I think you're trying to do too much all at once here. If you're trying to convert unstructured FM files to DITA, you need to create a conversion table (maps the para and character styles to DITA elements and structures), then import the DITA template and EDD into the resulting files .. then save to XML. This is a very rough overview of the process, but that's basically what's needed.

The Structured Application Designer is for creating your own structured application .. you should likely just be using the provided DITA structure applications. If you want to customize those that's fine, but that should probably be done after you've converted your content.

To be honest, I have no idea how to use the Structured Application Designer .. I've been creating structured applications for years the old fashioned way, and find this too to be very confusing and overly complicated. Unfortunately there's very little useful documentation (that I'm aware of) on this tool so that complicates matters. You should really read the Structure Application Developer's Guide to get a full understanding of all the pieces that make up a structure application .. then you may have better luck with this tool .. or you'll just be able to create an app on your own.

http://www.adobe.com/devnet/framemaker.html

Scroll down to the "Structure Application Development" section.

Cheers,

...scott

Report · Nov 30, 2011

Thanks Scott. I'll try to give you a better explanation of where I'm at in the process and why I feel like I have to start messing around in the Structured Application Designer:

I have created a conversion table that's working alright and I am able to import the template and EDD into it successfully. Unfortunately, when I save to XML the basic formatting (paragraph and character fonts) reverts to the default formatting (the formatting in the templates that ships with FM10). My coworker who set-up the templates had the same problem when she tried to save the templates as XML.

So, we assumed that we needed to update the Read/Write rules because there seems to be a disconnect in the fm files and xml files.

Does this make sense, or do I not have a good understanding of the purpose of the Read/Write rules. I've tried to read the Structure Application docs, but unfortunately the latest version is for FM9 and I don't think they implemented the Structure Application Designer until FM10.

It might also be important to note that we have not included font information in the EDD. We were under the impression that we could update the character and paragraph tags in the FM template and that they would carry-over. Is there an additional step that we need to do here?

Report · Nov 30, 2011

Ah, OK.

The first thing you need to do is to clone the default structure applications to create your own apps. This is much more complicate with FM10 and DITA 1.2 because instead of there being a single app that covers all of the DITA topic types, you've got one app per topic type. If you're not using DITA 1.2 features, you might consider usign the DITA 1.1 apps and focusing on migrating the ditabase app (that allows for all topic types).

Here's the general process you'll need to follow if you don't want to use the standard formatting provided by FM10 apps ..

1) Clone the default apps to create your own apps. This is very important since you really shouldn't mess with the default apps so you can have something to test with *when* you break them (you will .. we all do at some point). Here's a link to the DITA_FMx documentation that explains how to clone the apps (this is written for DITA-FMx and DITA 1.1 and a single app for all topic types, but gives you the general idea) ..

http://docs.leximation.com/dita-fmx/1.1/?ditafmx_cloningtapps.html

The Structure Application Designer may be able to help with this, but I can't say.

2) In your cloned apps, modify the properties and styles in the template file to change the page layout and formatting. If you need to modify the underlying EDD, remember that the EDD lives inside of the template, so you'd modify the EDD then import that into the template. The structured application definition references the template file which is a combination of the EDD and template. It's likely that you won't need to touch the read/write rules .. this just affects the mapping of one element type to another or the assigning of object types to elements. Unless you're making very serious changes to the DITA structure, the default r/w rules file should be sufficient.

Hmm .. that's really it. Just two "steps", but lots of iteration within each step.

The FM9 Structure Application Developers Guide still applies to FM10 .. it doesn't have information on the Structure Application Designer, but it provides all of the information about the relationship of the underlying files, and is really the info you need to be doing this type of thing.

...scott

Report · Dec 01, 2011

Darcy,

In addition to what Scott advises, I just want to clarify one point you had.

I have created a conversion table that's working alright and I am able to import the template and EDD into it successfully. Unfortunately, when I save to XML the basic formatting (paragraph and character fonts) reverts to the default formatting (the formatting in the templates that ships with FM10).

As you may know, an XML file contains only content, not formatting. So, once you convert an unstructured document into structured, you import the template, as you said you did. The template provides the formatting you wanted. THEN when you save the file as XML, the formatting is NOT part of the XML file. When you open the XML file in FrameMaker, part of that process is to import the template. Because you are using the default DITA application to open the XML file, FrameMaker is using the template specified in the default DITA application, NOT yours. This is why you need to clone the DITA application, so you can tell FrameMaker what template to use when opening a DITA XML file.

Scott knows more about DITA in FrameMaker, but it appears to me that the DITA EDD does no, or maybe only a little, formatting directly in the EDD. To my knowledge, the DITA EDD applies formatting by assigning named character and paragraph formats. So, if you want you structure to follow DITA but with a different format, then all you may need to do is edit the character and paragraph formats, master pages, etc, to get the result that you want. There may be no need to edit the EDD or the read/write rules.

Van