The Project Converter

This tool converts the now-obsolete project files created with Help+Manual 3 (.hm3) and 4 (.hmx) to the current Help+Manual XML format. It also has a command line interface so that you can convert multiple files with batch files. See Project converter syntax in the Command Line Options chapter for details.

You can convert old projects directly by opening them. Just click on the File menu, select Open, choose the project type you want to open and follow the instructions displayed. This will also give you the option of opening the external converter program.

You can also open the Project Converter manually by selecting it in the Help+Manual program group in the windows Start menu. This gives you more control over the conversion options.

How to convert projects

1.Select the File menu and click on Open.

2.Select the project or help file type you want to convert, then navigate to the file and select it.

3.The following dialog is displayed:

Convert and open:
Automatically converts the project to the compressed, single-file .hmxz format, storing it in the same directory as the original file. The converted project is then loaded for editing automatically. If you choose this option no additional options are displayed.

Start external converter:
Opens the external Project Converter program providing additional options, particularly for Help+Manual 3 (see below).

You can also start the Project Converter directly by selecting it in the Help+Manual program group in the Windows Start menu. See also Project converter syntax for information on running the Converter from batch files to convert multiple projects.

Using the external Project Converter

When you use the external converter you can choose the project file format (compressed single-file format or uncompressed XML) and configure the Help+Manual 3 conversion settings. See also Project converter syntax for information on running the Converter from batch files to convert multiple projects.

Project file format:

First you must choose whether you want to export to the compressed .hmxz single-file format (default) or uncompressed XML (a directory of individual XML project files).

•Uncompressed XML is only available in the Professional and Floating license versions of Help+Manual. This format is required for multi-user editing.

•If you choose uncompressed XML you must choose an empty directory for the output files. This is necessary because this format consists of several folders with individual files for all topics and other project components.

Help+Manual 3 conversion settings

If you are converting a Help+Manual 3 project the following additional options will be displayed in the next screen of the conversion wizard:

Convert tables to auto-size:	This converts the fixed-size Version 3 tables to dynamic tables that will automatically resize to fit the help viewer window. Note that this option makes the widths of all columns in your tables variable – they will adjust automatically on the basis of their content. Don't activate this option if your project contains tables with explicitly defined column widths as it may cause formatting problems! (For example if you use tables as a formatting tool.)
Convert only last column to auto-size:	This has the same effect as the previous option but it only makes the last (rightmost) column in the table variable. This is the most flexible table conversion option.
Concatenate similar tables:	In Help+Manual 3 it was often necessary to split tables to control formatting properly. In PDF and printed manuals Help+Manual now splits tables automatically at page boundaries and can also automatically generate headers on each page so manual table splitting is no longer necessary. This option can identify similar tables in your topics and automatically join them together to create a single table that is more easy to handle.
Tolerance for column width differences:	Defines how closely matched the columns of tables have to be to be combined with the Concatenate function. Two tables will only be combined if all the widths of all their columns are within this tolerance. Increase this value if your tables contain manually-adjusted column widths with slight variances.
Try to recognize styles and format converted text with styles:	If this is selected the Converter will attempt to identify styles applied to the text in your .hm3 project. It will create new style definitions for these styles and apply them to paragraphs formatted with these styles in the old project. Please note that this process cannot be perfect because style names in Help+Manual 3 projects did not have a very close association with text and paragraphs. All the formatting of your text will be converted correctly but you may find that some paragraphs are associated with the Normal style instead of a newly-defined style matching the old formatting.

Invisible topics from obsolete Help+Manual project formats (HM3 and HM4)

If your old HMX or HM3 project contains "invisible topics" (topics without TOC entries) they will be moved to a sub-folder called Topics\Invisible in the Topic Files section in the Project Explorer.

Automatic Converter:

When you use the automatic converter a chapter called (Former Invisible Topics) will also be created at the bottom of the converted project's Table of Contents (TOC) section.

These TOC entries are linked to the topic files of the former invisible topics but they will still not be included in your published output because their include options are automatically set to "None".

You can delete the (Former Invisible Topics) chapter by selecting it and pressing DELETE. Before confirming, deselect the option Also delete referred topic files to keep the actual topic files.

External Converter:

When you use the external converter program you can decide what you want to do with your old invisible topics:

Add invisible topics to TOC creates the (Former Invisible Topics) chapter described above. We recommend deselecting this option.

Keep organization structure creates sub-folders in the Topic Files section to match your folder structure in your old project. You can create a maximum of 10 levels but the converter will not create more levels than the original project contained.

Help+Manual 5 and 6 projects do not require conversion

The Help+Manual 5 and 6 project formats have the same file extensions as the current version and are directly compatible with Help+Manual 9. They do not require conversion and can be opened directly.

Avoid editing current projects with earlier versions

You can edit Help+Manual 9 projects with versions 5 and 6 but it is not recommended. Any features not supported in the earlier versions will be stripped out when you save there.

Editing teams should all use the same version

Similarly, if you are working on projects in a team, it is essential that all team members should use the same version of Help+Manual. All members should also have the same update installed, so that their builds are really all identical.

About converting Help+Manual 4 projects

Help+Manual 4 .hmx projects are converted 1:1 without any restrictions or limitations. All version 4 features are supported in the current version of Help+Manual – you will not see any formatting or functional changes.

About converting Help+Manual 3 projects

Help+Manual 3 did not have dynamic styles and its table formatting options were quite limited. In addition to this the code of the HTML templates used for HTML-based output formats has changed considerably and if you have made any additions of your own you will have to add them again manually after converting.

Styles:

If you select Convert Styles in the options (see below) the Project Converter will try to identify the styles used in your HM3 project and replace them with dynamic styles. This is only possible with text explicitly formatted with styles in the HM3 project – the formatting of manually-formatted text will be converted but it will not be associated with a defined style.

If the style of a paragraph cannot be identified uniquely it will be assigned the Normal style. Its text formatting will converted correctly but it will be applied manually. The result will be a paragraph with the Normal style containing manually-formatted text.

Tables:

Tables in Help+Manual 3 were fixed-width only and they were often split into multiple tables to handle page break problems in PDF and printed manuals. The Project Converter has options for dealing with both of these issues (see below) but because of the differences between the two table formats you may need to make some manual corrections to your tables after importing.

Customized HTML templates:

The HTML templates have changed considerably since version 3, so it is not possible to transfer custom code from your .hm3 projects when they are imported – the risk of mangling the resulting code would be too great.

If you have entered custom code in your templates you will need to re-enter it manually in the templates of your project after conversion.