XMetaL Tips and Tricks
Dave Gash August 9, 2010 at 10:25 pm
Tutorial: Producing Automated, Customized DITA Documents in Batch ModeAugust 9, 2010 at 10:25 pmParticipants 0Replies 1Last Activity 11 years, 10 months ago
Tutorial: Producing Automated, Customized DITA Documents in Batch Mode
By: Dave Gash, HyperTrain ([url=http://www.hypertrain.com]http://www.hypertrain.com[/url], [email protected])
Purpose: This tutorial presents a way to automatically re-create any DITA output format in batch mode, including production of documents with modified content.
Abstract: You have DITA documents prepared with XMetaL that you need to reproduce via a DITA build, but without invoking the XMetaL GUI. Further, the documents need to be customized in terms of content and/or conditionalization. The solution is to run XMetaL's DITA build process in batch mode, and provide build-specific conref source and ditaval files for customization.
Prerequisites: XMetaL 6.0 or higher
Step 1: Create your project in XMetaL as usual.
For this example, let's assume your project is in the folder C:myproject, and that its DITA map file is called myproj.ditamap.
Create build conditions as necessary and apply them to text, topics, map entries, etc. You can find information about customizing the conditions file in XMetaL's online help system here:
Create conrefs as necessary in topics. Make sure to put all your conref data elements in one file – very important for later customization. Let's call this file customer_data.xml.
Step 2: Configure XMetaL to not delete its work files.
When XMetaL does a DITA build, it normally cleans up after itself by deleting build files and folders that are no longer needed. However, these files are exactly what you need to re-create the build.
Go to Tools > Configure Output > Advanced tab and “uncomment” a parameter. Remove _rem_ from the line _rem_cmd_synchro_mode = 2 so that it reads cmd_synchro_mode = 2. This prevents XMetaL from cleaning up the work files after a build.
Step 3: Build your project in XMetaL as usual.
Choose an output format, select any options, and set your build conditions. (XMetaL writes the DITA build conditions to the myproj.ditaval file.) Run the build. For this example, let's build a PDF document, so your output folder will be C:myprojectpdf_out. Your PDF will have all the resolved conrefs and conditionalized content as specified by the conref data file and the ditaval file. Open the PDF to make sure it's correct.
Close XMetaL. Shut it down, don't just minimize it; you won't need it for the rest of this tutorial.
Step 4: Test the batch build process with the original output.
In the output folder you will see a sub-folder called xmetal_log, and in that folder you will find the file dita_call.bat; that is, C:myprojectpdf_outxmetal_logdita_call.bat. This is the batch file you need in order to re-create the output.
To make sure you get a clean test, delete all files and folders in C:myprojectpdf_out except the xmetal_log folder. (This isn't really necessary, but for testing purposes it makes success or failure more evident.) Then open the xmetal_log folder and double-click dita_call.bat. A command window will open; let it process and close by itself.
Look in the pdf_out folder one level up; the output files should be back. Again, open the PDF to make sure it's correct; there should be no change from the build you did in XMetaL.
You should run one build for every output format you wish to customize and re-create, but we're just looking at the PDF output in this tutorial.
Step 5: Customize the content outside of XMetaL.
In the project folder, C:myproject, open the customer_data.xml file in any text editor. You can find information about good applications for editing configuration files here:
[url=http://forums.xmetal.com/index.php/topic,955.0.html]http://forums.xmetal.com/index.php/topic,955.0.html[/url]. It will look something like this:
BobCo, Inc. Aug. 13, 2010 Otto Palindrome
Manually change the conref data as desired and save the file. My examples are phrases (
), but yours could be paragraphs, tables, code samples, or nearly any element. Don't change the file name, topic ID, or element IDs, as these are already used in your project topics to resolve the conrefs.
Next, open the myproj.ditaval file in a text editor. It will look something like this:
Manually change the conditions as desired and save the file. For example, you might swap the “include” and “exclude” actions for the platform attribute values “windows” and “mac”.
These conref and condition changes should result in a significantly different output document.
Step 6: Test the batch build process with the modified output.
As in Step 4, to make sure you get a clean test, delete all files and folders in C:myprojectpdf_out except the xmetal_log folder. Then open the xmetal_log folder and double-click dita_call.bat; let it process and close as before.
Again, look in the pdf_out folder one level up; the output files should be back. Open the PDF; this time you should see different content based on your conref and condition changes.
That's the basic idea, but it's really just the setup for the good part.
Step 7: Automate the process.
You now have a template document that you can customize, conditionalize, and build programmatically, without going through the XMetaL GUI. This means you can automate the entire process to produce a specialized document whenever you need it.
In my case, I wrote a simple little app that does everything. It lets me select a customer for whom I want to produce a document, and then:
(1) retrieves the customer's information from a database, including name, contact info, product options, platform and product information, preferred output format, even customer-specific code blocks,
(2) writes the customer information into the conref data file (customer_data.xml) and the platform and product information into the ditaval file (myproj.ditaval), and
(3) executes the appropriate batch file (C:myproject[output_type]xmetal_logdita_call.bat) for the customer's preferred output.
Result: Easier to produce, more consistent, more accurate documents.
Using this technique, I or anyone in the office can quickly and easily produce a customized, conditionalized output document for any customer, without knowing DITA or XMetaL, by simply pointing the app to the customer's database records; everything else is automated. That means there are no transcription or copy/paste errors, no last-minute edits done by other authors, and no unauthorized mods to the document template topics.
Acknowledgements: Thanks to Su-Laine Yeo and Derek Read for their invaluable assistance in this effort.gran March 26, 2011 at 1:14 am
Reply to: Tutorial: Producing Automated, Customized DITA Documents in Batch ModeMarch 26, 2011 at 1:14 am
We have attribute specializations overriding @props in concepts.dtd, tasks.dtd and references.dtd along with .ent file for each attribute we define. We have registered these DTDs with our CMS system ok, however have problems when registering them in XMetal 6.0 Enterprise Author.
As per Option 3 (most flexible), we have copied our customized DTDs to following locations
C:Program FilesXMetaL 6.0AuthorDITADITA_OT_DTD
C:Program FilesCommon FilesXMetaL SharedDITA_OTdtd
When opening a DITA xml file XMetal complains with error dialog box upon startup:
“Unable to create rules file. The file C:Program FilesXMetaL 6.0AuthorDITAXACsconceptconcept_ditabase.rlx could not be created.”
followed by an error indicating our dita file could not be opened because a DTD could not be found. The DTD reference is same as standard DITA
If we open the file after XMEtal starts without loading an existing doc, it doesn't complain?? Has anyone encountered this problem?
- You must be logged in to reply to this topic.