Help+Manual News

TidyXML and the Roadmap to Help+Manual 7.3

This topic is all about translation of Help+Manual projects. As you know, Help+Manual saves a project in XML format, enabling external translation programs to parse the XML and translate it.

The XML code, that Help+Manual creates, however, is a bit more complicated than many translation programs would like to have it. And we are going to change this with the next update(s). I mentioned this detail in the 7.2 maintenance update already, here’s more about it. It is best explained with an example…

Please run Help+Manual and paste the following 2 lines of text into a topic:

Now let’s switch the editor to “XML View” and have a look at the XML code created for these 2 lines:

The XML colored in yellow is the code created for the two lines. These are 2 paragraphs (<para> tags in XML) and several separate text elements (<text> tags in XML). A translation program that parses the XML code, does not see the visual representation like you do in Help+Manual. It sees the XML structure only and has to make sense of it.

What makes it difficult for translation programs and translators are the <text> tags in particular. It would be much easier to read and less error-prone to translate if the XML structure was more simple and – nested. For example, the very same text could be represented by an XML code like this:

You see in the picture above, that there is just a simple <para> tag that starts the paragraph. There is not even a style attribute to it, which makes Help+Manual assume that the paragraph style will be formatted with the default style “Normal”. Text follows immediately after the <para> tag, no extra <text> tag is used here. The text will as well be formatted with the default style “Normal”, to be exact: with the same style that is already defined by the <para> tag. Just when a text part with a different style comes along, an additional nested <text> tag with modified style attributes is inserted.

This simplification of the XML code makes it much easier to translate those two sentences with an external translation program. It’s not only more compact, but the translation program doesn’t have to worry about moving plain text around. It’s just plain text between and opening <para> and a closing </para> tag. The same rule applies to links and other objects with meta information: easier to read, easier to re-group text, easier to translate.

There is just one caveat with this new more compact XML code: it is not backwards-compatible with older versions of Help+Manual. So we decided to implement it in 3 steps:

Version 7.2 (that last update out already) implemented the first step and has a modified XML reader to be able to read the simplified XML code. If you have installed 7.2 already, give it a try! Open H&M, switch to the “XML view” and paste the XML code below into the XML editor:

When you switch back to WYSIWYG view, the result should look more or less like in the first picture – depending on your own style settings for “Normal” and “Heading1”. Version 7.2, however, does not write this XML code. That’s planned for the next update.

Version 7.3 will implement an optional switch for TidyXML. We expect a relatively long beta-phase for this update and the TidyXML switch will remain off by default and can be switched on per help project for extensive testing. If you don’t do anything, Help+Manual 7.3 will behave as before. If you switch it on, it will create the new XML code.

After version 7.3, we plan to keep the switch, but might eventually switch it on by default for new projects, once the function is mature and widely tested.

Help+Manual’s XML code has been back- and forward compatible through many versions. We have introduced additional attributes, new objects and new features (think: publishing tasks) over the years, but basically, you can still open a help project created with version 7.2 with an old version 5.0 of Help+Manual. It will work, topic content is the same.

The new TidyXML format breaks this backward compatibility and the step-by-step introduction decreases the risk that people who still work with older versions will run into a problem when opening or editing content.

Stay tuned for the announcement of a 7.3 beta to test it. We will publish it in this blog.