Import options for HTML files

The importer needs to know how to deal with the different parts of HTML topic pages. You can improve the import performance with the import options settings. Always click on the Continue with Options button and check/configure the import options before proceeding.

HTML files import options dialog

Hitting the Continue with Options button brings up this dialog:

Include sub-folders and empty folders, file extensions

Where to look for files in the specified folders, and which file types to include. If you include sub-folders they will be used to create a chapter structure.

Topic header:
Getting the header information from the <title> tag will usually work. If your topics have a separate header block you may need to specify a different tag. If in doubt display the HTML file, right-click on one of its pages and examine the source code with right-click and Inspect or View Source.

Topic body:
Specify a <table> or <div> tag with a specific ID only if you know that is used to identify your body content. Otherwise use the default setting.

Single-column tables:
Some topic pages are enclosed in single-cell/single-column tables, which can cause undesirable results when you import them. You can solve this problem with the option for converting such tables to single paragraphs.

Import tags and labeled elements as anchors:
If you you know the HTML files you are importing contain tags and labeled elements with name= attributes that you want to use as anchors you can make sure that they are converted to anchors (jump targets) with this setting.

Import invisible block elements (and make them visible):
Normally block elements hidden with the display=none attribute are considered to be not part of a page. This setting enables you to import these elements and switches them to visible. (Invisible block elements are not directly supported in Help+Manual).

Ignore HTML styles and use default styles (except margins, bold, italic, underline):
Use this option if you want to import your CHM or HTML files with a "clean slate" for styles and formatting. It will strip out all styles (both CSS and inline styles) and only keep margins, bold, italics and underline. This can be particularly useful for source material that has accumulated a lot of manual formatting over time.

Overwrite existing topics:
This is only displayed when you are importing into an existing Help+Manual project. If you select it, it will overwrite any existing topics in your project with imported topics that have the same IDs. Use with caution!

Help+Manual imports styles to the project stylesheet where possible

Starting with Help+Manual 9.6, the import module identifies defined styles in your HTML files and includes them in the project stylesheet. However, this can only work well if your formatting is applied with named styles that have class names attached to the elements in the HTML, along with centrally defined CSS rules for the styles. Because of the complex and often deeply nested nature of HTML style definitions, this import process cannot be perfect, but it will generally provide a good starting point. How good it is will depend almost entirely on how systematically named styles are used in your source material.

Cleaning up your styles after importing

See Turning formatting into styles for details on turning inline formatting into a style and adding it to your project stylesheet.

See Replacing formatting and styles for details on how to do more extensive processing on styles with additional Help+Manual tools.

Tidying up inline formatting with the Premium Pack Toolbox utility

Provided style classes were used in the original HTML you can globally strip out inline formatting imported from HTML and convert it to style references with the powerful Toolbox utility included in the Premium Pack style pack.

Import options for CHM files

The importer needs to know how to deal with the different parts of HTML topic pages in the imported CHM file. You can improve the import performance with the import options settings. Always click on the Continue with Options button and check/configure the import options before proceeding.

HTML files import options dialog

Hitting the Continue with Options button brings up the dialog shown below:

Topic header:
Getting the header information from the <title> tag will usually work. If your topics have a separate header block you may need to specify a different tag. If in doubt display the CHM file, right-click on one of its pages and examine the source code with View Source.

Topic body:
Specify a <table> or <div> tag with a specific ID only if you know that is used to identify your body content. Otherwise use the default setting.

Ignore internal folders:
Help+Manual does not use internal folders in CHM files, all files are stored on the same level. If the CHM file contains internal folders the folder names will normally be prefixed to the topic IDs of the imported topics to prevent name conflicts. You can turn this option off if you are sure that there are no name conflicts caused by files with the same names stored in different folders.

Single-column tables:
Some topic pages are enclosed in single-cell/single-column tables, which can cause undesirable results when you import them. You can solve this problem with the option for converting such tables to single paragraphs.

Import tags and labeled elements as anchors:
If you you know the HTML files you are importing contain tags and labeled elements with name= attributes that you want to use as anchors you can make sure that they are converted to anchors (jump targets) with this setting.

Import invisible block elements (and make them visible):
Normally block elements hidden with the display=none attribute are considered to be not part of a page. This setting enables you to import these elements and switches them to visible. (Invisible block elements are not directly supported in Help+Manual).

Ignore HTML styles and use default styles (except margins, bold, italic, underline):
Use this option if you want to import your CHM or HTML files with a "clean slate" for styles and formatting. It will strip out all styles (both CSS and inline styles) and only keep margins, bold, italics and underline. This can be particularly useful for source material that has accumulated a lot of manual formatting over time.

Import text popups as standard topics:
Selecting this converts any text popups defined in the CHM file as regular topics by giving them the class Default. Otherwise they will be given the class Popup, which will handle them as popups on export. Whether they are treated as plain text or JavaScript popups depends on your popup settings.

Overwrite existing topics:
This is only displayed when you are importing into an existing Help+Manual project. If you select it, it will overwrite any existing topics in your project with imported topics that have the same IDs. Use with caution!

Help+Manual imports styles to the project stylesheet where possible

Starting with Help+Manual 9.6, the import module identifies defined styles in the HTML files in a CHM and includes them in the project stylesheet. However, this can only work well if your formatting is applied with named styles that have class names attached to the elements in the HTML, along with centrally defined CSS rules for the styles. Because of the complex and often deeply nested nature of HTML style definitions, this import process cannot be perfect, but it will generally provide a good starting point. How good it is will depend almost entirely on how systematically named styles are used in your source material.

Cleaning up your styles after importing

See Turning formatting into styles for details on turning inline formatting into a style and adding it to your project stylesheet.

See Replacing formatting and styles for details on how to do more extensive processing on styles with additional Help+Manual tools.

Tidying up inline formatting with the Premium Pack Toolbox utility

Provided style classes were used in the original HTML you can globally strip out inline formatting imported from HTML and convert it to style references with the powerful Toolbox utility included in the Premium Pack style pack.

Help+Manual automatically imports and integrates the styles from Word RTF files, but formatted text from HTML must be imported as "manual formatting". This is necessary because HTML formatting cannot be automatically converted cleanly into "text" and "paragraph" styles. Normally, if you want to use styles on imported formatted text you must first create Help+Manual styles on the basis of the imported formatting and then apply the styles to your text.

Converting imported HTML formatting to styles globally with Premium Pack Toolbox

Provided style classes were used in the original HTML you can globally strip out inline formatting imported from HTML and convert it to style references with the powerful Toolbox utility included in the Premium Pack add-on for Help+Manual. If you have or are considering buying the Premium Pack, see Integrating imported formatting globally for details on this.

Otherwise see the Replacing Formatting and Styles chapter for instructions.

There are no special settings for importing Markdown files, as the Markdown format is by definition extremely simple. The Markdown flavor (Daring Fireball or Common Mark) is selected automatically on the basis of the content of the file.

A set of standard styles is used to represent the basic Markdown formats.

There are no special settings for importing Winhelp files.

You will get much better results if you import Winhelp project source files (.hpj project file and other accompanying files). Compiled .hlp files do not contain all the information needed for recreating Winhelp projects.

Help+Manual does not import Adobe FrameMaker projects directly. However, you can achieve very good results by using FrameMaker's Save as RTF function. This provides all the benefits of importing Word files, including integrating your styles in the Help+Manual project stylesheet. In addition to this, FrameMaker also does a great job of exporting its compound graphics to vector-based EMF files, which Help+Manual can handle very well.

So to import a project from FrameMaker, just save it as RTF in FrameMaker, then follow the instructions for importing Word RTF files below.

The process of converting the Word files that constitute a D2H project to HM is quite straightforward and consists of only two steps:

1.Use Word to save your file(s) as RTF.

2.then use HM to import the RTF file(s), following the instructions for RTF.

The HM converter will import all formatting, styles, index entries, headings, bookmarks, cross references, links and so on and translate them into their HM equivalents. However, there are also some special considerations that are helpful when you are dealing with different types of D2H projects.

Combine your D2H files to a single file before importing

We recommend combining all your D2H Word files into a single file before importing. This will preserve the links and their targets. For full details and a lot more tips, please see this tutorial topic:

Doc-to-Help Imports

There are no special settings in the import wizard for importing RTF files. However, you do need to plan the content of your RTF files in order to get the best results.

Save your Word files in the RTF format with Word before importing

If you have RTF files that were not created with Word, always re-save them to RTF with Word before importing them to Help+Manual.

Automatic topic generation

The importer splits the contents of RTF files into topics automatically if possible, using one of two methods:

Standard Word Heading1 - Heading 9 styles:
If your RTF file uses the standard Word Heading 1 ... Heading 9 styles each heading with one of these styles will start a new topic. Subtopics will be created automatically on the basis of the heading levels.

Hard page breaks:
If your file does not use Heading 1 .. Heading 9 styles new topics are created at hard page breaks. No subtopics are created with this method.

Limiting the depth of chapter creation

You can limit the depth of chapter creation when importing Word documents with excessively complex chapter structures. You do this by specifying the maximum levels that should be converted to chapters and sub-topics in your Help+Manual project. For example, if you specify you only want the first 3 levels as chapters, all sub-topics below level 3 will be included in body of the corresponding topic.

These lower-level topics will not be included in the TOC and their headings will be rendered as normal text sub-headings in the body of the topic, along with their text.

Topic headings and topic IDs

Word files often use unfriendly IDs like ref_xxxxx or topic_xxxxx for headings. It is generally better to allow Help+Manual to convert the topic heading to an ID so that you have a more descriptive and useful ID in your Help+Manual project.

Anchors in RTF files

If the Word file contains links to anchors in topics, you may want to import the anchors as well. However, this can also create a lot of spurious anchors as well because Word files tend to use a lot of anchors for other purposes and Help+Manual cannot distinguish them from anchors used as link targets.

Hyperlinks in RTF files

Most hyperlinks in RTF files will be converted correctly but in some cases it may not be possible to resolve their targets with 100% certainty. In these cases the links will be shown highlighted in red in the Help+Manual editor so that you can check them and make the necessary correctly.

Graphics in RTF files

Graphics embedded in RTF files do not have names, they only have sequential numbers, starting with 1 in every RTF file. Help+Manual automatically generates sequential names for the graphics files combined with the first 8 letters of the RTF name, or of the project name if it is a WinHelp HPJ project. This ensures that you don't get duplicate file names for different graphics when you import RTF files to different projects.

Help+Manual supports importing Confluence projects directly.

About Confluence projects

Page structure

Confluence pages can be organized in multiple sections. These are usually columns, in which the first is always the main content. The other sections are usually additional columns next to the main section, containing things like "Recent changes", "See Also" and so on. You will normally not want to import these things and they are thus disabled by default in the import options (see further below).

Confluence macros

Confluence uses a large number of macros that also change from version to version. Help+Manual's import routines recognizes and converts most of the important macros, listing them in the import log. Unrecognized macros are converted to plain text with a warning informing you that some content may not have been imported in this location in the text.

Examples of converted macros

•Topic links

•Links to web pages

•Images with links

•Information boxes like "Node", "Information", "Warning" and so on

•Code snippets

•Lists (correspond to Help+Manual's link lists)

•Excerpts/Includes (correspond to Help+Manual's snippets)

Import procedure

Recommendation: Confluence projects are complex and larger projects can take a long time to import. We recommend experimenting with a smaller project first to see what the various import settings do in your case before committing to importing a larger project.

Step 1: Create a zipped site backup in Confluence

To get the data you need to import, you need to first use the Backup a Site option in Confluence to create the necessary package of XML files. This is explained here in the Confluence documentation:

 Confluence – Back Up a Site

Important — export individual languages separately: Unlike Confluence, Help+Manual manages multiple languages in separate projects. If your Confluence project contains multiple language versions you must export only one language version at a time and import each one to a separate Help+Manual project.

The result is a zip archive file containing a large XML file containing the project data and multiple sub-folders containing the images in Confluence's own binary format. Unpack all the contents of this zip archive into an empty folder. The XML file to import is usually named "entities.xml".

Step 2: Choose New Project and select Confluence as the import format

In Help+Manual, select New Project in the File menu, then select Confluence Project as the import format at the bottom of the screen:

Step 3: Select the Confluence project and your import location and name

In the next screen, select the Confluence XML file and choose an empty folder and a name for your new project. Then continue to the Options:

Step 4: Configure your import options

In the Import Options page you have the following choices:

Create topic IDs from titles

Recommended unless your project contains multiple languages. Activate this to make "human-readable" topic IDs based on the topic titles in your Confluence project. Turning this off generates "human-unfriendly" IDs based on Confluence's internal numeric IDs. Title-based IDs make selecting topics to link to in Help+Manual much easier when you are editing.

The exception is if your Confluence project contains multiple languages that need to be kept in sync. You will then want each language version you import into Help+Manual to have identical topic IDs, and the only way to achieve that is to use Confluence's own numeric IDs.

Import page drafts

Confluence can maintain "draft" versions of topics. If you wish, you can import these as well. However, they will become normal topics in Help+Manual, with the same status as other topics.

Import unreferenced page contents as snippets

This will import additional page content in your Confluence project as snippet topics in Help+Manual, in a separate folder in Project Files > Topic Files. In many cases this will just be seemingly irrelevant phrases that you don't really need as snippets. You should definitely experiment with this on a small project before committing to it on a larger project.

Step 5: Import the project, then save and edit

Just click on Import and wait until the process has finished. Confluence projects are complex and the analysis and import process can take quite a while, particularly if you include page drafts and unreferenced page content.

After importing you will have a regular Help+Manual project that will not yet be saved. You should select save before checking and editing the project.

About AuthorIT importing:

Help+Manual does a very thorough conversion and import of your AuthorIT project. All the following items are imported:

•All topics and snippets

•All "Books" (converted into H+M  TOCs)

•Index keywords automatically created by AIT

•Text and paragraph styles (AIT Help styles)

•Hyperlinks to topics and web pages

•Tables

•Variables (3 predefined variables and all user-defined variables)

•Topic status (converted to H+M topic status)

•Build tags (AIT Help, Web and Print tags converted to H+M build tags)

•Graphics with original file names

•Embedded pictures

•"See Also" link lists in topics

First publish your AuthorIT project to XML with the Publish To option:

To import an AuthorIT project you first need to publish it to XML using the Publish To option. This step is essential. You won't be able to import an Author IT source project directly.

Options you must set in AuthorIT:

These two options must be set as follows in your AuthorIT configuration when you publish to XML for importing to Help+Manual:

•Export embedded pictures as files:YES

•Export linked pictures as files:YES

The following option can be activated, but is not required:

•Include preview of file objects:optional

AuthorIT import options in Help+Manual:

You can then import the XML project created by AuthorIT to Help+Manual. You will be shown these options:

•Create topic IDs from titles
Recommended! Activate this to make "human-readable" IDs based on the topic titles in your AuthorIT project. Turning this off generates "human-unfriendly" IDs based on the AuthorIT numeric topic IDs. This makes selecting the correct topics for link targets etc. much more difficult if you are a human and not a machine.

•Import snippets as separate topics
By default, your AuthorIT snippets are imported as topic files with the build option "none" so that they are only used as source for snippets and not automatically exported as hidden topics when you publish to formats that support this (CHM, WebHelp, eWriter, VS Help). Activating this option sets their build option to "all builds" instead, so that they have the same status as any other topic without a TOC entry.

•Add a list of related topics
If you activate this option your "Related Topics" lists for each topic are imported along with each topic. Turn it off to exclude these lists.

You can import RoboHelp X5, X6, 7, 8 and 9 projects.

Here too, the importer needs to know how to deal with the different parts of the HTML topic pages. You can improve the import performance with the import options settings.

Topic header:
Getting the header information from the <title> tag will usually work. If your topics have a separate header block you may need to specify a different tag. If in doubt check the HTML source code of the files in your RoboHelp project.

Single-column tables:
Some topic pages are enclosed in single-cell/single-column tables, which can cause undesirable results when you import them. You can solve these problems with the option for converting such tables to single paragraphs.

Graphics files:
The graphics files from the RoboHelp project are not imported to the new project directory. Instead, Help+Manual adds the current location(s) of the graphics files to the image folders list in the Configuration > Common Properties section of your project. You can move the image files after importing if you want – just change the folder entries in the Image Folders list accordingly after doing so and Help+Manual will then be able to find them.

With the exception of RTF files (see above), text imported from external sources is all tagged as "manually formatted" with inline formatting, not with styles. You can integrate this formatting into your Help+Manual stylesheet with the Create Style from Selection and Replace Styles functions.

Provided style classes were used in the original HTML you can globally strip out inline formatting imported from HTML and convert it to style references with the powerful Toolbox utility included in the Premium Pack style pack.

For instructions see Replacing Formatting and Styles.