DITA and XMetaL Discussion

XMetaL Community Forum DITA and XMetaL Discussion Distributing XMetal Customization

  • MFerris

    Distributing XMetal Customization

    Participants 3
    Replies 4
    Last Activity 7 years, 11 months ago

    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:

    [u]Deploy a specialized DITA customization[/u]
    You can configure additional installations of XMetaL for use with your specialized DITA customization.
    1. Copy the folder containing your specialized DTD (for example, ..XMetaLAuthorDITAXACs1.2faq_shell)
    to the target machine.
    2. Copy the reusable components file,
    ..XMetaLAuthorDITAXACs1.2ditacomponentdcspecialized-typemods.ent to the target machine.
    dcspecialized-typemods.ent does not exist in that given file location
    3. Copy the XAC catalog file, ..XMetaLAuthorDITAXACs1.2dita_xac_catalog.xml, to the target machine.
    4. Copy the specialized template (for example, ..XMetaLAuthorTemplatesDITAFAQ.xml) to the target
    5. Copy the rules catalog file, ..XMetaLAuthorRulesdita12.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 XMetaLAuthorRules folder contains NONE of my files. All my .ent/.mod/.dtd files are in C:ProgramDataSoftQuadXMetaLSharedDITA_OTdtdtechnicalContentdtd 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 :).



    Reply to: Distributing XMetal Customization

    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.


    Derek Read

    Reply to: Distributing XMetal Customization

    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 AuthorDITAXACsn.n
    2. Copy the reusable components file AuthorDITADITA_n.n_DTDdcspecialized-typemods.ent
    3. Copy the XAC catalog file AuthorDITAXACsn.ndita_xac_catalog_specialized.xml
    4.  If you created one or more templates copy them to the same folder you saved them in inside AuthorTemplate
    5. Copy the rules catalog file AuthorRulesditann_specialized.soc (e.g. dita12_specialized.soc).


    Derek Read

    Reply to: Distributing XMetal Customization

    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: [url=http://www.slideshare.net/XMetaL/deploying-schemas-and-xmetal-customization-files]Deploying Schemas and XMetaL Customization Files[/url]

    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.



    Reply to: Distributing XMetal Customization

    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


  • You must be logged in to reply to this topic.

Lost Your Password?