• Getting Help
• Forums
• Help Resources
• News

• ---

• Articles
• Tutorials
• Online Documentation
• Email Us

Project Configuration with XML Skins

By Tim Green
April 28, 2009

Original article link

FULL PROJECT CONFIGURATION WITH CUSTOM XML SKINS

Help & Manual's skins have a very powerful undocumented feature: Provided you compile from the command line, you can actually use ordinary .hmxp configuration files as skins. This makes it possible to overload (replace) any of the settings in your project with alternative settings for individual builds. Multiple skin files can also be "chained" in the command line, so you can combine these configuration skins with standard skins containing alternative HTML templates, baggage files and so on.

This enables things that are not normally possible for individual builds, like replacing all the images in your project with alternative versions, changing any of your PDF settings or changing some or all of the help context numbers in your project.

Get an XML editor

Even if you do all your HTML editing with Notepad, get an XML editor for this work. This will make it much easier to identify and copy the configuration settings in your skins and you will save time because you'll make fewer mistakes that are difficult to locate.

XMLPad 3 from WMHelp is completely free and does everything you need for this work, so download and install it before you start: http://www.wmhelp.com/xmlpad3.htm

XMLPad and other good XML editors display the sections in your project file as a directory tree that you can manipulate directly, rather like the TOC in Help & Manual:

INSTRUCTIONS

Using custom XML skins is quite a simple process once you get the hang of it. You just need to create an empty project file with the extension .xml, copy in and edit the configuration settings you want to change and then reference the file in the command line when you compile your project. Using an XML editor makes identifying and copying the correct sections and settings from your project file much easier than manual editing, where it is all too easy to lose track of which closing tag is closing which section.

Let's assume you want to replace all the images in your project with alternative versions. You do this by creating a copy of your images folder containing the alternative versions, which must all have the same names and the same dimensions as the originals. Then you use an XML skin to change the Project Search Path to point to the alternative graphics folder.

STEP 1: CREATE THE XML SKIN FILE

Using an XML editor or a text editor create an empty framework file with the following contents and save it in your project folder with the extension .xml. You could also save it with the extension .hmskin, but that makes it more difficult to edit with an XML editor (which won't know the .hmxp or .hmskin extensions) and you also don't want to mix it up with your regular skins. The .xml extension is the best choice here.

Basic framework template for an XML skin file:

Note the isskin="true" value, which identifies the file as a skin – this is not absolutely essential but it's good practice. The project config-group is included here because that's where we're going to insert our setting for this example.

Warning: When creating XML skins you shouldn't include empty sections. Only include those sections where you are actually going to add settings! Empty sections can sometimes delete settings in your project.

STEP 2: COPY THE SETTING FROM YOUR HMXP FILE

Make a copy of your .hmxp project file and open it in an XML editor (change the extension to .xml to make this easier). If your project is stored in .hmxz format you can get a copy of the .hmxp file by using Save As to save in uncompressed XML format. Alternatively you can also change the extension from .hmxz to .zip and then unzip it with a zip utility. (The advantage of the second method is that it doesn't change the original paths of your project search path, which can be misleading in this case.)

Then locate the project search path setting and copy it to the corresponding section in your XML skin file, which will then look like this:

Now you just need to edit the path (or paths) to point to your alternative images folder (or folders). Individual paths in the searchpath setting are separated by semicolons ( ; ) and must be relative to the location of the project that you are compiling. For example, you could change the setting shown above to:

This leaves the path to the project folder (.\) unchanged and switches the other images folder to a folder called images_alternative inside the project folder.

IMPORTANT: Section nesting must be correct!
The order of sections and settings in the skin file doesn't matter but the correct nesting of sections is essential, because the settings are identified by paths, which are derived from the sections. In the example above the searchpath setting is inside the project config-group, which is inside the config section:

STEP 3: PUBLISH FROM THE COMMAND LINE WITH THE SKIN

The final step is simply to compile your project from the command line (a batch file is ideal for this), including the XML skin file with the /O= skin switch, like this:

For full details of command line compiling see the chapter on the subject in the More Advanced Procedures section of the Help & Manual help.

Skinning other settings

You can use the principles from this tutorial to replace almost all the configuration options in the project file.

DIRE WARNING: Don't include multiple copies of sections – that is a recipe for disaster!

Exceptions - Don't try to skin these settings:

• Namespaces (merge projects)
  You can't change the modular projects inserted in your project in the namespaces section with an XML skin. In addition to not working, trying to do this may also have negative results. Never put any namespace settings in your skin – just leave the standard placeholder tag in the framework skin file provided above as it is.
   
• Baggage files
  Baggage files can't really be referenced like this – create a standard .hmskin skin file with Help & Manual to use alternative Baggage files. You can chain multiple skins in the command line to add Baggage or other features, like this:
  

  Code:

  /O=baggage.hmskin /O=config_2.xml

  
  IMPORTANT: Settings in the last skin referenced always have preference, so always reference your XML configuration skin last, otherwise any config settings in the other skins will overwrite the settings in your XML skin!
   
• Project file references
  Don't try to make any changes in the xi:include or project-files sections.

Skinnable settings

With the exception of the namespaces section you can overload everything inside the config section of the .hmxp file with XML skins. This also includes things like:

• Help context numbers – you can assign completely different help context numbers to all your topics with an XML skin.
• Text styles – redefine text styles for individual builds.
• Project settings – all your project settings are skinnable.
• Publishing options – this also applies for all PDF options, which are just as switchable with a skin as all your other options
• Variables – variables can be redefined with normal skins and external text files, but you can also define and redefine them with your custom XML skins.
• HTML templates – you can also skin these, but it is actually easier to do this with a regular .hmskin skin, with which you can edit the templates directly in Help & Manual. You might want to use XML skins for small template variants, however.

This is the short version of this tutorial for experienced users.

If you need more detailed instructions see the full version.

Tim Green is an experienced help author and translator. He wrote the online help of Help & Manual and is the site admin of the H&M user forum. You can reach him through his private web site http://www.it-authoring.com