Opening RoboHelp Projects

What's covered?

Sometimes there are problems opening a project because of corrupt files.
Sometimes you want to open a project in an older version of RoboHelp.

This topic explains your options.

If the problem is with a RoboHelp 6 project, you might want to look at Snippet 79 first.

Before attempting to fix ANY corrupt project or opening it in an earlier version, it is vital that you back it up. I recommend that you zip it up so that you cannot mistake the backup and open it causing further irreversible damage. If you then get anything wrong, you are no worse off than when you started. Keep the backup for a while just in case there is something that you don't spot immediately.

RoboHelp 8 Folder Bug

You can skip to the next section if you are not using RoboHelp 8.

RoboHelp 8 users who do not have Service Release 8.0.2 applied may encounter a bug the symptoms of which are:

On opening a project, the cursor flickers between an arrow and an hour glass (XP) or the beachball (Vista).
The project may crash.
On opening the project, there may be broken links and folders and files are missing from Project Manager.
In isolated cases the missing files may also have been deleted from the hard disk.

If you are using RoboHelp without that service release and have encountered this problem, read on. Otherwise skip to the next section.

Service Release 8.0.2

Service release 8.0.2 should be applied to all installations of RoboHelp 8 to prevent this happening in future, regardless of whether or not this problem has been encountered. Note that Service Release 8.0.1 must be installed before applying Service Release 8.0.2

It is available from the Adobe Downloads page and via Help > Updates. You will need local administration rights to install the service release on your PC.

The service release will not repair any damage to your project(s), that still needs to be done manually.

Standalone Projects

Create a zipped backup of the project.
Install the service release.
Open the project using the XPJ file and check to see if any broken links are shown in Project Manager.
If there are broken links, right click each one in Project Manager and select Restore. It is important the links are repaired this way.
Check Tools > Reports > Unused Files and ensure that none of your topics are reported there. If they are, then reimport them.
Close the the project and create another zipped backup.
Delete the CPD file and reopen the project using the XPJ file.
Check that no broken links are showing and that there are no unexpected topics showing in Tools > Reports > Unused Files.

Projects under Source Control

These steps apply to all source control systems recognised by RoboHelp. [Further information to be added here]

Steps 3 to 10 must be undertaken by one author and during that time no one else should be permitted to access the project.

It is recommended that all authors check everything back in to source control.
Have all writers on the project make a pre 802 zipped backup of their local copy of the project and close RoboHelp.
Install Service Release 8.0.2 on Author 1's machine.
Open the project on that machine using the XPJ file.
You will be prompted check out the FPJ files. You must select Yes.
If you are not prompted, check to ensure all FPJ files are checked out. There is one per folder. If the Display Confirmation dialog options are unchecked in the Tools > Options > Version Control tab in RoboHelp, the files will be checked out automatically.
Check to see if any broken links are shown in Project Manager.
If there are broken links, right click each one in Project Manager and select Restore. It is important the links are repaired this way.
Check Tools > Reports > Unused Files and ensure that none of your topics are reported there. If they are, then reimport them.
When the project is fully repaired, close it and create another zipped backup.
Delete the local CPD file and reopen the project using the XPJ file. This step is not essential, it is more to verify the repair has worked.
Check everything back into source control.
Get all users to delete their local copies of the entire project, but not the backup taken in Step 2.
Get Author 2 to apply Service Release 8.0.2 and take a fresh copy of the project.
Check it can be opened with no errors.
Repeat Steps 12 and 13 for all authors.

General

After a project has been opened on a machine with this service release, it should not be opened on an unpatched machine. A warning will be given that the project is from a newer version. Whilsy you can delete the CPD file and then open the project on the unpatched machine, you then run the risk of losing files from Project Manager again. This practice is discouraged because of the attendant risks. Service Release 8.0.2 should be applied to all the machines you use.

In the event you cannot open the project using the XPJ file, you will have to open it with the HHP file and select No when prompted to use the existing XPJ file. Then follow the steps above before proceeding with the other steps described in Using the HHP File.

With 8.0.2 applied, you should not encounter any further occurrences of this problem.

After a project has been opened on a machine with this service release, it should not be opened on an unpatched machine. A warning will be given that the project is from a newer version. You can delete the CPD file and then open the project on the unpatched machine but you then run the risk of losing files from Project Manager again. This practice is discouraged because of the attendant risks. Service Release 8.0.2 should be applied to all the machines you use.

Corrupt Projects with an MPJ file

For versions of RH that have an mpj file, the standard advice for dealing with corrupt files has always been to open the project with the HHP file. You can rename or delete the mpj file first and if you know your way around Microsoft Access, you may be able to import back some of the lost data (an mpj file is an Access database with a different file extension so that RH can be linked to it). That might of course reintroduce the problem so it's trial and error.

See Using the HHP File below.

Corrupt Projects with an XPJ file

For versions of RH that have an XPJ file (X5 onwards), the procedure is to rename the CPD file and then open the project with the XPJ file but read on a bit before you rush ahead and do that as that does not always work. The CPD file is an Access database holding much of the information about your project that was in an mpj file in earlier versions.

Adobe RoboHelp 7 and 8

Adobe RoboHelp 7 and 8 changed things so that you should not lose any data if you rename the CPD and use the existing XPJ file to reopen your project. A new CPD will be created from various files within the project and that should correct the problem. Do make a backup of your project first.

If the project will still not open, then see Using the HHP File below.
If it opens with many broken links and / or missing folders and files, you could try checking the FPJ files in each folder first.

The FPJ file

Each folder contains an FPJ file. If you open it in a text editor such as Notepad, you will see it lists all the HTM files in the folder and any sub-folders in the format:

If you have missing folders and files, it is likely they are not listed. With the project closed, you can add them manually and use the XPJ file to open the proejct and see if that fixes the problem. It would be prudent to backup again before you reopen the project. If you have a lot of folders and / or files missing, it may be easier to use the HHP file as described below.

You must backup up first and if it appears to fix the problem, there is a further test. With the project closed, rename the CPD and then open the project and check it again. I have seen a project recovered then break again but there was something a little unusual with that project.

If you are using RoboHelp 8 and encounter this problem, check that you have Service Release 8.0.2 applied. If you do not, then do not edit the FPJ file(s) in this way, instead apply the service release and read the instructions under RoboHelp 8 Folder Bug above.

RoboHelp X5 and RoboHelp 6

If you are using RoboHelp X5 or RoboHelp 6, then you might lose some data but if you follow the right steps, most things can be recovered easily. What you will lose and how to recover it is described later in this article.

Make a backup of your project and then in order try these methods.

Rename the CPD and use the existing XPJ file to reopen your project. A new CPD will be created from cached information and that should correct the problem. If does not, then delete that and make a fresh copy of the backup, then proceed to the next method.
If you are able to open the project, albeit with problems, generate a new output. This updates the HHP file in your project. Then see Using the HHP File below.
If you cannot open the project to generate a new output, then you will have to use the HHP as it is. See Using the HHP File below.

Any Version

Remember, make a backup before following any of these procedures and never work on that backup. When you get things going, keep that backup around for a while in case you discover something else that is not quite right when you are further down the line. I prefer zipped copies as you cannot work on them and you can extract the contents over and over again if necessary.

Opening Projects in an Earlier Version

If you simply want to open a project in an earlier version, you have to accept that things not compatible with the earlier version are not going to work. If you know how to use Microsoft Access, you can minimise the loss by tweaking the mpj file and using that rather than the HHP file. Visit Rick Stone's site and download his Tips and Tricks file.

This is not possible with RoboHelp 7 and RoboHelp 8 projects.

Using the HHP File

If you cannot successfully open the project in the ways described above, then you will have to resort to using the HHP file. Either use RoboHelp to browse to the HHP file or right click the HHP in Windows Explorer and use Open With.

Almost certainly the project will now open but there will be damage. Here's how to repair it. Not all the items listed apply to all versions of RoboHelp.

Topics created since the HHP was last updated.	Note the word "created". The HHP is updated in a number of situations as described in Snippet 119. Principally this is when you generate online help. Any folders and files created after then will not be in the current HHP. The first step in the rebuild is to look at Tools > Reports > Unused files. Any topics created since the HHP was last updated will be listed there and need to be imported back into the project.
Replace missing Conditional Build Tags	Simply create new CBTs with EXACTLY the same names (spacing, underscores etc). The new CBT will associate itself with the topics and text.
Replace missing single source layouts	Look for the SSL files in WE and simply create new layouts with EXACTLY the same names (spacing, underscores etc). The new layout will find the old settings. Tip: Highlight an SSL file in Windows Explorer, press F2 and then CTRL C. In Project Manager, use CTRL V to create the layout name, making sure you do not include the file extension.
Snippets and variables	With RoboHelp closed, copy rhsnippet.apj and rhvariable.htm from a backup and paste into the project. Open both in a text editor. Check that rhsnippet.apj shows all the .hts files in the project. Add any that are missing. Check that rhvariable.apj shows all the variables in the project and their values. If any are missing, try recreating them in RoboHelp with their original names and see if they are still shown in the topics. Reopen the project and check everything here is OK.
Replace missing TOCs, Indexes and Glossaries	The default TOC, index and glossary will be restored but any additional ones will be missing. Create a new TOC with a new name, tick Copy and browse to the HHC that will still be in the project. That creates a new TOC with the new name. Use Windows Explorer to delete the original file. Now you can rename the new file with the original name. Follow the same steps for indexes and glossaries.

Tricks

Don't have an HHP file? Click here to download Adobe's HHP builder.

Point it to the root of the project and enter the name of the file to be created. The name is important. Look for the CPD, HHC, HHK files. They will all be the same except for the extension. That is the name you need for the HHP file.

Post Recovery

For a while at least after having problems like this and maybe until you have identified the cause, it might be advisable to go a little overboard with protection procedures in case things go wrong again.

Here's one method.

Zip the recovered project and prefix the zip file with the date and time. Use the format YYMMDD for the date, it sorts the files into chronological order. You cannot work on a zipped project so this protects your source.
Go to Tools > Options and tick the option for the cache to be rebuilt each time you open RoboHelp. In other words, RH will delete and recreate the CPD. This will slow up project opening but it does stop the CPD getting bloated.
Make sure things are good and work on your project.
Close and zip the project as frequently as you deem safe. Maybe as often as two or three times a day in the short term. It doesn't take long to zip up a project.
Keep this procedure going until things are proving reliable. Then ease off a bit as you deem safe.

If at any point, there is a problem after opening the project, then turn off the option to rebuild the cache and close RoboHelp. Then unzip the last good backup and open that in RoboHelp. The CPD will not be rebuilt so you are back to having a good project. Then you need to investigate just what the root cause is.

Date	Changes to this page
19 Dec 2009	802 procedures revised to include source controlled projects.
05 Nov 2009	Minor amendment to section on rebuilding the FPJ file(s).
04 Nov 2009	RoboHelp 8 problem revised and the Post Recovery procedures built into the main article.
29 Oct 2009	Rewritten to include how to recover what will be lost in all versions if the HHP is used to open projects.
15 Aug 2009	RoboHelp 8 added plus explanation that the HHP does not contain all the information a project needs.
28 Apr 2008	Various changes so that topic recommends deleting the CPD file to see if that works. Reduces what can be lost.
23 Apr 2008	Instruction re any missing folders amended.
01 Dec 2007	Procedures for variables and snippets added. Taking a backup further emphasised.
03 Oct 2007	Reference to Snippet 79 added.
01 Apr 2006	Loss of SSL settings revised. Default layouts retain their settings. Additional layouts are lost but can be recovered.
23 Mar 2006	Updated to cover loss of Conditional Tags. Also added a note re Rick Ferrell advising that SSL settings will be lost.
07 Oct 2005	Creating an HHP file using Macromedia's HHP Builder added.
16 Aug 2005	Instructions revised to clarify when to compile a CHM file before deleting the CPD and XPJ files. Additional instructions added re reinstating lost folders and files.
16 Apr 2005	Topic revised to include instruction to compile a CHM file before deleting the CPD and XPJ files. Link to old eHelp forums removed.
27 Dec 2004	New topic.