Deploying full specialized DITA customizations to users.

[jmblachman]

I've just got a copy of XMetaL Author 8.0 and I'm trying to get it ready for my users. We have custom specializations that we created, including all of the necessary XAC files: dtd, css, ctm, templates, etc. I need to find an easy way to deploy these files to my users without them doing too much work, but after reading the help documentation, the forums and the web I've only found 2 ways to “deploy” specializations, and both of them don't seem great.

The first, clicking “Select Specialized DITA DTD” for every user for every DTD just doesn't seem feasible. I can't ask my users to all run this. They won't know how to do it and it's very error prone. The only other way I found was some sort of manual file editing and copying such as what is stated in the help: Working with DITA > DITA specializations > Deploy a specialized DITA cusomization. That also seems unmaintainable. What's stopping anything from being clobbered? How do we ensure we're writing the files in the correct format?

I've read the Xmetal Developer Customization Guide (version 6.0 is the latest?) but haven't found anything useful or different. I feel that I'm missing something simple as this seems like an issue that many companies probably face. Is there any way to do what I'm looking for?

Thanks.

Reply

[severin.foreman]

I have a similar situation at my company. I agree that using Select Specialized DTD is not an option for medium to large sized teams.

What I do is bundle all the customization files in a .zip. I wrote a DITA OT plugin to retrieve the .zip from a shared network location, extract the files, and copy the files to the appropriate locations. Becuase the files in the .zip are in the same folder structure as the files in the XMetaL installation, everything is copied to the correct location. I developed a .bat script to call the plugin, so when I release updates, all writers need to do is run the .bat file.

It was a fair amount of work to set up and test, but it has worked well for the team. You might be able to acheive the same ends using a .bat script or some other scripting language if you don't want to use an OT plugin.

Reply

[XMetaLOldTimer]

I agree this is all rather clumsy and JSCI would like to simplify this process, hopefully sooner than later.  From Severin's solution description, the development investment needed can be rather significant.

We have custom specializations that we created, including all of the necessary XAC files: dtd, css, ctm, templates, etc.

Can you tell me what is custom about them?  Did you extend the menus, CSS styling or CTM mini-templates? 

The only other way I found was some sort of manual file editing and copying such as what is stated in the help: Working with DITA > DITA specializations > Deploy a specialized DITA customization. That also seems unmaintainable. What's stopping anything from being clobbered? How do we ensure we're writing the files in the correct format?

All files are in text format.  None of the files in that procedure, except “dcspecialized-typemods.ent”, are included with the XMetaL installer.  btw, the “dcspecialized-typemods.ent” step could be skip if you never use the “Reuse.Create_Reusable_Component…” or “Reuse.Insert_Reusable_Component…” actions.  So, there should not be any clobbering of files unless somebody did a “Tools.Select_Specialized_DITA_DTD…” action previously on a given CPU. 

If you have a mix of 32-bit and 64-bit Windows systems or XMetaL is installed on different hard drive volumes, I recommend a slightly altered “Deploy a specialized DITA customization” procedure.  Instead, run the following procedure:

(1) Place all your specialized DTDs into the “C:Program FilesXMetaL 8.0AuthorDITADITA_1.2_DTD” folder.  This ensures that the shell DTD (e.g. C:Program FilesXMetaL 8.0AuthorDITAXACs1.2faqshellfaqshell_ditabase.dtd) XMetaL generates has a relative-path.

(2) Launch XMetaL

(3) Execute the “Tools.Select_Specialized_DTD…” action for all the specializations you intend to deploy.  Choose from the DTDs you placed into the “C:Program FilesXMetaL 8.0AuthorDITADITA_1.2_DTD” folder.

(4) Quit XMetaL.

(5) Using Notepad or similar, hand-edit “C:Program FilesXMetaL 8.0AuthorRulesdita12_specialized.soc” so that it denotes a relative-path each catalog entry instead of the a full-path.  This allows for variation in the XMetaL installation location (e.g. C: vs D: or 32 vs 64 bit Window Program Files folders).

(6) Create a zip rooted in the Author folder with the following files and check that folder paths are remembered:

  C:Program FilesXMetaL 8.0AuthorDITAXACs1.2dita_xac_catalog_specialized.xml
  C:Program FilesXMetaL 8.0AuthorRulesdita12_specialized.soc
  C:Program FilesXMetaL 8.0AuthorDITAXACs1.2{specialization1-base_sys_id}*.*
  C:Program FilesXMetaL 8.0AuthorDITAXACs1.2{specialization2-base_sys_id}*.*
  etc.

“dita_xac_catalog_specialized.xml” affects conref, xref and other reuse operations along with the Map Editing.
“dita12_specialized.soc” is used to load up the right DTD and related customization files.  “dita12.soc” refers to this file.

(7) Copy zip to “Author” folder on each desktop and extract.

Regards,
Addam

Reply

[jmblachman]

This is a very circuitous process, but it's exactly what I'm looking for and it works perfectly. I see now that every file that gets created/edited by “Tools.Select_Specialized_DITA_DTD…” is separate from the standard install, so it won't clobber anything. Thank you.

Reply

[barbwire]

XmetalOldtimer, I think that your solution probably works, but it is very complicated. In “real life” there is much better solution for this, which is pretty simple and easy to do. 🙂 You just have to edit dita*.soc, nothing else.

Reply

[XMetaLOldTimer]

Yes, it is too complicated. 

But I caution you that problems will occur if you only change the .soc file.  The MapEditor and conref resolution features use 3rd party XML processors.  These processors don't support .soc catalog resolution mechanisms.  Instead, our code temporarily changes the doctype's system id so the DTD resolves properly.  In order to do this, our code requires this file be changed as mentioned in step 6:

“dita_xac_catalog_specialized.xml” affects conref, xref and other reuse operations along with the Map Editing.

Reply

[barbwire]

Yes, it is too complicated.  

But I caution you that problems will occur if you only change the .soc file.  The MapEditor and conref resolution features use 3rd party XML processors.  These processors don't support .soc catalog resolution mechanisms.  Instead, our code temporarily changes the doctype's system id so the DTD resolves properly.  In order to do this, our code requires this file be changed as mentioned in step 6:

“dita_xac_catalog_specialized.xml” affects conref, xref and other reuse operations along with the Map Editing.

Not necessarily (I am not saying, that this cannot happen). People use XMetal in very various ways, like with CMS. This leads in very different working styles, were XMetal provided DTD's are not used at all and therefore step 6 mentioned files do not require any modifications. With 8.0 (and with my case) I just needed to modify that .soc file and everything seems to be working.

Reply

[Author]

Posts