Problem Working With Framemaker 9 Dita XML Files in Framemaker 10

[Guest]

I just upgraded to Framemaker 10. I am encountering a number of problems when I try to work with my Dita XML help topics, which were last saved in Framemaker 9 format.

1. Using the Default Dita Template

When I open one of my documents in Framemaker 10, the Dita 1.2 template ditabase.fm is automatically applied. Everything seems fine. But then when I convert the XML to Eclipse help (which is essentially html, so we're going from XML to HTML) using Dita Open Toolkit ant scripts, I see this message:

[pipeline] [DOTJ013E][ERROR] Failed to parse the referenced file 'html\c_licensing.xml' due to below exception. Please correct the reference base on the exception message.
[pipeline] c_licensing.xml Line 25:Attribute "xmlns:ditaarch" must be declared for element type "dita".

I then opened the xml  file in a text editor, and I saw this on line 25:

<dita xmlns:ditaarch = "http://dita.oasis-open.org/architecture/2005/">

Line 25 looks fine to me. Am I missing something? 

2. Switching to a 1.1 Dita Template

I tried to work around the above problem. In Framemaker, I tried to set a different structured application as the default one. I closed all files and chose the default Dita 1.1 structured application (it defaults to the Dita 1.1. Composite app.)

Then I tried to open my file: I got this message inside Framemaker:

"Validation of XML failed. Continue?
Error at [FILE PATH], line 25, char 72, Message: Attribute '{http://www.w3.org/2000/xmlns/}ditaarch' is not declared for element 'dita'

Sounds familiar, doesn't it?

I switched from the default Dita 1.1. Composite structured application to the Dita 1.1. Topic structured application. Then I dirtied the source file and saved it. The messages I got in FrameMaker log window included the one above, plus I got a variety of Unknown Element messages, things like this:

Unknown element dita,

unknown element concept,

various attributes are not declared for concept,

unknown element conbody.

If I switch back to the Dita 1.1 Composite application all of these messages diappear except for this one:

Attribute '{http://www.w3.org/2000/xmlns/}ditaarch' is not declared for element 'dita'

My ant conversion scripts from the Dita Open Toolkit are still unable to process this file. They give the same message as is listed in (1) above and the file is not converted to HTML.

Can anyone help me with this problem? I've also posted this question to the Dita Users Group on Yahoo Groups. If I get an answer in one place, I'll post it in the other.

Thanks,

Nina P.

[ScottPrentice · Accepted solution]

[cross-posted to dita-users]

Hi Nina...

The xmlns:ditaarch attribute should be on the "topic" element not the root dita element. if the FM10 structure application is assigning that, it's wrong. Are you creating composite topics (multiple topics in one file under the dita root)? If not, you can get rid of the dita element altogether and that may "fix" the problem.

The first error you're getting (#1) is saying that the xmlns:ditaarch attribute needs to be declared (that is, defined in the DTD) .. it's not (because it's not supposed to be there (as far as I know). It's not saying that it should be declared in the DITA file.

Same for error #2 .. the 1.1 composite app is apparently set up properly, so it's saying the same thing that the OT is saying .. "you've got this attribute in the XML file, but it's not declared in the DTD".

Your later error about missing elements is because you've switched to the "topic" DTD, which doesn't know about the dita element or the concept-based elements.

If you can unwrap the dita element from your files (because you're just using one topic in each file), that may solve the problem. But what you probably should do is open these files in a text editor and remove the xmlns:ditaarch attribute from them (it's not really needed on the topic elements either since it's the default value). Then I'd switch to the 1.1 composite app as your default. I'll take a look at the default FM10 1.2 app and see what's up. (I've not seen this problem since I'm using DITA-FMx which has it's own structure apps.)

Cheers,

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

[Guest]

Thank you very much, Scott. Removing that xmls:ditaarch attribute from the Dita element worked. The XML document now opens and saves fine in Framemaker, using the 1.1 Composite template.  It also converts to HTML when I run the ant script.

I also tested unwrapping the Dita element from the document. That seemed to work fine as well. The document saved without any errors in Framemaker and it converted to HTML.

I next tried appying the Dita 1.2 ditabase structured app to my source file. It saved properly in Framemaker and the ant scripts did not complain, but I'm going to reapply the the 1.1 Composite template.

Finally, the topics display correcty in the help system.

Not all of my topic files have that attribute in the Dita element, but a good number of them do. Looks like I need to do a bulk search and replace.  Or just remove the Dita element as I open each file.

Was the Dita element once used with older versions of Framemaker?  I am just wondering how it and that attribute got into my source filees in the first place?  I don't recall ever adding it; I think it was always there.

Again, thanks for your help, this had me stumped.

[ScottPrentice]

Hi Nina...

I think that the FM templates have always defaulted to creating dita-rooted files. With the Composite (or ditabase) app, you can have it both ways .. which is nice in FM so you only have to maintain one structure app rather than one for each topic type. The reason for using a dita-rooted file is so that you can have multiple top-level topics in one file. If you're not creating files that contain more than one topic, then there's no reason to use the dita element. It's most common to just have one topic per file so in general the dita element isn't used.

Cheers,

...scott

[Guest]

Thank you for these additional details, Scott. I think I might have a couple of topic types in my task topics: I wanted related links sections in those at one point and I believe I cobbled something together by adding a concept element at the end of the task. I'll watch out for that!

I'm having a new problem. I cloned the Framemaker 10 DITA app. and named it DITA-BigPage, following your instructions which you kindly provided me for Framemake 9 a couple of years back. I must do this because I need one page size for my eclipse help topics and another page size for the PDFs.   I altered structapps.fm as well, again following your instructions for cloning the elements in that file and changing their paths and their application name to that of the EDD in my Dita-BigPage clone. I believe I did all of this correctly.

But when I open a Dita XML document, either one that I've stripped the Dita element from (they say Reference or Concept, etc. at the top, now) or one that still has the Dita element but without the attribute, the default structured application that is applied is DITA 1.1-Reference-FM or DITA 1.1-Composite-FM, not DITA 1.1-Reference-BigPage-FM or Dita 1.1-Composite-BigPage-FM.  I can choose "set structured application" from the Structure Tools menu, and select any one of my modified "BigPage" apps, but when I do that my XML page width does not expand  the way it should if a "BigPage" template were actually being applied.I save the file and reopen it and the default assigned structured app is Dita 1.1-Reference-FM, not my BigPage clone. 

I tried manually importing the formats from the BigPage template into my document file, but they don't "stick." As soon as I save, close and reopen the file, I'm back to square one.

I looked for a way to set the structured application permanently and came across the DITA Applications Mappings Manager, but the documentation on this is so sparse and lacking in context that I don't know (a) if using this will give me the result I want and (b) how to get this utility to "see" my BigPage structured apps. (Currently my BigPage apps do not appear in any of that dialog's selection areas).

FrameMaker 9 used to pop open a little dialog each time I opened a file asking me which structured app I wished to use with the file. The dialog remembered my last choice, which was always my custom BigPage application, and so my pages always formatted correctly. FrameMake 10 seems to be doing things a bit differently, and I'm not sure how to get it to use my custom application with the large sized page.  That is the only change I made to my new application: I set the template's page size from letter to tabloid.

[ScottPrentice]

Hi Nina...

It sounds like there's something wrong with the structure application definitions for your BigPage apps. The thing that associates an application with an XML document when you open it is the doctype and the Entity Locations entries. Take a careful look at the headers in your XML files and compare the Public ID in there with those in your structapp definitions .. they need to match. If the app's has a doctype an Public ID match those in the  XML file being opened, that app will be listed in "select an app" dialog (unless there's only one matching app, in which case that's the app that will be used by default).

Yes, the DITA Applications Mappings Manager is not well documented and a little obtuse. I do think that you need to add your apps in there as well in order to be recognized, since this layer seems to override the default app-loading mechanism when working with DITA files. DITA-FMx doesn't require this additional layer, so I haven't messed with the App Mapping Manager in a long time. I'll need to reinstall the default DITA support to get that back and do some testing. See if you can add your apps into this Manager.

Let me know how it goes.

...scott

[Guest]

I really appreciate all the help you are providing with this, Scott. I tried your latest suggestions. Here's what happened:

Application Mappings:

I figured out how to add my "BigPage" structured application to the Applications Mappings dialog. I made a new "BigPage"  mapping type, then figured out the non-intuitive part: how to add my individual BigPage topic types to it.  I closed and reopened FrameMaker opened my test document, and, as before (before I did the application mappings) I saw my BigPage applications listed in the Structure Tools > Set Structured Application drop-down. I selected the appropriate application (in this case it was DITA1.1-BigPage-Reference-FM and clicked the "Set" button. 

It is at this point in Framemaker 9 (and also once, in FrameMaker 10, early in this process, but I haven't been able to replicate it since) that the page size would change to tabloid size, indicating that the document was using the template from the BigPage reference structured application, not the regular DITA1.1 reference application. But this did not happen.

I tried saving the document, closing it, and reopening it. Once again the default structured application assigned to that document was "reset" to DITA1.1-Reference-FM.  But the fact that the page size did not immediate refresh to tabloid size told me that although I did select the BigPage application in the drop-down, it wasn't being applied.

Public IDs:

The public ID in my test reference XML file is:  <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" [

The four public IDs in the DITA1.1-BigPage-Reference-FM entry in structapps.fm (in the Entity Locations section) are:

-//OASIS//DTD DITA Reference//EN 
-//IBM//DTD DITA Reference//EN
-//OASIS//DTD DITA Composite//EN
-//IBM//DTD DITA Composite//EN

Do you see anything wrong with the above? .

Directory Structure: 

Maybe I cloned the application incorrectly?  Here's what I did:

1. In C:\Program Files (x86)\Adobe\AdobeFrameMaker10\Structure\xml, I copied the folder called DITA and pasted it into the same directory. I renamed this folder DITA-BigPage

2. Inside DITA-BigPage, I opened the app folder. Inside each subfolder in app, DITA-Reference-FM, for example, I opened the edd file in Framemaker. In this case, the edd file name was reference.edd.fm.

3. I edited the top line of reference.edd.fm.  It originally said:

Structured Application: DITA1.1-Reference-FM.

I changed it to say:

Structured Application: DITA1.1-BigPage-Reference-FM

4. I saved the EDD file. Then I opened the template file in the same folder. It was called: reference.template.fm.

5. In reference.template.fm, I first changed my page size: Format Menu > Page Layout > Page Size > Tabloid > Set.

6. Then I imported the element definitions from the corresponding EDD file:  File > Import > Element Definitions > reference.edd.fm > Click Import > Click OK to dismiss verification message.

7. I repeated the above process for all topic-type folders. For the maps types, I did not change the page size, as these will never display as topics in my online  help. I did nothing to the dtd folder.

8. Once all this was done, I opened structapps.fm.  I did the following to all Dita1.1 elements in the structure tree.

• Selected the Dita 1.1 XMLApplication element, for instance, the one named Dita1.1-Reference-FM, copied it, and pasted it underneath the original element.
• The original first few lines in the clone looked like this:
  
  Application Name: DITA1.1-Reference-FM
        Template:              $STRUCTDIR\xml\DITA\app\DITA-Reference-FM\reference.template.fm
        DTD:                       $STRUCTDIR\xml\DITA\app\dtd\reference.dtd
        Read/write Rules:  $STRUCTDIR\xml\DITA\app\DITA-Reference-FM\reference.rules.fm
        DOCTYPE:              reference
• I changed these lines to look like this, using your suggestion to create a variable for the first part of the URLs to enable speed and accuracy:

       Application Name:      DITA1.1-BigPage-Reference-FM

               Template:                    $STRUCTDIR\xml\DITA-BigPage\app\DITA-Reference-FM\reference.template.fm

               DTD:                            $STRUCTDIR\xml\DITA-BigPage\app\dtd\reference.dtd

               Read/write Rules:        $STRUCTDIR\xml\DITA-BigPage\app\DITA-Reference-FM\reference.rules.fm

               DOCTYPE:                    reference

• I also changed the "Filename" URLs in the "Entity Locations" section of this XMLApplication clone from  $STRUCTDIR\xml\DITA\app\  to $STRUCTDIR\xml\DITA-BigPage\app\.  Applying the "BigPage" variable I'd created for this purpose made this go quickly.

Finally, after this didn't work the first few times I tried it, I got suspicious that the structapps.fm file in my AppData folder (in my case, it was in the Roaming subfolder under the usual Adobe directories) was overriding the modified structapps.fm file in the Framemaker program directory so I replaced the one in AppData (it had all the original settings) with my modified version.  This had no effect, unfortunately.

That was my process. After doing the above, the Dita1.1-BigPage applications all listed in the Set Structured App drop-down. They just didn't work,when applied to my XML documents. Nor did the application "remember" what structured application I had set when I opened a new xml document  or closed/reopened the current document or closed/reopened the application.  Did I place the directories correctly for Framemaker 10?  This is the way I did it for FrameMaker 9 and it worked successfully.

----------------------------------

As much as I'd love to solve this mystery, I've thought of a workaround I can fall back on  that doesn't involve using a cloned application.  I will change the page size of a few of the original Dita1.1 sturctured application templates to tabloid size, but leave the Topic structured application at letter size. I'll then apply the Topic structured application to my PDFs and use the others for my help topics.  I'll set this up now. If this doesn't work, then I'll know there's a much bigger problem at the base of this, perhaps even something to do with changing page sizes in templates.

[ScottPrentice]

Hi Nina...

Your process looks spot-on to me .. and since you're now seeing the app names in the Select Structure App dialog, it now seems to be registered properly. If you're selecting the BigPage app when opening the file, but it's not appearing to be applied, something is still a bit wonky. Unfortunately, the FM10 app mapping process is a bit convoluted and seems to be doing some "magic" on the back end.

One thing you can do to determine which app has really been applied to the file, is to use the Structure Tools > Export Element Catalog as EDD command. If you do this and see your BigPage app name, you'll know that it is actually your app. This is a common mistake people make by not updating the app name in the EDD (but you list that in your steps, so that should be OK).

Another test you can do regarding page size is to go in and modify the template for the default FM DITA app. Be sure to back up that tempalte before changing it, but this will be one way to see if there is a fundamental problem with changing the page size.

Your concern about *which* structapps.fm file to use is warranted. In general, you should be editing the one in the "appdata" area. This is the one that opens when you choose the Edit Application Definitions command. However, I have seen a handful of cases where it just isn't working as expected, and you have to copy the one in appdata over the default one in the main FrameMaker program structure. (Be sure to save a backup of the original file.)

Personally, I think you're best off using a Composite app that lets you work with a single app for all topic types. It's just a lot of a hassle to work with multiple apps. Also, when it comes time to generate a book, I honestly don't know what's going on behind the scenes with the default FM-DITA process. If you've got a map that includes various topic types, does it swap in the Composite app so they can all be accommodated in a single file? What happens if you build a book from a map that includes a topic type that's not supported by the Composite app .. how does it merge those into a single file?

This is one of the reasons why the DITA-FMx process has a separation between the authoring and publishign structure applcations. The "Topic" app is a composite app for all topic types (DITA 1.1) .. this is used for authoring and has no special page-based formatting (since you really shouldn't be thinking about print output while authoring). The "Book" app is a composite app that has all of the print layout formatting. The two worlds are compltely separate. For default FM10 DITA, I *think* the book generation process uses the topic apps for the layout and formatting, but it's doing a bit more work as well to pull the various topic types together in one file .. this seems likely to result in unexpected layout problems.

Sorry I can't be of more help. Do let us know what you end up doing!

...scott

[Guest]

"Your process looks spot-on to me .. and since you're now seeing the app names in the Select Structure App dialog, it now seems to be registered properly.If you're selecting the BigPage app when opening the file, but it's not appearing to be applied, something is still a bit wonky. Unfortunately, the FM10 app mapping process is a bit convoluted and seems to be doing some "magic" on the back end".

Well, this is the weird part. In FrameMaker 10, when I open a topic, I never see the pop-up "set structured app" dialog. That never appears for me, although it always appeared in FrameMaker 9.  Instead, I open my document then go to the Structured Applications menu, and select "Set Structured Application" from there. 

One thing you can do to determine which app has really been applied to the file, is to use the Structure Tools > Export Element Catalog as EDD command.

Ok, opening my test document and trying this. It automatically opens with the wrong structured application selected. So I open the Structure Apps menu, select Set Structured Application, and change the selected DITA1.1 application to a DITA1.1-BigPage  application. The page size does not change, as it should. Then I save the file. Then I export element catalog as an EDD. It says Dita1.1-BigPage-Composite-FM on the exported untitlted EDD, however, despite the fact that the xml file did not change its page size.  If I close this saved xml file and reopen it, export the element catalog as an EDD once again, I find that Dita1.1-Composite-FM is what is on the first line of the exported EDD. It's changed back.

Another test you can do regarding page size is to go in and modify the template for the default FM DITA app. Be sure to back up that tempalte before changing it, but this will be one way to see if there is a fundamental problem with changing the page size.

I did this as part of my "Plan B."  It worked beautifully. The original template is read, and it is tabloid size, so my documents resize to tabloid size.

Your concern about *which* structapps.fm file to use is warranted. In general, you should be editing the one in the "appdata" area. This is the one that opens when you choose the Edit Application Definitions command. However, I have seen a handful of cases where it just isn't working as expected, and you have to copy the one in appdata over the default one in the main FrameMaker program structure. (Be sure to save a backup of the original file.)

Ok, that is covered. Both the structapps.fm files have my "BigPage" modifications now, and I have an original named something else. But it did me no good.

Sorry I can't be of more help. Do let us know what you end up doing!

No problem. FrameMaker 10 apparently works differently than FrameMaker 9 and for some reason will no longer recognize a simple cloned structured application.  I suppose if I dug into the specialization documentation I might be able to figure out why this so, but I've browsed that documentation in the past and it is a bit above my head at this point. I don't have a long time to spend trying to figure it out. 

What I ended up doing was my workaround, described in the earlier message. I modified the original DITA1.1. templates to be "BigPage" (tabloid) size, but left one template, topic.template.fm alone.  I am not single sourcing. My PDF content is separate from my online help content, so this works for me. I found that with a bit of wrapping/unwrapping of various top-level elements and the addition of an ID, I could make my older PDF source files (most were concepts under a DITA element) work well with the unmodified Dita1.1-Topic-FM structured application. I imported my PDF styles into that template as well, and everything looks good. I haven't yet compiled a book, however. If I run into issues at that point (as you suggested I might), I'll post an update. 

---------------------------------------

By the way, a bug cropped up at ID-assignment point. When I added a topic element under my DITA element in a PDF source file, this topic element required an ID.  I couldn't get FrameMaker 10 to automatically assign an ID to a top-level (topic) element I added to the document's structure, even though it was required. Whether or not the Dita Options dialog's "Auto Add IDs if Required By Element" box is checked or unchecked (and the Adobe documentation, paradoxically, says to uncheck it--which seems the opposite what you should do), no IDs are ever auto-assigned to that topic element. I experimented with unchecking the box, adding the topic element, saving the file and getting the "Need an ID" validation message, and then repeating the process with the box checked. I still got the error message no matter which way it was set.  I have to assign required IDs manually. I'll be reporting this  as it does seem like a genuine bug or possibly a doc bug. If there are exceptions to when "Auto Add IDs if Required By Element" works, these exceptions should be documented with the command, but currently no exceptions are listed.

Thank you again for taking all this time,with me, Scott.If nothing else. I've learned a lot more about FrameMaker 10 than I knew when I first posted my question. I'm now a lot more comfortable with the interface and other changes. Also, I believe if I hadn't walked through the broken cloning process with someone else, the workaround wouldn't have occurred to me.

[ScottPrentice]

Ah .. if you're not seeing the "Select Structure Application" dialog .. it's still not registered properly. FM10 added an extra layer of processing to this, and I don't recall what it is. It should work, but something is missing. I'll try to mess with this next week and see what I can find.

I don't think the specialization docs will help much, but it's worth a try. It sounds like your "Plan B" is the way to go.

As for the ID issue .. you might check the underlying EDD to see if the @id attribute for that element is *actually* required. Because you're working with multiple apps and multiple EDDs, it may work in one but not in the other. I've not seen that, but that's because I'm not using the default FM10-DITA support.

Cheers!

...scott

[Guest]

"Ah .. if you're not seeing the "Select Structure Application" dialog .. it's still not registered properly. FM10 added an extra layer of processing to this, and I don't recall what it is. It should work, but something is missing. I'll try to mess with this next week and see what I can find."

Thank you, Scott. I would really appreciate that. 

Regarding the ID issue, I checked some  EDDs.  In the app I am using the for the PDF files (topic app) an ID is required for the topic element.  I also checked the Reference element in the Reference EDD. It is required,too.