Importing Using RoboHelp 9.0.2

What's covered? This page is about the screens you will encounter when importing Word documents into 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.

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?

• Make a copy of the document and work from that rather than risk spoiling an important document.
• Remove any unwanted cover and blank pages from the document.
• Removing any inline formatting and applying proper styles will help. To remove all inline formatting from a Word document, press CTRL A to select all the text and then press the spacebar.
• A typical document will have been worked on by many people who have created styles if you are lucky, more likely they will have applied inline styling. Also it will typically contain a large number of styles that are not used but the import process nevertheless lists them in the Word Document Settings window. What you see below in Figure 3 is from a clean document, typically the list can be many times longer and it can be difficult to know which styles need to be mapped and which can be skipped.
  The easiest way I know of to get rid of them is to create a new document and paste in the content of the document you want to import.
  Ideally I would like to see RoboHelp filter out the unused styles. The argument for retaining them is for when authors want to keep the topics created from the import looking as they did in Word and may want to make subsequent edits using the styles available in Word. I can understand that point but I think that most people want their import to take on the style of their other topics. I hope Adobe can offer filtering as an option in the future. Please submit a Feature Request if you agree.
• If your document contains PNG images, it is important that you tick a Word option. In Word 2010 it can be found in
  File > Advanced > General > Web Options - Tick the Allow PNG as a Graphics Format checkbox.
  Without this option ticked, the images will be converted to poor quality GIF images.

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:

• A Contents page.
• Bulleted and numbered lists.
• Tables.
• Images in GIF, JPG and PNG format.
• Cross references.

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.

8. Click the Edit button. The screen you will access is described below in Editing the Word Conversion Settings.
9. After saving the conversion settings you will be returned to the above screen.
10. Optionally save your settings for future use by clicking Export. (I recommend that you do save the settings.)
11. When you return to the above screen, click Finish.
12. 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. Click the Edit button and redefine the style in RHStyleMapping.CSS. 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. In Word there was no Header or Footer used so I ignored mapping that. 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. Heading 1, Heading 2 and Normal are easy. Click the RoboHelp Style dropdown and map to the same map styles there. 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.
	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 will be used when importing FrameMaker documents that also use this screen. Ignore it when importing from Word.
	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.

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.

Embedded style sheet

You will find an embedded CSS in each topic created. You need to delete it. 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 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.

 

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
12 Mar 2012	Editing the Word Conversion Settings amended to describe revised steps for get lists to import cleanly.
12 Dec 2011	New topic