DITA specialization bug?

[txvia]

I am trying to add specialized elements following a guide entitled “How to make changes to DITA DTDs” by creating a mod and an ent files, as well as integrating the elements into ditabase.dtd. However, for some reasons, no matter how hard I tried, I could only get three specialized elements to appear on the element list, and the fourth, the fifth, the sixth, never appeared. I deleted some in the mod and ent files and limited to three elements, that worked fine; however, if I want to add the fourth or the fifth element into the mod file, that does not work. After so many unsuccessful endeavors, that led me to think that there may be a bug in DITA OT that sets limit to three specialized elements, is that true? Could someone help? Thanks.

I am using XmetaL Author Enterprise 6.0 SP1

Reply

[Derek Read]

The DITA Open Toolkit does not come into play when authoring in XMetaL Author Enterprise. The product uses its own XML validating parser to list the elements allowed at any particular location (by reading the DTD).

There must be something odd about the DTD you have coded that is causing this issue. It will be necessary to see the DTD to help further.

Reply

[txvia]

Hi Derek:

  Thanks for the quick reply. I am attaching my mod, ent, and modified ditabase.dtd files for your reference.

  Basically what I wanted to do was to insert 5 newly created specialized elements that were modeled after 5 existing elements from the Programming Domain, I guess you can call them child elements. The reason why I did that was to make sure they would retain the same formatting styles of their parent elements.

  I created a new domain called “txvia” and the 5 new elements I created were:

  artifact
  changeset
  model browser
  txadmin
  txconsole

  Of course I integrated them into ditabase.dtd. And when I opened a new doc in XmetaL using ditabase_ditabase.dtd in “C:Program FilesXMetaL 6.0AuthorDITAXACsditabase” (in Windows XP), I only saw 3 of the 5 elements on the element list. And even as an experiment, I deleted the ones that didn't appear and recreated them, to no avail. Could you tell me what's wrong?

Do you need to do Tools -> Select Specialized DITA DTD before you start open a new doc with the new dtd?

I am attaching the files I created for your reference, thanks Derek, appreciate it very much!

Reply

[Derek Read]

This does not appear to be a proper DITA specialization. You are modifying the ditabase.dtd directly and I would not recommend modifying any of the standard DITA DTDs. What really should be done is to create a new DTD, usually similar to one of the other main topic types (such as topic.dtd) then reference your MOD file from there. You will then also create a new PUBLIC id to use in any XML documents you create based on the DTD so that software (XMetaL Author Enterprise and the DITA Open Toolkit, possibly others if you use those) can locate the DTD using their catalog lookup mechanisms.

If you need help with creating a specialized DTD I would recommend Eliot Kimber's tutorials on specialization here: http://xiruss.org/tutorials/dita-specialization/

Once you have a valid specialized DITA DTD you should use the “Select Specialized DITA DTD” option to make XMetaL aware of your DTD. This portion of the steps are described in the help topic Working with DITA > DITA Specializations.

Reply

[txvia]

Hi Derek: Thanks for your quick reply; I did read through Eliot Kimber's guide, and created a fresh DTD and referenced my mod from there. The problem is by doing what you suggested did not allow my new elements to inherit formatting styles from their parent elements, if you know the cause of that and are willing to share, I'd appreciate it.

Reply

[Derek Read]

That is likely because you skipped the step “Select Specialized DITA DTD”.

When you do that XMetaL duplicates the “customization” files (including styling) that it ships for use with the standard DITA DTDs. If you skip that step then XMetaL will treat your DTD as non-DITA and as a result it will not locate any of the customization files that are required for authoring to a specific DTD (because you have not provided any). It will then generate those using another process (a process that is used for people using the product for DTDs other than DITA if they have also not used XMetaL developer to create their own customization files).

Why is this? It is because XMetaL Author can be considered to be a platform for authoring to any DTD (or W3C Schema). Companies use it as a platform for authoring to their own custom DTDs but when they do this they provide their own customization files (created using XMetaL Developer). For DITA we provide the DITA customization files for you so you don't need to build a DITA authoring customization. However, in order for XMetaL to know that you want a DTD to be treated as DITA (and enable the DITA authoring functionality) you need to tell it that using the “Select Specialized DITA DTD”. I think (and have been told by other clients) that all of the steps in the help are quite clear.

Reply

[txvia]

Thanks for the reply Derek, I'll try what you said again and let you know.

Reply

[txvia]

Hi Derek, one more question: Now that I have created a freshly new DTD, an .xml template, a mod, and an ent file by following the instructions detailed in “DITA Configuration and Specialization Tutorials.” Now how do I get it to look like the default “General Topic” in tag view. For example, when I open my newly created xml file (pointing to the newly created dtd, of course), it looked like this: screenshot1.jpg.

Whereas I really want my newly created file to automatically look like this when I open it in XMetaL: (screenshot2.jpg)

Note: Please attached zip files for screenshots.

I am almost there, just this is really bothering me, could you help? Thanks.

Reply

[txvia]

Here is the zip file, sorry about that.

Reply

[Derek Read]

I'm not sure what's been done but I will guess (it really should not be this hard, so I'm a little confused about the state of your machine).

The fact that the CSS looks like this means XMetaL has auto-generated one for you. We don't want that for DITA (which is why we provide the “Select Specialized DITA DTD” function). This also means that the CTM file was auto-generated and you will have no MCR file either. For non-DITA people this is where they might start to build their customization, or if they choose not to build one they would use the (limited functionality) auto-generated customization.

What this means for you is that all of the DITA functionality is likely not functional for this DTD (because these three critical files must be the ones that are put into place by “Select Specialized DITA DTD”). I suspect your combination of trying to work with the DTD without selecting “Select Specialized DITA DTD” and then later trying that, and perhaps also making modifications to the DTD (and you may have kept the same filename, etc) have made a mess of your install.

I suspect that your machine probably has a bunch of files lying around, and we really don't know which XMetaL is using (I could figure this out by looking at your machine but that would be inefficient as fixing things would still be easiest by cleaning the installation out anyway). If you do not have these menus then DITA is definitely not functional for this DTD: Paragraph, Reuse.

What I would do is to put your installation into a clean state and then start again by following the instructions that start with the “Select Specialized DITA DTD” in the documentation.

1. Shut down XMetaL Author Enterprise.
2. Remove these folders:
%appdata%SoftQuadXMetaL6.0
AuthorDITAXACs
3. Follow the instructions that include the “Select Specialized DITA DTD” step.

If that doesn't fix it then do this:
1. Shut down XMetaL Author Enterprise.
2. Uninstall.
3. Remove this folder: %appdata%SoftQuadXMetaL6.0
4. If this one exists remove it: Author
5. Reinstall.
6. Follow the instructions that include the “Select Specialized DITA DTD” step.

Reply

[Derek Read]

If you have not watched this I would highly recommend it:
http://forums.xmetal.com/index.php/topic,1164.0.html

Reply

[txvia]

Hi Derek:
  After reading and following the tutorial you referred me to, my specialization is finally working! Thank you very much for your support.

Reply

[Author]

Posts