XMetaL Tips and Tricks

XMetaL Community Forum XMetaL Tips and Tricks Info: Customizing document templates for efficient writing

  • Su-Laine Yeo

    Info: Customizing document templates for efficient writing

    Participants 1
    Replies 0
    Last Activity 13 years, 9 months ago

    An easy and quick way to boost author productivity is to customize the templates that authors use when creating new documents. By including the markup that writers should most often use, and by adding instructional text to templates, you can help to ensure writers get onto the right track, and can save them time. Customizing templates requires no programming skills – If you can edit documents using your DTD or Schema, you can customize templates.

    When you click File > New in XMetaL Author, the dialog that appears is fully customizable. Each tab in the dialog corresponds to a folder in your Program FilesXMetaL x.xAuthorTemplate folder, and each icon in a tab corresponds to an XML file in the folder. For example, see how the names of tabs and icons in the dialog below are mirrored in the folder structure below.

    You can edit the options in the File > New dialog by editing, adding, and deleting files in the Program FilesXMetaL x.xAuthorTemplate folder. Before you start changing this folder, back it up by copying it to a different location. Now you can delete all files and folders in this folder that you don’t want writers to use as new document templates, edit the ones that you want to keep, and add new ones if you wish. You can have more than one template for each document type! For example, you could have a “Full Task” template with elements for a task Prerequisites, Steps, Postrequisites, and Result sections, and a “Simple Task” template with only the Steps section.

    Editing a template file
    Here are some examples of things that you might want to change in a template file:

    • Add the elements that writers frequently need. Remove the ones that they don’t frequently need.
    • For the elements that you include, set attribute values to be the values that you use most often. For example, if most DITA Reference topics should include an image that is on its own line and centered horizontally, edit your Reference topic template to include .
    • Add instructional text as placeholder text. Placeholder text, which usually appears as dark blue text on a light blue background in Tags On and Normal views, is visible to authors in XMetaL but is not visible in output. It is a type of XML processing instruction. To edit placeholder text, switch to Plain Text View. Placeholder text appears in green in Plain Text View.
      For example, if the default placeholder text for the DITA element is “Short Description”, it will appear as in Plain Text View.
      To change this to say, “Short Description (optional but strongly recommended)”, edit the green text to be, . When you switch back to Tags On or Normal Views, you will see your changes as blue-on-blue placeholder text.

    Note that some elements have required attributes or subelements that you would probably do not want to include in templates, even though documents created using that template would fail XML validation until the author adds the required attribute. For example, if you include an element in your template, you would generally not want to include a “href” attribute for it. If your templates do not include required markup, make sure your authors know how to add the required markup, and that they can expect validation errors if they try to save a file without it.

    Saving a DITA template file
    If you are using XMetaL’s default settings for DITA documents, some elements are automatically given element IDs, which should be removed from template files so that you do not get duplicate IDs in new documents. XMetaL has a macro that will save DITA topics without element IDs.

    To run the macro to save a DITA template:
    1. Click Tools > Macros
    2. Select DITA Configuration: Save Copy as Template
    3. Click Run.

    Saving a non-DITA template file
    For non-DITA documents, use the File > Save or File > Save As command to save your document to the Template directory. If you have any scripts that automatically insert metadata (such as element IDs) that you do not want to include in every new document, you might want to open each template file using a plain text editor in order to remove the unwanted metadata.

    Distributing templates to writers
    Once you have set up your C:Program FilesXMetaL x.xAuthorTemplate folder optimally on one machine, you can copy it to the same path on other machines. XMetaL will automatically present those templates when the author clicks File > New.

    Free sample
    The attached package includes a DITA Reference topic template that uses a 2-column Normal table instead of a 3-column Properties table. Note that you must be logged in to XMetaL Community Forums in order to download files.

    New document templates vs. element insertion templates
    Note that editing a new document template does not affect what is inserted when you insert an element into an existing document. You can, with some limitations, customize what is inserted when inserting a new element by customizing the .ctm file for the document type. You can edit .ctm files using XMetaL Developer or any text editor.


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

Lost Your Password?