Opening RoboHelp Projects

 

 

What's covered?

This page explains your options.

 

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

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. With that proviso, see Willam van Weelden's site for information on what needs to be done.

RoboHelp 8 Folder Bug

I have mostly removed from this site any content for versions pre RoboHelp 9. However, this one still crops up from time to time.

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

If you are using RoboHelp without that service release and have encountered this problem, click here.

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

  1. Create a zipped backup of the project.
  2. Install the service release.
  3. 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.
  4. Check Tools > Reports > Unused Files and ensure that none of your topics are reported there. If they are, then reimport them.
  5. Close the the project and create another zipped backup.
  6. Delete the CPD file and reopen the project using the XPJ file.
  7. 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.

  1. It is recommended that all authors check everything back in to source control.
  2. Have all writers on the project make a pre 802 zipped backup of their local copy of the project and close RoboHelp.
  3. Install Service Release 8.0.2 on Author 1's machine.
  4. Open the project on that machine using the XPJ file.
  5. 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.
  6. 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.
  7. Check Tools > Reports > Unused Files and ensure that none of your topics are reported there. If they are, then reimport them.
  8. When the project is fully repaired, close it and create another zipped backup.
  9. 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.
  10. Check everything back into source control.
  11. Get all users to delete their local copies of the entire project, but not the backup taken in Step 2.
  12. Get Author 2 to apply Service Release 8.0.2 and take a fresh copy of the project.
  13. Check it can be opened with no errors.
  14. 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.

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.

Corrupt Projects

The first step is to make a backup copy of the project as covered above. Then delete the CPD file that is in all versions (from X5 onwards) and then open the project in the usual way with the existing XPJ file. RoboHelp will rebuild the CPD and that often fixes the problem. You can rename the CPD if you prefer rather than delete it. Delete the old file later when you have got things going.

You may come across instructions elsewhere to delete both the CPD and XPJ file. Do not delete the XPJ file at this stage. That method will result in a lot more work and often just renaming the CPD will do the trick.

Projects should not lose any data if you delete 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.

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 project 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.

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.

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. You will see an option to use the existing XPJ file, do not select that option. If the above has failed this method is your next step.

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 Snippets > Miscellaneous > Item 25. 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 the root of your project in Windows File Explorer 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 File 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.

  1. 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.
  2. 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.
  3. Make sure things are good and work on your project.
  4. 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.
  5. 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.

Other Options

If you have a supported output that has all your topics in, then Willam van Weelden offers a commercial script that will recover your project. If the output only has some of your topics, then it may still help if the missing topics can be imported back in after recovery. See Willam's site for a full list of the output types that are supported by his script.

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

29 May 2017

Other Options added.

08 Feb 2017

Topic reviewed and most content relating to versions before RoboHelp 9 removed.

08 Oct 2014

Some references to RoboHelp 7 and 8 amended to RoboHelp 7 and above.

30 May 2011

Minor changes clarifying when to rename the CPD and when to delete.

RoboHelp 8 procedures placed in dropdown.

Which projects have an MPJ and which have a CPD clarified.

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.