Importing Using the RoboHelp 6 Wizard

Introduction

Importing a Word document into RoboHelp 6 can be a painless procedure if you follow some simple rules. Ignore them and what goes into RoboHelp may haunt you for some time!

Too often I see posts on the Adobe RoboHelp forum about problems with a project that started life by importing a Word document.

• The document looked good in Word so if it doesn't look right in RoboHelp, it is RoboHelp that gets the blame.
• Other times the imported document looks OK in RoboHelp so other changes are made to the project and when something goes wrong, RoboHelp gets the blame while Word looks all sweet and innocent while being at the root of the problem.

It is just too easy to blame RoboHelp. Using the improved import features of RoboHelp 6, I recently imported a number of documents that looked great in Word but in the online help they were a disaster. I'll admit my first reaction was that RoboHelp's import routine was worse rather than better. However, something told me to question that so I went back to the documents and found the truth.

The documents had been created by someone who had put a lot of effort into making them look good and they truly were professional looking documents, but that person had not done things the right way. If they wanted an indented paragraph, they selected the paragraph and used the indent icon rather than apply a style that was indented. If they wanted different bullet symbols they applied them manually to those lists rather than use styles. On and on it went. I spent quite a time cleaning up the documents reversing these malpractices and apply proper styles. After that the import was so clean that I only had a few minor changes to make in RoboHelp 6.

In Word there are right ways of doing things and wrong ways but the appearance of both is the same so people think, wrongly, that their document is good and blame RoboHelp when using a document that does not work as expected.

So let's look at what you need to do.

Getting the Best Import

For ease of explanation I will look at the various aspects of the import and describe each of them. I will look at the issues and suggest how you can minimise the problems. It may be that you cannot follow the advice because of something unique to your source document, in which case you will have to import following my findings as closely as you can.

One thing I strongly recommend is do not import Word documents into your carefully crafted main project. Import them into a project set up just for the purposes of the import.

w If it goes well, then import the htm files created into your main project

w If you have problems then nothing is lost, just trash the temporary project and start again.

Part One

These steps may be all you need if your Word document has been formatted correctly. At worst it will take a minimal amount of time to prove to yourself that the steps described in Part Two are necessary. You have to regard the import as a trial and error experiment. If you start with that in mind, it helps the attitude later on!

1. Remove any unwanted cover and blank pages from the document.
2. If you are creating a new RoboHelp project and the document has a Table of Contents that you want to use, leave it in.
3. Remove headers and footers if you do not want them in the online help. Otherwise leave them in.
4. Convert any Body Text to Normal. Normal converts to a <p> tag in HTML, body text does not. Use Word's Find and Replace tool to convert all Body Text to Normal for better results.
5. One of the most important things I found was changing the language setting in Word. This step is vital. It "only" applies to those of us outside the US, although it has to be pointed out that there are more of us outside the US than in it! You need to select all the text in the Word document (Ctrl + A) and set the Language to English (US). Always leave this step until last before importing.
6. Create a new project and import the document into that to see what it looks like.

• If you are lucky the topics will look as you want when you apply your own style sheet. You can move on but do remember the topics were created from a Word import so if you have problems later on, that needs to be taken into account. Please do mention it when posting on the RoboHelp forum.
• If the topics do not look right after applying your own style sheet and require more than a few simple corrections, you can easily delete the project created with no loss and work through Part Two. Had you imported the document into an existing project, it would require some rather more time consuming cleaning up. Which topics to delete? Which images to delete? And so on. This way you quickly delete the whole unwanted project.

Part Two

OK, so obviously Part One didn't give you quite what you wanted.

1. Look at what styles are in use in your Word document.

If you are going to use your own pre-existing style sheet (css file), make sure the names of the styles match in the Word document and the CSS. You can change the names to make them match either in Word or during the import. I cover this aspect in more detail in the RoboHelp 6 topic and suggest you take a look at that as well.

2. Change all paragraphs that use either bullet point or numbered styles so that the bullets or numbers are applied using Word's toolbar icons.

If there are many such paragraphs and you have a hard copy of the document as a reference, you could use Word's Find and Replace tool to change those styles back to the Normal style. There's a similar macro you can download from my Word Macros that does the same job but a bit more easily. After converting the paragraphs back to Normal, you then have to painstakingly work through applying the bullet and number icon. If you don't do this in Word, the change will need to be made in RoboHelp. There will be no macro to help you and the Word document will have been split into numerous topics, making the task more time consuming. I realise that this could be a very time consuming task and you may only be able to justify it unless you have a strong case for creating topics that are easier to edit in RoboHelp. Also do a sample test first to make sure the method does work for you. If you have lots of bulleted or numbered lists, then you might want to consider upgrading to RoboHelp 6 as things are much better there.

3. Consider reducing the number of styles used before you start the import.

If you are starting with more styles than you want in the RoboHelp project, it will probably be easier for you to streamline things in Word first. After the import, your Word document will most likely be split into a number of topics. You could change things in RH but it's probably easier to do it in Word. Also for some of you, HTML will be a bit of a mystery and a place you do not want to be making too many changes.

4. Look at manual formatting that has been applied at paragraph level as opposed to character level.

What you should be aiming to have is a Word document that uses styles for each paragraph format that you want, rather than styles with variations being created manually. For example you should use Normal for most paragraphs and Normal Red for paragraphs that are to be formatted with red text, not selecting a paragraph and applying Red to the text. Unfortunately the latter is what most Word users will do but it is not the correct way.

During the import, RoboHelp 6 will create its own stylesheet for the document. For some authors that style sheet will be sufficient but if you are planning to change the topics to your own pre-existing style sheet after the import, then you should aim to match the styles. Normal in Word will map to <p> and heading styles will also map correctly. Other styles you need to test and it may be easier to modify a class in your style sheet to match the class name the RoboHelp has applied during the import.

Why?
Any manual formatting will convert to an inline style in your online help. You should be aiming to have it convert to an html class as that is controlled from your style sheet and makes mass changes much easier.
How?
To find manually formatted paragraphs using Word 2003 make sure you have this check box ticked in Tools | Options | Edit.

That's the one that gives you the much longer list of styles that you see in Word 2003. At other times you might want to clear that one! I place the cursor in each paragraph in turn and make sure the style does not have a + symbol after it. For example it shows as
 
rather than the style with a + symbol after it.

The + sign indicates you have taken the style and modified it for that paragraph. "Normal Red" would be OK as that indicates your document contains a style with that name. The + symbol is what you are looking for. You may find that you have to repeat the process several times over in the Word document as Word will ignore what we may regard as similar formatting because technically there is some difference.
The other way of doing this is to press Ctrl + A and then Ctrl + Spacebar as that removes all manual formatting. You then get the document back to the required appearance using styles rather than manual formatting. Be careful with that one though as it may make more changes than you really want. Check immediately and use the wonderful Undo feature if necessary.
It's OK to have individual words manually formatted as the import routine creates classes for those. That's useful as you can quickly change the class so that something bold in Word can be blue and bold in RoboHelp.

5. Create a template that you will use only for this purpose. You might want to skip Steps 4 and 5 and see how what results you get. Provided you are importing into a new project, you can always carry out these steps later.

How you do that varies a little according to your version of Word. In Word XP (2002) you go File | New to display a panel on the right and then select General Templates in the New from Template section. That displays the same dialogue box as is displayed when you go File | New in Word 2000. Change the radio button selection from Document to Template and just save the template with your chosen name. Do not make any changes to it. Your document may not look right in Word but what we are interested in is what it looks like when it hits RoboHelp, not what it looked like in Word.

6. Apply the template to the document to be imported.

Open the document in Word and then go Tools | Templates and Add-ins. Click the Attach button and navigate to where you saved the clean template. In my initial test of the method, I did not select Automatically Update Document Styles and the method worked fine. With some subsequent tests I have found that it is necessary to select that option! On balance and until I have further evidence, I would say select the Automatically Update Document Styles option. It will probably make your source document look odd but see my comments in the item above.

7. Open the new project and start the import.

Two dialog boxes will be displayed during the import. In the first I got the best results with:

w "Preserve Heading Styles" not ticked so that all topics are created with Heading Style 1

w "Auto-create styles from inline formatting" not ticked (the defaults).

You may find otherwise, it's a bit of trial and error. For the other options you will need to make your own choices.

In the second dialog, make sure you tick the heading levels that you want RoboHelp to use when creating new topics.

Reviewing the Import

At this point it is not possible to cover everything you might find. All I can do is point out the main things you are looking for.

Is the import OK?

• If the HTML and the topics look good, you can now apply your own style sheet. You can either do that with the individual topics or you can select all the imported topics in the Topics tab, right click and then apply your style sheet to all the topics. If after apply your own style sheet you notice that the style dropdown in RoboHelp is displaying the style in CAPS, it means that style is not defined in the style sheet. Your HTML is saying something like <p class=YourStyleName> but that style is not defined in the css file you have just attached, so RH tells you by showing it in CAPS.
• If the HTML is still not good or the document does not look right, don't give up just yet. Step back and identify the things that are wrong. Can you correct them manually without too much effort? Can you run the import again and do something different? Maybe you need to post a question of the RoboHelp forum.

Printing

Try creating a printed output immediately after the import. Sometimes the HTML created can cause issues not related to styles. If you have problems see either Printed Output or Print Issues.

Useful Tools

There are two main tools that you may find useful in this process. Macro Express and FAR. See Useful Tools and Links to find their websites.

Macro Express

At its simplest, you perform an action once recording it as a macro. Then you repeat it as many times as you want. It's much the same as recording a macro in Word except this works with any program you use. Last time I looked it was free for one month so you can easily find out if it is for you. There are other programs around and some of them free but in my opinion, this one is far and away the best. It can do all sorts of other useful things, like remember all your standard paragraph wordings.

FAR

FAR stands for Find and Replace which is in fact just one of the things it does. The beauty of this Find and Replace tool is that it finds strings across multiple lines (most do not and miss the string if it is not all on one line) and it works across multiple files. With careful use of this tool, you can quickly change all sorts of things that are not quite right. Bear in mind though that you can just as quickly wreck the whole project if you mess up, so take a copy of the project before you start. Again this tool is free to start with and it is my preferred tool