Importing Word Documents into RoboHelp

 

 

This page is about the screens you will encounter when importing Word documents into RoboHelp 9.0.2 and above up to and including RoboHelp 2017.

If your are using RoboHelp 9, it is vital that Service Release 9.0.2 is applied to your machine as that updated the process in important ways. What is described below will not work unless that service release is applied.

If after following these instructions you still do not get the expected import, take a look at Importing Word Documents.

The process for RoboHelp 9 is the same for RoboHelp 10 and above except that in later versions you will be given the option during the import to automap the styles. RoboHelp will then match any Word styles with identical style names found in your CSS.

Best Practice

I recommend that you do not import Word documents into your carefully crafted main project. Import them into a project set up just for the purposes of importing.
- If it goes well, then import the htm files created into your main project. If losing the Word TOC or Index is a problem, repeat the process importing into your main project knowing it will not be spoiled.
- If you have problems then nothing is lost, just trash the temporary project and start again.
If you intend to create printed documentation from your project later, try it early on as problems from the import can manifest themselves there. Leave it until later and you may not make the connection between the import and the problem.

Before you start

The import process will be smoother if you first prepare the Word document, it is reliant on a properly constructed Word file and the old rule of "rubbish in, rubbish out" certainly applies here. RoboHelp is having to convert the document from Microsoft's file formats into HTML, think along the lines of mixing oil and water. Use Word to save the document in HTML format and you will see the HTML is not pure HTML and that is what RoboHelp has to deal with. So what do you need to do?

The Process

I will describe the process with a document created from a clean template (a minimal number of styles). See Downloads below if you want to test with the same document. It is short but it contains the following features:

If the objective is to get the topics created from the import to look the same as existing topics in the project, you will want to use your own CSS. See Step 7 below before you start importing.
If the objective is to retain the appearance of the document, ignore the mapping process described in Editing the Word Conversion Settings.

  1. Optionally create a new project for the import. See Best Practice above for the reason I use this method.
  2. Optionally create a folder in Project Manager into which you will import the document. For the purposes of this tutorial I have called the folder "word_import". That ensures the topics created from a specific document are in a unique folder making any cleanup work easier.
  3. Right click that folder and select Import.
  4. The Content Settings dialog will be displayed.

    Figure 1

  5. Tick the required options. I have elected to have the Word TOC added to the existing RoboHelp TOC.
  6. Click Next. The Import dialog will be displayed.

    Figure 2

  7. The Settings field and the CSS field are a little confusing at first Here's how they work.
    The first time you open this dialog, what you see in the CSS field will be whatever is set in File > Project Settings > Import Tab. By default that will be RHStyleMapping.CSS but you can change that to any CSS that has the styles to which you will want to map later in the process.
    If you have imported before and saved the settings in an ISF file (Import Settings File), you can use them again by clicking Browse and navigating to the ISF file that you saved. That will change all the settings to whatever was saved, including the CSS file.
    When you next come to this dialog after saving the settings in an ISF file, the dialog will show that ISF file selected. If you now want to use a different CSS, you need to either select another ISF or change the default in Project Settings and then what you will see here is [Custom] in the Settings field and the new default in the CSS field. Later in the process you can save a new ISF file or overwrite the old one.
    It's more logical than it may seem at first reading but beware...

There is a gotcha in the process. Let's say you use an ISF file by browsing to it as shown in Figure 2, then you change the settings and export those settings overwriting the original. When you next import a document, it will still show the same ISF filename so you will likely think RoboHelp will use the settings you exported. Wrong! RoboHelp is simply displaying the last file you used but unless you browse to the file again, it will use the settings that were defined at the start of the previous import, not what you exported.

  1. Click the Edit button. The screen you will access is described below in Editing the Word Conversion Settings.
  2. After saving the conversion settings you will be returned to the above screen.
  3. Optionally save your settings for future use by clicking Export. (I recommend that you do save the settings.)
  4. When you return to the above screen, click Finish.
  5. The topics will be created and show in Project Manager.

See Post Import after the next section.

Editing the Word Conversion Settings

When you click the Edit button on the Import page, RoboHelp will scan the document and then display the Conversion Settings window.

In the screenshot below, the number of paragraph styles is minimal because I worked with a clean document. The importance of this is described above in Before You Start.

Figure 3

 

The settings are described in detail below. The details are important!

Setting

Field

Description

Paragraph

RoboHelp Style

If left as Source, RoboHelp will create a class in the CSS that will have definitions written by RoboHelp so that the topics created will look the same as they did in Word.

Instead you can use the dropdown to select a style from the CSS that RoboHelp is going to use during this import. That is where I hit a gotcha with the import process. This is the first import so there are no saved ISF files and the supplied ISF file does not allow you to change the CSS file that will be used so you cannot see your styles.

There are two options.

  1. Click the Edit button and redefine the style in RHStyleMapping.CSS.
  2. Cancel the import for now and go to File > Project Settings. Select the CSS you want and then Export the settings. OK the various warnings.
    Restart the import and you should see the settings file you saved, if not browse to it. This time you will see the CSS file you selected so that you can map the styles.

So back to mapping now that you can see the styles you want.

  1. In Word there was no Header or Footer used so I ignored mapping that.
  2. The TOC styles will only get used in a topic that RoboHelp will create and I don't think you will want that topic so I am ignoring those too.
  3. Heading 1, Heading 2 and Normal are easy. Click the RoboHelp Style dropdown and map to the same map styles there.
  4. The list styles gave me a problem when researching this. The list styles you see in the image above are not ones I had used in the document so I left them as source. That gave me a bunch of classes in the CSS that would not be in the project CSS. I found the solution was to map each of them to Normal. Yes I know they are lists so just trust me for now. If you do not map them to Normal you will end up with something like this and indents way out line with what you had in Word.
    <p class="ListParagraphCxSpFirst">
    <p class="ListParagraphCxSpMiddle">
    <p class="ListParagraphCxSpLast">
    UPDATE 12 March 2012: I have since found that the styles shown in the image are what you will get if the lists were created using Word's icons for lists. If the lists in the document you are importing have been created using Word styles, those styles will be listed for mapping. Again whilst it may seem illogical, map those styles to Normal and they will import correctly. If you required different levels of indentation, then map to styles in your CSS such as Normal, Normal Indent 1, Normal Indent 2 and so on.

29 Apr 2014 If you use the Rh Style Mapping CSS, you will not see Normal in the RoboHelp styles dropdown. You can either edit that file and add a <p> style to it or use your own CSS.

Glossary Definition

Tick if this style is to be used for glossary definitions.

Glossary Term

Tick if this style is to be used for glossary terms.

Pagination

If this field is ticked, RoboHelp will start a new topic each time it finds the style in Word.

User Defined HTML Tag

This field will mostly be used when importing FrameMaker documents that also use this screen. Ignore it when importing from Word.

Character

 

Select the character style to map to. It will list the same styles as in the Paragraph field. Mapping here is only required if you have used a style as a character style in Word. If in doubt, apply the same mapping as for Paragraphs.

Table

 

If you want your Word tables to map to a table in your CSS, select the required style.

If you want your table to be 100% in RoboHelp, it must be set to 100% in Word. Just because it fills the page width in Word does not mean the table is set to 100%, check the tables properties in Word.

Other

Auto-create CSS styles from Inline Formatting

See RoboHelp's help.

Convert References to Hyperlinks

Word can contain references and hyperlinks. RoboHelp understands hyperlinks so this option allows you to convert the references.

Convert Header

Tick if you want any Word header converted to a header in your topic.

Convert Footer

Tick if you want any Word footer converted to a header in your topic.

Convert Word List To

Select HTML List to convert any lists in Word to standard <li> tags.

Select RoboHelp List to convert any lists in Word to multi-level lists in RoboHelp.

Note that the generated CSS will contain multi-level list styles for ALL lists that are in the Word document but only use them if this option is set to RoboHelp List.

My import document contained only two single level list styles and and I chose the Select HTML List option. Thus while the CSS created contained 13 multi level lists, they were not used with this option. Some minor numbering format and list indentation issues were corrected when I applied my own CSS.

Context Sensitive Help Marker

This field can be used for both importing and linking although it is perhaps more useful with linking. It enables you to set up a marker so that map ids are created "automatically".

  • When importing, the work involved in setting this up means that there is no saving compared with doing the work post import into RoboHelp.
  • When linking, it will save you having to recreate the map ids after every update.

Word

Before you start, you have to decide how the pagination will be set in RoboHelp. For the purposes of this explanation, we will assume it will be based on each Heading 1. Against each Heading 1, enter a footnote.

Go to the first Heading 1. It is important that you click where shown below.

 

This will bring up the dialog shown here. Enter a marker that will be used for each topic.

 

When you click Insert, Word will show the footnote area with just your marker. Add whatever you want for that footnote.

Move to the next header and repeat the above process adding different text for each topic that will be imported or linked. What you enter here, will be the ID.

Save the document.

RoboHelp

In RoboHelp, make sure your pagination setting is for Heading 1, or the same as you have set up in Word, and that this field is set to the same marker, PG in this example.

****************************************

If importing, look in All Map IDs and you will the map ids set up.

If linking, this will appear when you update.

Topic Name Pattern

This allows you to define how the filenames are generated. See RoboHelp's help for the detail.

Figure 4

Post Import

It is important to understand that RoboHelp always creates a CSS for the import of each document. Although I mapped the styles to my own pg_std.css, RoboHelp has created its own CSS (For902ImportTests.CSS) as shown in Figure 4. It does this in case the document contains styles that have not been defined in the CSS used for mapping. I would prefer that it linked to the CSS I defined as any errors caused by me in not ensuring the styles exist are mine to fix but that's the way it is.

RoboHelp 2015 has some additional fields under Other Settings so that it is no longer the case that a new CSS will always be created. There are now options to link the imported topic(s) to an existing CSS. I have yet to test this and amend this topic. Please take that into account if you are using RoboHelp 2015.

Figure 4

With Service Release 902 applied, in most respects the import was what I wanted. The lists were indented a little further than expected and the font for the numbering was not the same as in Word. The indent and the numbering were corrected as soon as I applied my CSS file, also included in the zip file that you can download from the link below. If your CSS does not correct the lists, you will probably just need to modify the <ol>, <ul>, and <li> tags.

Fixing the import

Post import I took the following steps

Meta tag

RoboHelp has always created the following meta tag when importing.

<meta name="OriginalFile" content="ForImportTests.doc" />

It seems to do no harm in online help but I have seen it cause problems with printed documentation. I suggest you remove it.

Internal (Embedded) style sheet

You will find an internal style sheet in each topic created. You need to delete it as otherwise it will override anything defined in the external CSS used for the topic. Typically you will see blue for unvisited links and purple for visited links.

The style will be something like this.

<style type="text/css">/*<![CDATA[*/
A:visited {
color: #800080;
}
A:link {
color: #0000ff;
}
/*]]>*/</style>

As the string is multi-line you will need to use a tool such as FAR as RoboHelp's Find and Replace in Files (up to Rh9) will not find strings that are split across lines. If you don't have too many topics you can do this in the HTML view of each topic. Rh10 and above will find strings across multiple lines but see Using Rh10 as there is a bug in the Must Include option.

There is an alternative solution if you have control of the documents being imported and better still, their templates.

  1. In Word, click the bottom right corner of Change Styles to show the Styles pod.
  2. Click Manage Styles.
  3. Locate the Followed Hyperlink and Hyperlink styles and set them to the colour you have in your CSS.

When you import, the internal style sheet will still be there but it will not need to be removed as the colours will be the same as in the CSS.

 

Any other issues?

Tables

If you didn't map your tables during the import or want to change the style you mapped to, it is easy to fix them in RoboHelp.

  1. Right click in the table and select Table Styles.
  2. Tick Clean Inline Styling. (Skip this step if you are just changing the table you mapped to.)
  3. Select the required CSS table.
  4. Click OK.
  5. Apply any table / column widths that you require.

Table of Contents

The books will be based on Heading 1 styles with links to the topics. Any Heading 2 will then appear as a topic within the book. If you do not want the books to be linked and prefer the topics to be listed below the book, you will need to amend what RoboHelp has created. What RoboHelp has done is not wrong, it is simply one way of creating a TOC and it may not be your way.

RoboHelp also created a topic showing the TOC in Word. I'm not sure that anyone would want that as well but it is easily deleted.

The ISF file

ISF stands for Import Settings File. When you export the settings as covered in Step 10 of The Process, those settings are saved in an ISF file. The zip file you can download below also contains the ISF file that I used.

Download

Click here to download the document I used for importing, the ISF file used and the CSS file.

Donations

If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.

Topic Revisions

Date

Changes to this page

06 Feb 2017

Topic reviewed and amended to remove content related to older versions of RoboHelp. Any screenshots may differ in your version of RoboHelp but the functionality is the same.

Temporary update removed. The change was reversed in a patch.

03 Sep 2016

Temporary update re changes in RoboHelp 2015.

29 Apr 2014

Note added re mapping to Normal (Editing the Word Conversion Settings)

14 Jan 2014

Minor revisions to reflect this topic covers Version 9, 10 and now 11.

23 Dec 2013

How to prevent Word converting PNG images to JPG added in Before You Start.

27 Apr 2013

Alternative to removing inline formatting added.

15 Mar 2013

Instructions for removing inline formatting amended.

31 Dec 2012

Before You Start amended to cover Allow PNG being document specific.

23 Nov 2012

Amended to cover RoboHelp 10 as well. Automapping added to process.

12 Mar 2012

Editing the Word Conversion Settings amended to describe revised steps for get lists to import cleanly.

12 Dec 2011

New topic