Command Line Generation

The Author

The page was written by Bill Albing who is a senior information architect at Paragon Application Systems www.ParagonEdge.com and is co-founder and editor-in-chief of KeyContent.org. Bill has over 15 years experience in engineering, software development, and technical writing.

The Steps

Wouldn't it be great to generate the online help from a command line so it can be done automatically as part of the build process? If you are creating online help for a software product, this would allow automatic generation of the help whenever the software is built. Basically, it's a four-step process.

• Getting the Content Ready
• Preparing a Layout for Each Deliverable
• Using the Command Line Syntax
• Running in an Automated Build Process

This doesn't count deploying the files; this topic only explains how to generate them from a command but not what to do with them once they are generated. I will let you figure that part out on your own.

Getting the Content Ready

The first step is getting the help to a point where it can be generated. Remember, the automation doesn't include actually creating the content. You have to do that part. The automation only involves generating the deliverables from the great content you have put in place to begin with. So I assume you have created a bunch of topics, assembled a logical table of contents, added an index and glossary if you like, and are ready to generate the output.

Preparing a Layout for Each Deliverable

The second step is getting the Layouts the way you want them. So figure out what your deliverables are, Web Help or Web Help Pro, Compiled Help, Printed documentation, etc. And figure out who the deliverables are for and how often you want to generate those deliverables. In the example here, I am creating Web Help Pro (for posting on a server) for a single customer and want to generate it every time the build of the software is done.

For a Web Help layout, there is the Project Name, General settings, Navigation settings, and other options. The Web Help layout wizard steps you through those settings. For a Web Help Pro layout, there is only one page of options. This includes the Project Name, the Output Folder, Conditional Build Expression and more. The idea is to create a layout for each distinct deliverable because it is the layout that is used by the RoboHelp generate command.

So for my example, I'm calling the Project Name "Online Help" and specifying the output folder:

C:\Source\ProductXYZ\!SSL!\CustomerA Layout\ProdXYZ CustA 2011-03-18\Online_Help.htm

The conditional build expression is used if you have conditional text:

NOT print AND NOT Customer2 AND NOT Customer3 AND NOT year2010

In the Skin and Content settings, I set the skin to Default and set the Glossary to one specific to this customer and set the variables which are specific to this deliverable.

I add breadcrumb links but customize their display for this particular customer who wants centered breadcrumbs.

It is a good idea to generate the help using this layout manually to make sure the layout is what you want. After you are sure that the output gives you what you want, you can move on to the fun part, the automation part.

Using the Command Line Syntax

The third step is using the command line interface with RoboHelp to generate the online help for a particular product and customer.

On the Windows desktop, open a command prompt window. You can either use Start > Run > cmd, or select it from the menu Start > Programs > Accessories > Command Prompt.

Type this command (or a similar one tailored to your system) and press Enter.

rhcl "C:\Source\ProductXYZ\Online Help.xpj" -l "CustomerA Layout" -o "C:\Source\ProductXYZ\!SSL!\CustomerA Layout\ProdXYZ CustA 2011-03-18" -g "C:\generatedhelp\OnlineHelp Logs\helplog.txt"

Thanks to Paul Hanson for advising me that a quote is required after 2011-03-18 above.

This of course is specific to a product, to a customer, to a date, and to a location on my machine. Let's break down the pieces:

RHCL command

rhcl

This first piece is the RoboHelp command line executable command and kicks off the program. For details on the parameters, type:

rhcl -?

Source Location

"C:\Source\... .xpj"

This piece is the "C:\Source... .xpj" path and file name of the Project file. This is the location of the Project file (the .XPJ file) and this will differ for each product. The example above is on my hard drive but just as easily be on a network drive. It is bounded by quotes because the path name has spaces in it.

Layout

-l "CustomerA Layout"

This piece is the -l parameter (L for Layout) and its value. This allows you to specify the layout that I dealt with in the previous step. Now by default I have been using WebHelp Pro and could simply type "WebHelp Pro" but what you will get is the default settings for that layout and not our customized options. So before you can use this command I have shown here, you have to define the "CustomerA Layout". It is bounded by quotes because the path name has spaces in it. All these options are specific to that customer and product which, in the GUI, are set using the Generate Layout menu choice through a series of wizard screens. So when you have it done in the GUI, then generate it as a layout with a specific name, the command line can now use that layout.

Output Location

-o "C:\Source\..."

The next piece is the -o parameter and its value. This allows you to specify the output destination. You could specify the output location in the Layout (see above) but if you want to change the location each time you build it, you can set a different output option without changing the layout. Here I have the location include a folder for a customer and a subfolder with the date for each time I deliver a help to that customer. It is bounded by quotes because the path name has spaces in it.

Log Output

-g "C:\generatedhelp\OnlineHelp Logs\helplog.txt"

This piece is the -g parameter and its value. This allows you to keep a record of the log, saving the information (that RoboHelp would ordinarily simply display on a screen) to a log file. You specify the location and name of the log file. Be sure the folder exists - RoboHelp doesn't create it. I like this feature because I can keep track of the build and if there are any errors, I can refer to something, copy and paste to a browser in order to search, etc. You can give it a generic name (helplog.txt) and overwrite it each time, or you could give a specific name, such as including the date and time (helplog-2011-10-09-0800.txt) and keep records of all your builds.

If you don’t use the log option, the prompts that display in the command line window look like this.

Microsoft Windows XP [Version 5.1.2600]

(C) Copyright 1985-2001 Microsoft Corp.

C:\bill>rhcl "C:\Source\ProductXYZ\Online Help.xpj" -l ProductName
-o "C:\Source\ProductXYZ\!SSL!\CustomerA Layout\ProdXYZ CustA 2011-03-18"
Adobe (R) RoboHelp Project Command Line Compiler version 7.00.145
Copyright (C) 2006-2007, Adobe Systems Incorporated and its licensors. All rights reserved.

Project: C:\Source\ProductXYZ\Online Help.xpj
Layout: WebHelp.
Output: C:\Source\ProductXYZ\!SSL!\CustomerA Layout\ProdXYZ CustA 2011-03-18\start_page.htm.

Scanning project for compilation....
Scanning finished.
Warning: No baggage file description.
Starting compilation...
WebHelp preprocessor 7.00.145

Compiling C:\Source\ProductXYZ\!SSL!\CustomerA Layout\ProdXYZ CustA 2011-03-18\start_page.htm ...

Preparing to create WebHelp...
Clearing output folder...
Preparing files for WebHelp...
Copying files...
Updating files...
Finished preparing in 6 sec(s)

Initializing compiler...
Generating WebHelp 5.50 (7.01.001)...
Processing TOC data...
Processing Index data...
Processing Context-sensitive-Help data...

Updating HTML topics...
...
Updating help-topic01.html...
Updating help-topic02.html...
Updating help-topic03.html...

Updating start_page.htm...
Finished updating HTML topics in 2 sec(s) : total 85 topic(s).

Processing Full-text-search data...
................................................................................
Finished processing Full-Text-Search data in 1 sec(s)

Applying WebHelp 5.50 Template...
................................................................................
Finished applying Template in 2 sec(s)

Added result path to RoboHelp7.cfg
Finished compiling WebHelp in 13 sec(s)

Compilation complete.

Running an Automated Build Process

The fourth step is running that command as part of the build process so it happens automatically. You can set up batch files and use Microsoft's Task Scheduler or you can add the command as part of whatever batch you are running for building the software.

From Rob Houser

"Command line compilation is a pretty useful feature, especially if you're using source control or have very large projects to manage. I was impressed that the online help gives you plenty of examples about how to set up batch files and use Microsoft's Task Scheduler. Since you can activate two copies of RoboHelp, you could use your second activation for the server. According to the EULA, you can't compile on the server and use RoboHelp on your desktop at the same time. However, you could do overnight builds on the server."

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