Managing EDD, DTD, and templates in Framemaker 11 and DITA 1.2

Report · Apr 24, 2013

I'm in the process of upgrading from FM9 with DITA to Framemaker 11 with DITA 1.2 I'm using the ditabase template, EDD, and DTD. I've made some paragraph format changes in the template and will need to make changes to the EDD as well. Once all the changes are made, I will need to distribute the changes to other writers. I'm wondering what is the best way to go about making the changes so the distribution process is as simple as possible?

In FM 9, the EDD was a single file so we only had to update 2 files (the template and the EDD). In FM11 with DITA 1.2, there are multiple EDDmod files. Do I need to distribute all of these files to apply the changes?

Also, I haven't actually been able to apply the changes to the EDD to my documents and I'm not sure what I'm doing wrong. This is what I did to change the prefix text applied to the postreq element:

1. Open the task.eddmod.fm file. Find the postreq element and change the prefix text. (Note that this is the only change I made to the document) Save the document.

2. Open the ditabase.edd.fm file. Find the text inset to the task.edd,mod. fm file. Update the text inset. Save the document.

3. Open the dtiabase.template.fm file. Import the Element Definitions from ditabase.edd.fm file.

Expected results: the element definitions are imported with no errors.

Actual result: I get the following error messages:

Format rule specification (| bookmeta) is invalid.

Elements that are defined but not referenced.

steps-informal

Elements that re reference but not defined.

bookmeta

topicmeta

I didn't make any changes to these elements so I don't understand why they are now invalid. Did I miss a step or do something incorrectly that would affect these elements?

Note that I'm making the changes to the original documents that are referenced in the structured document, the template, and so on. I have saved backups of all the original files before I make changes to them.

Thanks for you help,

Sharon

Report · Apr 24, 2013

Hi Sharon...

First .. it's best to clone the default apps and create a new structure application using your own app name. That will make it less likely that you'll run into problems trying to fold your updated files into the default structure. It also means that you can have the default apps and your custom apps available at the same time (without restoring from a backup set). As you customize the apps, you will break things, and it's really nice to be able to swap back and forth with the default apps and your apps for testing and comparison. I strongly encourage you to take the time to create your own app names rather than modifying the default files.

That said .. you only need to provide the files referenced by the structure application definition. The EDD (and "mod") files are not part of the structure application definition since the EDD has been imported into the template file. The template file contains all of that data. Just provide the template, DTD, read/write rules, and XSLT(s) that are referenced by the app definition.

I like to use what I call, "structapp stub" files to make the "installation" of a new app less painless. This stub file is a text inset that contains the entire structure application definition. All that's needed is for the "user" to insert that file (as an inset) into their structure application definitions file.

Customizing the DITA 1.2 EDDs is *very* difficult. These files make use of nested insets to EDD "mod" files, and are filtered for the various topic types using conditional text. I can't even begin to explain how to proceed. You have to carefully reverse engineer the nesting of the files.

My only suggestion is to open the template file for whichever topic type you want to work with, and export the EDD. This will give you a single file that contains all of the EDD code that's needed for that topic type. Save the resulting EDD and use that as the starting point for your customizations. Or .. better yet, think hard about whether you really need DITA 1.2 at all .. if you're not planning to take advantage of the DITA 1.2 features .. use the DITA 1.1 structure applications which are mocu simpler to manage.

Cheers?

...scott

Report · Apr 26, 2013

Hi Scott,

Thanks again for the help. It's very helpful.

I don't have any strong reason to move to DITA 1.2 other than I was getting an error trying to open the documents in DITA 1.1. I found the solution though in a response from you to another questions about moving from FM9 to FM10. I was getting the same error message: Message: Attribute '{http://www.w3.org/2000/xmlns/}ditaarch' is not declared for element 'dita'. It must have been something in FM9 because this attribute is in all my files. So I have the DITA 1.1 set up and am able to modify the template and edds. Much easier than in 1.2!

I have most of the files working now, at least back to where they were before upgrading, except for variables. In the headers and footers, a number of user variables were used to set the book name (BookTitleName) and chapter name (ChapterTitle). When I open a xml file and set these variables they work, but when I save the files as XML, close it and then reopen the file, the variable settings are gone again. Do I need to declare them somewhere or add them to the template to get the defintions to stay when closing and opening the xml files? For some (like ChapterTitle) I don't want the same value for all the documents the template is used in. Or is there a better way to set up the headers and footers with this information? I use conrefs for the document name elsewhere in the document but don't see a way to add them to the headers and footers.

Thanks again,

Sharon

Report · Apr 29, 2013

Hi Sharon...

None of the info you change on a mater page or reference page or in the document catalogs (tags, styles, formats) is saved in the XML. When working with DITA (any XML model) you should never modify any of that information, since it'll just be lost when saving the file. That information is applied by the template when opening the XML file, so you should change it in the template, then reopen your XML file or import the template into your XML file.

You may be interested in DITA-FMx (a plugin I produce), which among other things, will let you update variables in your template(s) based on metadata in the map. This means you can have your headers/footers and other information (even on the title page) update with project-specific information stored in the map rather than needing to update the template for this purpose ..

http://leximation.com/dita-fmx/

Here's a video that shows the entire book-build process with DITA-FMx ..

http://blog.leximation.com/2010/03/pdf-publishing-with-dita-fmx-1-1/

Cheers,

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com