Integrating RoboHelp 9 projects with Perforce

Additional requirements

• Perforce Visual Client (P4V) (Download)
• Perforce P4SCC plug-in (Download)*
• Perforce Server (Download)**

*Some versions of P4V include the P4SCC plug-in. The Windows 32-bit installer does not.

**This article is not intended to provide instructions on the setup or maintenance of a Perforce source control system; it presumes that you have access to a Perforce depot to use for source control.

Perforce is a Perforce Software product providing source control, integration, and project tracking. RoboHelp 9 integrates seamlessly with Perforce depots via the Perforce Visual Client (P4V) and P4SCC plug-in to leverage the Microsoft Source Code Control Interface (MSCCI). I used the Perforce Visual Client/NTX86/2010.1/271261 version.

You must install the following components to use RoboHelp 9 with Perforce:

• The P4V client
• The P4V SCC plug-in (included in the 64-bit installer, you must install independently for 32-bit client)
• Adobe RoboHelp 9

I also recommend that you contact your Perforce administrator to provide you with necessary information about your Perforce installation and depot.

Perforce terminology

• The depot is the repository where Perforce stores files. The default depot Perforce creates is also called "depot"; however, depots can have any name. In other source control systems, such as RoboSource Control, the depot correlates to the database.
• The workspace is the framework that lets you work with the files in a depot. Your workspace is an image of the Perforce depot on your computer. All workspace names must be unique.
• A changelist is a request you submit to Perforce with files you have modified. The changelist is how Perforce tracks change requests to the depot in case of conflict with changes by another user.

Connecting to Perforce the first time

If this is your first experience with Perforce, you may need to create a connection. When you start the P4V client, Perforce may prompt you to create a connection by displaying the Connection Setup Wizard dialog box.

If you see this wizard, you should immediately contact your Perforce administrator to assist with the settings appropriate for your Perforce installation.

Creating a connection to a known depot

If you are already using Perforce, or have access to a Perforce depot, you should create a connection (if you don't already have one) before you create your workspace.

From the Connection menu, click Open Connection. The P4V client displays the Open Connection dialog box.

The default Server entry is "perforce:1666"; check with your Perforce administrator for information specific to your depot. Your user name should appear in the User box; type it in if the space is blank. Click New on the Workspace row to open the New Workspace dialog box and create a new workspace for your RoboHelp depot.

Creating a workspace

1. In the New Workspace dialog box, type a name for your workspace. Click OK.

2. The Workspace dialog box appears. Some of the information has been generated for you by Perforce (shown in red). Settings that you need to specify (in blue) tell Perforce where to store files locally and in the depot.

3. You should select a Submit Options setting. For example, selecting "revertunchanged" tells Perforce to submit only files with changes.
4. Specify the Root location to direct Perforce where to store files on your local system.
5. Specify the entries in the View box to direct Perforce where to find your files in the depot and the workspace used to manage them. There are two parts to the View box entry, the depot side and the workspace side. The depot side entry should correspond to the depot location you plan to use. The workspace side entry should be the same as your workspace name. Both entries should start with "//" and end with "/…" .

For example, if your workspace is called "robobuild", the Perforce depot is named "depot", and the location in the depot you are using is "help/builds", the depot side string is "//depot/help/builds/…" and the workspace side string is "//robobuild/…" .

Each writer needs to create a workspace to grant RoboHelp access to the Perforce depot. The following characteristics are worth noting:

• Perforce requires unique workspace names. Two writers won't be able to specify the same workspace name.
• The user is free to specify a Root location.
• The depot side information in the View box should be identical, because that is what Perforce uses to connect the workspace to the depot.
• The workspace side information in the View box should match the Workspace listed by the dialog box.

Add a RoboHelp project to Perforce

Before you can use Perforce for source control, you must add your RoboHelp project to a Perforce depot. Once a project is in Perforce, writers can get the project files out, update to the latest revision, and submit changes in a controlled environment. To add a project to Perforce, complete the following steps:

1. Launch RoboHelp and create a project in the folder you specified in the Root box. You can also copy an existing project into that folder and open it from there.
2. After the project is created or opened, click Add Project to Version Control from the Version Control toolbar or on the File menu.
3. Select the Perforce SCM option and click OK.

4. In the Open Connection dialog box, specify the workspace you defined previously. Click OK.

This image of a Perforce changelist shows how Perforce recognizes that there are files waiting to be submitted. You need to check in these new files with RoboHelp to allow Perforce to submit them to the depot.

5. Click the Check In All icon to open the Check In dialog box. Click OK.

6. Perforce opens the Submit Changelist dialog box. Type a changelist description in the Write a changelist description box to enable the Submit button. Click Submit.

7. RoboHelp checks the files in and Perforce updates the depot.

Get a RoboHelp project from Perforce the first time

Each writer must create a uniquely named workspace before they can work in a project. To get a project from Perforce the first time, make sure that you have the workspace name, folder details, and the appropriate access rights. Each writer needs to perform the following steps to acquire files from source control:

1. Create a workspace in Perforce.
2. Open RoboHelp. On the File menu, click Open.
3. Click the Open Project from Version Control icon to open the Select Version Control Provider dialog box.
4. Click Perforce SCM, then click OK.
5. In the Open Connection dialog box, type or browse to the workspace you created in Step 1. Click OK.
6. In the Perforce – Open Project dialog box, navigate to the folder containing the target project. Click the project folder, then click OK.

7. RoboHelp displays the Open Project dialog box containing the project .xpj file. You can now open the project from the .xpj file. The local copy is saved in the location you specified in the Root box when you open the project from source control.

Working in RoboHelp with Perforce

Once you have gotten a project from Perforce, you can open it with the .xpj file or from the Starter menu. RoboHelp automatically updates all of the project files to the latest version from Perforce. When you need to modify a topic or project file, click the Check Out icon or use the Check Out menu option in the Project Manager. When your changes are complete, click the Check In icon or the Check In menu option to display the Submit Changelist dialog body to submit your changes to Perforce. Best practice indicates that using the Check In All option in RoboHelp is better than checking in individual files, because you need to submit only a single changelist. If your workspace specifies the "revertunchanged" Submit Option, only files with actual changes are updated.

What if you added the project to an incorrect location in Perforce?

Unless you have permission to permanently remove material from the depot, you will probably need to enlist the help of your Perforce administrator to correct this situation. Depending on your source control protocols, the administrator can determine whether you need to correctly add the files before or after the incorrect files are removed, or if another solution is available.