October 2000: Generating WebHelp
This Help Corner column was originally published in October, 2000, and written for RoboHELP Office Version 9.
by Char James-Tanny
WebHelp 4, available only from RoboHELP HTML Version 9, has several new features.
For the latest news on WebHelp, visit the RoboHELP Community Forums. Posts cover everything from developing WebHelp to determining why it isn't displaying correctly.
Oracle Help will be covered in a future column. I need to do more research on this new Help format!
- Developing a WebHelp Project
- Cross-Platform Tips
- Customizing the WebHelp User Interface
- Generating WebHelp
- Viewing WebHelp During Development
- Publishing WebHelp with the Smart Publishing Wizard
- Displaying WebHelp
Developing a WebHelp Project
Use WebHelp to publish any kind of online documentation, online Help (including context-sensitive Help), and Web sites (to the user's PC) or on an intranet, extranet, or the Internet.
First, create an HTML Help project or use one of the custom templates. Then:
- Add topics, which are HTML files explaining different concepts to your users. Topics can be informational or context-sensitive, depending on the results you want. When creating context-sensitive topics, work with your application programmer to determine the necessary file names so that the results display as expected.
- Add hyperlinks, graphics, and other content as desired.
- If needed for your results, add a Table of Contents and an Index.
- Add enhanced topic navigation, including browse sequences and Related Topics, See Also, and Keyword Search links.
- Generate the WebHelp files, specifying the options you want to include.
- Publish the WebHelp files. RoboHELP HTML includes the Smart Publishing Wizard for quick and easy deployment to an Internet or Intranet server.
Starting a WebHelp Project
To create a new WebHelp project:
- Start RoboHELP HTML. You'll be prompted to open an existing project or create a new one.
- If you are creating a new project, choose either HTML Help or WebHelp as the project type. The only difference between the two project types is the primary target setting.
- I typically use HTML Help as the project type for my WebHelp files. I modify the window definition to take up my entire screen, which makes it easier to see the results. I let the compiler track any errors and I use the .chm file to see how the WebHelp will look when viewed through Internet Explorer. Then, I generate the WebHelp files on a regular basis and verify their appearance in both browsers.
- Enter all information in the New Project dialog box, including project title, path, and name of the first topic.
- I suggest that you name the first topic index.htm as a security measure. Whenever you type a URL, the browser immediately looks for an HTML file called index. If one isn't found, then the folder information displays. By calling your first topic index.htm, you guarantee that the folder includes an index file.
- Once your project is created, the first topic opens in the WYSIWYG Editor so you can start working with it. On the left, the Project Manager opens.
Setting WebHelp as the Primary Target
If you have an existing project that was originally targeted for a different output format, you can change the target to WebHelp.
From the RoboHELP File menu, choose Select Primary Target | WebHelp.
If you choose to create a WebHelp project from the New Project dialog box, this option is already selected.
Once WebHelp is set as the primary target, the Generate Primary Target icon creates WebHelp files instead of a .chm file.
You can use the following items when developing your WebHelp project.
- Cascading Style Sheets. When WebHelp is generated, the style sheet you used in development is assigned to topics when viewed through Internet Explorer. The style sheet is copied and modified slightly for topics viewed through Netscape Navigator. A script is added to all topics that specifies which style sheet should be used.
- Therefore, if you used four style sheets in development, your resulting WebHelp folder will contain eight style sheets.
- You should verify the Netscape style sheets before deploying your project. Cascading Style Sheet bugs in Netscape can give you a headache, but there is some relief. Visit the CSS Pointers Group-Bugs and Workarounds or WebReview for the lists of bugs.
- Expanding/collapsing Table of Contents
- Related Topics lists
- Auto-synching Table of Contents. This new feature in WebHelp lets you add a Sync TOC button to your topics.
- Images and interactive images
- Full-text Search
- Multi-level Index
- Context-sensitive Help
- Dynamic HTML. Please be careful with this! The RoboHELP HTML Dynamic HTML is Internet Explorer- specific, although it should work with the new Netscape Navigator (currently in beta). Expanding and drop-down boxes work as expected in Internet Explorer, but are fully expanded in Netscape. This won't be much of an issue if you know your users are standardized on Internet Explorer.
- Hyperlinks to URLs, email addresses, newsgroups, and FTP sites
- Be sure to add a Macintosh font to your font set. To add a font to a font set, from the Format menu, select Font Sets. From there you can create or modify a font set. Because you are developing on a Windows system, only Windows fonts display in the font list. However, you can type the name of a Macintosh font (for example, Helvetica, Geneva, or Sans Serif) to add it to your font set.
- For versions of Internet Explorer before 5, Macintosh fonts typically display at a smaller font size than their corresponding Windows counterparts. Use relative font sizing (for example, Medium) instead of absolute point size (for example, 10pt).
- UNIX is case sensitive. All file requests must exactly match the case of the file name or error messages result. Thus, WebHelp provides the Always Use Lowercase option.
- Be sure to add a UNIX font to your font set. To add a font to a font set, from the Format menu, select Font Sets. From there you can create or modify a font set. Because you are developing on a Windows system, only Windows fonts display in the font list. However, you can type the name of a UNIX font (for example, Helvetica) to add it to your font set.
- If the Table of Contents (.hhc) and Index (.hhk) do not display after you have published WebHelp to a UNIX server, it means that the MIME types for the Table of Contents (.hhc) and Index (.hhk) are not associated correctly. Ask your ISP or system administrator to add the HHC and HHK extensions to the TEXT/HTML MIME type on the server.
Internet Explorer 5.x Browser
- Publish the WebHelp files to a subfolder under your server's root drive. For example, publish them to s:\webhelp or <URL>/webhelp.
Internet Explorer 3.0x Browser
While most users have updated their Internet Explorer to versions later than 3.0x, this information is provided in case some of your users are viewing WebHelp in this older browser.
- Internet Explorer 3.0x supports embedded and inline styles. You should not use external style sheets, as Cascading Style Sheets are not supported in Internet Explorer 3.0.
- Dynamic HTML is not supported in Internet Explorer 3.0. You can use Dynamic HTML effects in your Help system, but they will display as static effects in this browser.
- Java applets do not resize when the browser is resized.
Opera 3.51 and 3.60 Browsers
- Hyperlinks in topics displayed in popup windows display the target in the popup window. Keep this in mind as you plan the hyperlinks in your topics.
Netscape Navigator Browsers (All Versions)
- If you are deploying WebHelp onto a LAN (for example, with a file server-based application), be sure to map drives on the LAN. Netscape won't load Java applets from locations specified by UNC file names. For example, do not use \\<server>\share\paint.htm. Instead use G:\server\share\paint.htm.
- In Netscape, file names cannot contain spaces. This includes graphics and folders, which are easy to overlook.
- Netscape Navigator 4+ has numerous limitations in the implementation of Cascading Style Sheets. These may prevent the display from matching your design. If they don't match well, verify the definitions in your Netscape style sheets.
- Older versions of Netscape (before 4.6) ignore margin settings. As a result, the right side of all topics tends to run over the browser window. If your users are likely to use earlier browsers, apply a 6-point indent to the right margin of <BODY> in your style sheet and set tables to 97% of the window width.
- Older versions of Netscape (before 4.61) do not correctly resize Java applets when the window is resized. This affects the Table of Contents and Index.
- If any specified style sheets are not available when the HTML file loads, Netscape will crash. Be sure to use the Smart Publishing Wizard (or copy the entire WebHelp folder to your server) to ensure that the style sheets are available.
- Netscape does not directly support ActiveX technology. It is recommended that you don't add ActiveX controls to WebHelp projects if you have users running Netscape browsers.
- Netscape does not support standard W3C Dynamic HTML. Thus, all Dynamic HTML effects display as static effects.
Customizing the WebHelp User Interface
You can customize how WebHelp displays to suit your needs and the needs of your users.
Displaying a Table of Contents
You can specify whether or not to display the Table of Contents tab during the WebHelp generation process. To add or remove the Contents tab from the navigation pane, select or clear TOC.
Displaying an Index
You can specify whether or not to display the Index tab during the WebHelp generation process. To add or remove the Index tab from the navigation pane, select or clear Index.
Displaying the Search Tab
You can specify whether or not to display a Search tab during the WebHelp generation process. To add or remove the Search tab from the navigation pane, select or clear Search.
The Search tab allows your users to easily find information in your Help system using Full-Text Search.
Adding an In-Topic Navigation Bar
You can specify special in-topic Navigation options when you generate WebHelp. When browse buttons, WebSearch, auto- synching the TOC, or show/hide the navigation pane are selected, the buttons display in an in-topic Navigation Bar. You control where this button bar displays in the right pane: at the top right, top left, bottom right, or bottom left.
Adding Custom Image or Text Buttons
The in-topic Navigation Bar is fully customizable. You can choose to use either text or images for the elements.
By default, the in-topic Navigation Bar uses images that look like text buttons. However, you can use your own images instead of the defaults. First, create the image that you want to use. It should be a GIF or JPEG image. Some settings, such as Show/Hide Navigation Pane, need two images (one for Show and one for Hide). Then, when generating WebHelp, select the setting for which you've created an image, click on the image that you want to change, and specify your new image file.
You can customize text buttons by changing the text that displays. When generating WebHelp, select the setting that you want to use, click on the text button that you want to change, and type the new text.
Enabling Browse Sequences
To display browse buttons, select Browse Sequences while generating WebHelp. This enables you to provide browse sequences in WebHelp, if they have been defined in your project.
Browse sequences allow your users to step through a predefined set of topics, like turning the pages in a book.
You need to have created browse sequences in the project for the browse sequence buttons to display.
To provide quick access to WebSearch from your WebHelp project, select WebSearch when generating WebHelp.
When you enable WebSearch, your users get customized, context-sensitive Internet searches right from the Help system. WebSearch provides users with Internet search results based on the content of the Help system. For example, searches can target a topic title, or index (K- Keywords) terms for a topic, or even the Table of Contents book names in the Help system. It's a fast and convenient way to extend Help for your users.
Synching the Table of Contents
By adding a Sync button to your topics, you enable your users to quickly find the topic's location within the Table of Contents. To add or remove the Sync button, select or clear Synchronize TOC when generating WebHelp.
To produce your WebHelp files:
- Create your topics, taking into account the previously mentioned items. Add hyperlinks, graphics, and other items as desired.
- Create your Table of Contents and Index.
- On the Project tab, double-click WebHelp under the Single-Source folder or select File | Generate | WebHelp.
If you will be producing only WebHelp, select File | Select Primary Target | WebHelp. Then, click the Generate Primary Target icon to produce your WebHelp files. However, the functionality of your project isn't verified when generating WebHelp only. Make sure you check the Broken Links and Images folders on the Project tab or generate HTML Help, where the HTML Help compiler will verify links, images, and other functionality.
The WebHelp General dialog box appears.
On this screen, you can:
- Type the folder and start page names for the WebHelp project. By default, WebHelp projects are stored in a WebHelp folder under your project folder. If desired, click the Open Folder icon to display the Save As dialog, where you can navigate to the correct folder.
- If you have defined build tags in your project, specify a build expression for the results.
- Specify the options for the Navigation Pane. By default, TOC, Index, and Search are selected.
- Select your Preferred Format for the navigational options when your WebHelp files are displayed in Internet Explorer. Netscape Navigator always uses a Java applet.
- Click Always Use Lowercase to convert all file names, hyperlink targets, and so on to all lowercase. While Windows servers are not case sensitive, UNIX servers are. This option guarantees that your WebHelp project displays correctly on a UNIX server. The default setting is unchecked.
- After selecting your options, click OK.
- When finished, click Next to display the WebHelp In- Topic Navigation Bar dialog.
On this screen, you can:
- Set the Location for the topic navigational bar, which can contain as many as four buttons or text links (Show or Hide Navigation Pane, Synchronize TOC, and the Previous and Next browse buttons). Click the drop- down arrow and select from Top Left, Top Right (default), Bottom Left, or Bottom Right.
- Choose to display either Image buttons or Text links for the selected elements by clicking the drop-down arrow next to Style. The samples under the Detail section reflect your selection by displaying buttons or text links, which you can modify.
- Select the navigational elements that you want to display in the different topics: Show/Hide Navigation Pane, Synchronize TOC, Browse Sequences, and WebSearch. Browse Sequences and WebSearch display only if implemented in your project. To toggle an element, you must click in the checkbox. Clicking over the label updates the Detail section, but doesn't select the element.
- Click Preview to display a sample topic with the selected navigational elements.
- Click Restore Defaults to reset all options to their original settings.
- Accept the default images and text links or modify them.
- To modify an image button, you must first create the new button in a graphics application. When you click on the image to change it, the Open dialog appears, where you specify the new file.
- To modify a text link, type the new label in the field.
- When you're done making modifications, click Finish.
If WebHelp has already been generated for this project, the WebHelp message displays.
All files currently stored in the WebHelp folder will be deleted before the new WebHelp files are generated. Click Yes to continue.
If you have customized any files that you want to preserve, such as a Cascading Style Sheet for Netscape Navigator, copy the files to another folder before generating a new version of WebHelp. Then, copy them back before deploying the files. Do not use this method for any files in which you have changed the content, such as a topic file. In this case, you must make the customized changes again.
As RoboHELP HTML generates the WebHelp files, various messages display in the status bar. When the files have been generated, the WebHelp Wizard Result message displays.
- Click View Result to display WebHelp in your default browser. If you want to select the browser that WebHelp uses, close this box and select File | Run | WebHelp with Netscape Navigator or File | Run | WebHelp with Internet Explorer. You can change the browser executables by modifying the settings in the Options dialog.
- Click Publishing to start the Smart Publishing Wizard. See Deploying WebHelp for more information.
- Click Close to return to RoboHELP HTML without viewing or publishing the results.
Viewing WebHelp During Development
When you click View Results after generating WebHelp, your project displays in your default browser. You can view WebHelp in a specific browser by using the File | Run menu. Select WebHelp with Internet Explorer or WebHelp with Netscape Navigator.
Publishing WebHelp with the Smart Publishing Wizard
Use eHelp's Smart Publishing Wizard to copy the WebHelp folder to your server. This folder includes all files created by RoboHELP HTML, as well as your topics (HTML files), graphics, Cascading Style Sheets, and any other files you used when creating your project. Subfolders used in the original project are maintained in WebHelp.
You can launch the Smart Publishing Wizard from the final WebHelp dialog (after generating the WebHelp files) or from the Tools tab at any time.
When launching the Wizard from the Tools tab, the Select Source dialog displays.
The Source Location is blank when you first launch the Smart Publishing Wizard. Click the drop-down arrow to select from a list of previously deployed files or folders, or click Select File/Folder to select the desired folder, and, if needed, the specific file, from your system. This enables you to publish entire folders or only specific files.
In the Select File/Folder dialog, click Select Folder after navigating to the correct folder or Select File after selecting the desired file.
Click Publish Subfolders to deploy all folders under the source. This option activates when a valid folder has been typed into the Source Location field.
If there aren't any subfolders under the source, Publish Subfolders still activates.
When finished, click Next.
When launching the Wizard after generating WebHelp, or after clicking Next on the first screen when launching the Wizard from the Tools tab, the Select Destination dialog displays.
If you have already used the Smart Publishing Wizard, previous destinations display in the top section. If you haven't used the Smart Publishing Wizard before, or if you want to add a new destination, click New. The New Destination dialog displays.
- Enter the name for this configuration, which will display in the top section of the Select Destination dialog.
- Select your connection protocol: FTP (default), HTTP, or File System. The FrontPage radio button is active only if FrontPage is installed on your system.
- FTP (or File Transfer Protocol) is a secure method of uploading files from one system to another. Typically, a password is required, unless the FTP site has been configured to allow anonymous access.
- HTTP (or HyperText Transfer Protocol) is a non- secure method of uploading files from one system to another. The target system must be configured to accept HTTP access.
- FrontPage Enabled lets you deploy your files using the FrontPage interface. FrontPage must be installed on your system
- File System is a non-secure method of uploading files from one system to another on a local area network or to a different drive on the same system.
- The center section changes according to the connection protocol.
- For FTP, type the host name (typically, ftp.URL.com). Unless your server is specifically configured to use a different port, accept 21 as the default port. If your server allows anonymous users, leave the checkbox selected. Otherwise, click the checkbox and type the user name and password. By default, the password is saved on your system. For more security, click the checkbox to disable the feature. Type the target directory in the Server Directory field. The default, /, deploys the files to the root folder on the server. If the specified folder doesn't exist, it will be created on the server automatically.
- For HTTP, type the host name provided by your Internet Service Provider and the Server Directory information.
- For FrontPage Enabled, type the destination path.
- For File System, type the destination drive and folder or click the Open Folder icon to select the target folder from your system or network drives. If you type a new folder name and it doesn't exist, a confirmation message displays before the folder is created. Click Yes to create the folder or No to return to the Destination dialog.
- When you're finished, click OK to continue.
The remaining options on the Select Destination dialog box are:
- Remove a destination by selecting it and then clicking Delete. When the message displays, click Yes to delete or No not to.
- Modify an existing destination by selecting it and then clicking Edit. The Edit Destination dialog displays, which looks like the New Destination dialog with the information entered.
- Click Check for Deleted Files to compare the current file list to the previously deployed file list. If you have deleted files from your system, the Smart Publishing Wizard will delete them from the target destination. However, this slows the publishing process.
- Click Prompt Before Overwriting Files to display a confirmation message before replacing existing files.
- Click Republish All to deploy all files, regardless of the date. If not selected, the Smart Publishing Wizard will compare the time/date stamps on all files and copy only those files which have been changed since the last time you deployed.
When you're finished, click Next. The Publish message displays, where you verify the source and target folders. If the information is correct, click Finish.
After all files have been copied, the Publishing Successful message displays. It displays the total number of files in the WebHelp folder, number of files published, and elapsed time, and the list of published files.
The Smart Publishing Wizard tracks the files in your WebHelp project and doesn't republish those files that haven't changed. Therefore, the number of total files might be different from the number of files published. The most common files that are republished but that haven't changed are standard WebHelp files, such as ehelp.xml.
After verifying the list of files, click Close.
There are two ways to display a standard WebHelp project.
- Create a standard hyperlink, calling the start page name.<A HREF="startname.htm">WebHelp Project</A>
- Create a new HTML file that loads the WebHelp start page by modifying the <BODY> tag. Then, create a link to this new file, using the preceding syntax.<BODY ONLOAD='location="startname.htm"'>
If you are using WebHelp for context-sensitive Help for your site, specify the start page name. This loads the WebHelp frameset and navigation (Table of Contents, Index, and Search tabs). The user then locates the desired topic. If you are using WebHelp for context-sensitive Help for your page or field, specify the file name of the topic that is to display.
The first time a user clicks the Search tab, the Search file is loaded, so a small time delay results.
Portions of this column have been taken from Sams Teach Yourself RoboHELP 2000 for HTML Help in 24 Hours by Char James-Tanny, ISBN 0-672-31625-0. Used with permission from Macmillan Computer Publishing USA. Portions of this column have been taken from The WebHelp Resource Guide by Char James-Tanny. Used with permission from eHelp Corporation.
Copyright © 2000 Char James-Tanny.