Publishing a Document for HTML Help (Windows Only)

Prerequisites: Arbortext Publishing Engine, Arbortext Styler, or Web/Wireless Composer Option and HTML Help Workshop

You can use Arbortext Editor to transform XML documents into HTML Help. The File > Publish > For HTML Help option breaks the document into separate HTML topics, and then combines them into one .chm file. By default, Arbortext Editor is configured to create HTML Help for documents based on the Arbortext XML DocBook (axdocbook.dtd) document type. To publish documents to HTML Help based on other DTDs, you can contact consulting services.

The For HTML Help option will be visible on the Publish menu, but will be unavailable until you install Microsoft's HTML Help Workshop. You can download the latest version from Microsoft's web site http://www.microsoft.com. Search within the MSDN Library for this download, as it may not be listed with the standard download choices, and be sure to install the full Workshop and not just the Viewer.

You must start and close HTML Help Workshop once before you can choose File > Publish > For HTML Help.

If your document includes graphics, you must specify graphic width and depth attributes in pixels if you want these attributes set in the HTML output. Web browsers can't interpret graphic width and depth attributes that are specified in measurements other than pixels.

Equations with TeX input will display as blank boxes in HTML output.

To publish a document for HTML Help:

1. To publish HTML Help in CJK languages, you must first set the Windows locale and default language settings to the desired language. Refer to your Windows operating system documentation for information on changing locales and languages.

3. Specify the path and file name to which you want to save the HTML Help file in the Save As field. Click Browse to locate an existing file.

4. Select the View Help File option if you want the document to display in the HTML Help Viewer after it is published.

If you select the View Help File option and your document file name includes an ampersand (& symbol), Arbortext Editor will respond that it cannot launch the HTML Help Viewer. Select Yes to publish with the viewer disabled, or No to cancel the publishing process.

5. Select the appropriate stylesheet from the Stylesheet list. A stylesheet that supports web publishing also works for HTML Help. Click Browse to locate an existing stylesheet that does not appear in the list.

If you are Using Arbortext Publishing Engine for Publishing Documents, the list displays the stylesheets available from the Arbortext Publishing Engine server. The notation (pe) appears in the stylesheet name. Local stylesheets are ignored, and you can't send one to the server with your document.

6. If you are publishing a DITA document that has an associated DITAVAL file, choose that file in the DITAVAL File list. Click Browse to locate an existing DITAVAL file that does not appear in the list.

7. If your document has change tracking, you can publish the document in any of the change tracking states. By default, the change tracking view from the Edit window is selected, except when publishing from a DITA map.

If you are publishing a DITA map, Changes Applied is selected by default. When publishing from a DITA Map, the Change Tracking view that's selected applies only to the topics referenced from the DITA maps. The DITA map itself, as well as other referenced maps, will always be published with Changes Applied, regardless of the Change Tracking view selected (even if a map has change tracking markup).

◦ Changes with Highlighting — Shows all proposed changes, highlighted with revision marks.

◦ Changes Applied — Shows all proposed changes incorporated into the document, without revision marks.

◦ Original — Shows the original document without proposed changes incorporated into the document.

8. If you choose Queue Transaction, you will be prompted for the Save As file name and whether to View Help File when you retrieve the result from your list of Queued Transactions, available from the Tools menu. Choosing to Queue Transaction clears Save As and View Help File values from the dialog box. If you entered values in these fields, they will be displayed again if you clear the Queue Transaction check box.

9. Choose whether to enter a Transaction Name. The transaction name will be displayed when you retrieve the result from your list of Queued Transactions, available from the Tools menu.

You can enter transaction names to use by default or for specific output types by entering values in the Queued Transaction Names Dialog Box.

10. If you want to apply profiling to your document, click Set Profiles to access the Set Profiles dialog box. Click OK or Cancel to exit the Set Profiles dialog box. The Set Profiles button is only available if profiles have been configured for the selected document type.

11. If you want to create a publishing rule, click Create Rule to open Create New Publishing Rule, where you can create a new publishing rule or rule set for publishing HTML Help.

Be aware of the following items when publishing to HTML Help:

• If you are Using Arbortext Publishing Engine for Publishing Documents, HTML Help Workshop must be installed on the Arbortext Publishing Engine server. If View Help File is checked when the published HTML Help file is returned, Arbortext Editor will display it in a local HTML Help Viewer.

• Arbortext Editor replaces some character entities during the publishing process because they do not display properly. The replacement character entities are defined in the Arbortext-path\composer\htmlHelpNavEntSub.xml. This file controls entity substitution for the HTML Help navigation pane only; it does not support entity substitution for the HTML Help content pane.

• Arbortext Styler supports three different methods of including CSS information in HTML output. Refer to CSS files in HTML output for more information.

• The Microsoft HTML Help Compiler (hhc.exe) cannot create .chm files in a directory that has a path containing a folder name starting with a period. If your APTCACHE environment variable specifies a directory with such a folder, the Help Compiler will fail when attempting to create a .chm file. A workaround is to use the APTCACHE environment variable to specify a directory containing no folder names beginning with periods.

HTML Help Workshop sometimes has trouble configuring itself in current versions of Microsoft Windows. After installing it, you should see a menu option File > Publish > For HTML Help in Arbortext Styler. If that option is disabled, it means Arbortext Styler cannot identify the program to use for HTML Help files.

To fix it, you can force the association of *.hhp files with Help Workshop:

2. In Windows Explorer, double click the file. You get a prompt from Windows about which program you want to use to open it. Select the More programs option, and navigate to C:\Program Files (x86)\HTML Help Workshop, and select hhw.exe. Make sure the Always use this program option is selected.

3. If Arbortext Styler is open, close it and reopen it. The HTML Help publishing option is now available.