Opening Projects

What's covered?

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

August 2019 - This page covers both the Classic versions of RoboHelp New UI versions.

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.

RoboHelp New UI

First things first, you did read the warning above didn't you? Also I suggest you read the whole section before starting to rebuild things as you might spot something that looks likely to be behind your problem.

The new UI projects are less likely to corrupt but if you do have a need to rebuild a project this is how I would tackle it. You can also use this information to copy parts of a project to another project.

Earlier Versions

The first thing to note is that going back to a Classic version is not an option.

The Folder Structure

It's all much cleaner and this is the structure that you will find in any project.

RHPJ File

This file should not be deleted as without it you will not be able to open the project. It does contain a few things that you might want to look at in the event of problems and that you could copy between RHPJ files to save a bit of work.

• Condition Tag Groups
• Topic Status List
• Colours

Opening a New UI Version in an Earlier Version or Update.

This is not recommended as the code may not be understood.

Rather than open a project that has been worked on in a later update but both machines are on 2019 or both are on 2020, update the installation on the other machine.

If you want to open a 2020 project in 2019 or not update as above, you proceed entirely at your own risk.

If you open the RHPJ file from the 2020 version in a text editor, you will find this code at the beginning. The Project Version needs to be changed to the version on the earlier release. If you are downgrading from 2020 to 2019, the ID line needs to be deleted.

<project version="2020.0.0">
<title>My Project 2020</title>
<id>24ad50c7-eb99-40c1-a770-a6a9cf6994e6</id>

.rh Folder

The contents of this folder can be deleted and RoboHelp will recreate the contents on reopening the project. It is unlikely to fix problems but it has helped on a couple of occasions.

• Project’s cache data that will be rebuilt on reopening the project.
• Version Control settings such as git repository information.
• The recently opened files history.
• Report data that will recalculated on reopening the project.

Condition Folder

• This folder contains the default.cnd file.

Options

1. Open the file in a text editor to check the structure and correct it if required.
2. Copy the file from a good backup or another project that has the required values or is close enough, then edit in Robohelp or a text editor.

Contents Folder

This is most likely where your problems are.

The contents folder itself will contain all your folders and files in whatever structure you have defined. The assets folder contains the folders shown plus any others you may have added.

One way of dealing with a problem project when all other avenues have been exhausted is to create a new project and start rebuilding it by copy parts of the old project bit by bit.

1. Using File Explorer, copy Folder_One from the problem project to the new one. The styles will be wrong, the images will be missing as will the masterpages, live with that for now.
2. If the problem persists try Folder_Two and keep going until a folder reintroduces the problem. Then you know where to look so you remove all the topics and then add them back in a few at a time.
3. With all the content back in, now copy your CSS files back in. If you have more than one, do this one file at a time so that you can identify the CSS file causing the problem.
4. Next add in your images. Add them in bulk but if this reintroduces the problem, delete them all and copy in a few at a time.
5. Finally add in your master pages, again one at a time.

If the problem is still there or it is clearly something to do with another folder, read on.

Glossary Folder

This folder contains the glossary files that you have created. It will be default.glo unless you have renamed it.

Options

1. Open the file(s) in a text editor to check the structure and correct it if required.
2. Copy the file(s) from a good backup or another project that has the required values or is close enough, then edit in Robohelp or a text editor
3. You can delete existing files and recreate them within RoboHelp but obviously the terms will be lost.

Index Folder

Index terms are stored within topics in 2019.

• The IDX file will only have content in the following scenarios.
• Keywords with no topic assigned to them.
• Keywords with condition tags applied onto them.
• Keywords with a cross reference.

Options

1. Open the file in a text editor to check the structure and correct it if required.
2. Copy the file from a good backup or another project that has the required values or is close enough, then edit in Robohelp or a text editor
3. You can delete the existing file and recreate the keywords that had no topic assigned, reapply the condition tags and the cross references. As soon as you enter something that is in the scenarios above, RoboHelp will create a new IDX file.

Publish Folder

Languages

In the labels folder you will find files containing details of any changes you have made to the default terms. These are unlikely to cause any problems but as with the other files, you can either recreate things in the new project or copy the file(s) from other working projects.

Presets

You can delete any of the presets and either recreate them or copy them from other projects. If you do create copies, you will need to go through the configuration to change some of the settings such as the output path.

Variable Sets

If you create variable sets, any of the changes you make from the original values will be stored here. You can either recreate the files or copy from another project and then edit the content as required.

Settings Folder

This folder contains the default settings for importing any FrameMaker or Microsoft Word documents plus any configurations you have saved. You can either use the default files in the new project or copy from another project that you have.

TOC Folder

This folder contains the TOC files that you have created.

Options

1. Open the file(s) in a text editor to check the structure and correct it if required.
2. Copy the file(s) from a good backup or another project that has the required values or is close enough, then edit in Robohelp or a text editor. You will need to carefully check the paths if you copy from another project.
3. You can delete existing files and recreate them within RoboHelp but obviously the structure will be lost.

Variable Folder

Options

1. Open the file in a text editor to check the structure and correct it if required.
2. Copy the file from a good backup or another project that has the required values or is close enough, then edit in Robohelp or a text editor
3. You can delete the existing file and recreate it within RoboHelp but obviously the terms will be lost.

RoboHelp Classic Versions

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, the Help Essentials site had the information on what needs to be done. The site is now closed but with the author's permission, you can download a PDF version of the information.

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.

• 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 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, the recovery script that was hosted on the Help Essentials site is now available free of charge on this site. See Scripts.