Pages: 1
Print
Author Topic: Distributing XMetal Customization  (Read 3823 times)
MFerris
Member

Posts: 14


« on: February 18, 2015, 09:39:19 AM »

I have created a XMetal customization and DITA specialization for a project, and now need to work on distributing the files. I have looked at the XMetal 9.0 User Guide section regarding the issue but things don't add up from the guide. Here's the extract from the guide with my issues in red:

Deploy a specialized DITA customization
You can configure additional installations of XMetaL for use with your specialized DITA customization.
1. Copy the folder containing your specialized DTD (for example, ..\XMetaL\Author\DITA\XACs\1.2\faq_shell)
to the target machine.
2. Copy the reusable components file,
..\XMetaL\Author\DITA\XACs\1.2\ditacomponent\dcspecialized-typemods.ent to the target machine.
dcspecialized-typemods.ent does not exist in that given file location
3. Copy the XAC catalog file, ..\XMetaL\Author\DITA\XACs\1.2\dita_xac_catalog.xml, to the target machine.
4. Copy the specialized template (for example, ..\XMetaL\Author\Templates\DITA\FAQ.xml) to the target
machine.
5. Copy the rules catalog file, ..\XMetaL\Author\Rules\dita12.soc, to the target machine.
dita12.soc does not contain any file references to any of my specialized files.

My specialization works in XMetal (9.0), but have I done it in some obscure way? The XMetaL\Author\Rules folder contains NONE of my files. All my .ent/.mod/.dtd files are in C:\ProgramData\SoftQuad\XMetaL\Shared\DITA_OT\dtd\technicalContent\dtd among all the other ones that come default with XMetal. I have been copy&pasting them after every change made into this folder, from an independent project folder. The files that go into my XACs folder are correct though, I believe.

tl;dr: I want to distribute my specialization, but I don't seem to have structured my files in the right way.

I'd appreciate any help/feedback. Thanks in advance :).
Logged
barbwire
Member

Posts: 44


« Reply #1 on: February 19, 2015, 03:07:31 AM »

My really rough proposal (and I am sure, that Derek does not approve this... ;)):

1) Modify dita12.soc file and remove all from there.
2) Every time when user edit topic, provide topic/map related DTD or RLX to the same location than file.

So, don't do any special customizations if you distribute it to the others. :) But remember that this is just rough proposal, which may work. And remember, that if you have certain macros or for example css-files (whatever) relating to the topic, they don't work either unless you put them to the same folder than topic file.
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2621



WWW
« Reply #2 on: February 19, 2015, 11:57:02 AM »

Yes, that documentation is outdated unfortunately.

Here's what it probably should say.

"n.n" = the DITA version active at the time of doing the Tools > Select Specialized DITA DTD... operation (1.1 or 1.2).
"nn" = the same as n.n but without the literal period character.

1. Copy this entire folder <xmetal install path>\Author\DITA\XACs\n.n\<your original DTD filename>
2. Copy the reusable components file <xmetal install path>\Author\DITA\DITA_n.n_DTD\dcspecialized-typemods.ent
3. Copy the XAC catalog file <xmetal install path>\Author\DITA\XACs\n.n\dita_xac_catalog_specialized.xml
4.  If you created one or more templates copy them to the same folder you saved them in inside <xmetal install path>\Author\Template
5. Copy the rules catalog file <xmetal install path>\Author\Rules\ditann_specialized.soc (e.g. dita12_specialized.soc).
« Last Edit: February 19, 2015, 01:41:34 PM by Derek Read » Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2621



WWW
« Reply #3 on: February 19, 2015, 01:35:34 PM »

barbwire is right ;-)

For DITA, doing what barbwire suggests will fail to enable the DITA authoring functionality or perhaps partially enable it (which might be worse). It really is the wrong thing to do for distributing the files needed to configure XMetaL Author Enterprise to recognize a specialized DITA DTD, even though it is very often the right thing to do for any other schema.

Many customizations are document-level only and consist solely of DTD/XSD, CSS, CTM, optional MCR file, and perhaps a few other files (like XFT). If the DOCTYPE declaration points to the schema in the same folder then all those files will be loaded, and the customization works in that case. So, in many cases for simple customizations it is a perfectly normal method for distributing customizations. See: Deploying Schemas and XMetaL Customization Files

The DITA customization is both application-level and document-level and pretty complicated (1200+ files in about 230 folders). It supports DITA specialization, it is CMS-aware, and the authoring experience can be tailored for DITA 1.1 and 1.2 capabilites. All of these things have dependencies on each other, including the document-level customizations, and if you bypass the documented method for setting up specialized DITA (the one step where you choose "Select Specialized DITA DTD") the document-level portion of the customization for your particular specialized DITA DTD won't be created. Several files are written to during that step and they are all necessary, so distributing them all to the right location for each user in your org that needs this capability is also necessary.

So, what are you missing when DITA authoring isn't available?
  • no integration with the DITA OT for generating output
  • auto-id on elements will not work
  • CMS functionality (if a DITA-capable CMS is integrated) will likely not work
  • the Reuse menu and associated functionality for setting up conref, keyref, keyspaces, the Conditional Text dialogs, etc, will not be present
  • the ability to display "target" content inside a "source" document via conref and similar references (as above) will not be available
  • the Paragraph menu and its associated functionality won't be available
  • you will not be able to reference your specialized topic from a DITA map or another topic because the software is smart enough to check the referenced document to see if it is DITA (anything it has not been configured to recognize as DITA, via Select Specialized DITA DTD, is not)
  • support for rendering SVG in documents will be missing
  • the Insert menu and the context menu will not include any DITA-specific actions
  • the Reference Checking, Topic References and Key References features (displayed in the Results window) won't do anything
  • refreshing references (F11 or while opening a document) won't be available
  • if the specialized DITA DTD is a map then the map editor won't let you open it and so none of its special functions will be available
I'm probably missing a lot more...

Basically, if you don't want any of the DITA authoring functionality you might as well use XMetaL Author Essential and create your own very simple customization for DITA. You will need to obtain the DITA DTDs independently in that case. I wouldn't recommend this either of course, since I think the DITA authoring experience provided by XMetaL Author Enterprise is pretty valuable.
« Last Edit: February 19, 2015, 02:12:24 PM by Derek Read » Logged
MFerris
Member

Posts: 14


« Reply #4 on: February 26, 2015, 09:13:34 AM »

Thanks for the input Barbwire!

I followed those steps and have been successful in creating an installer which distributes my specialization to other work stations, thanks a lot Derek :).

Edit: New thread for separate question
« Last Edit: March 02, 2015, 08:09:58 AM by MFerris » Logged
Pages: 1
Print
Jump to:  

email us