Lesson 2: Using the HTML Help Workshop
Lesson 2: Using the HTML Help Workshop
Microsoft Visual Studio .NET includes the HTML Help Workshop, which is installed in a separate location on the developer s machine. In this lesson, you ll learn how to use the HTML Help Workshop to create a compiled Help file that includes a table of contents, an index, and full-text search capabilities.
After this lesson, you will be able to
Create a new Help project
Add topics to a Help project and compile those topics into a single Help file
Build a table of contents automatically during compilation
Modify an automatically generated table of contents
Add index keywords to Help topics
Create different types of cross-references between topics within a Help file
Add special features such as associative links and Related Topics links to Help topics
Enable full-text searches within a Help file
Compile and preview Help from the HTML Help Workshop or from the command line
Estimated lesson time: 30 minutes
Creating HTML Help
An HTML Help file is made up of individual HTML pages, each representing a single Help topic. Each Help topic can include keywords that are included in the index and cross-references to other topics. HTML Help projects include the types of files described in Table 14-1.
File type | Use to |
Help topic (.htm) | Create content to display in Help |
Project (.hhp) | Define how the project is compiled and which Help topic, contents, and index files to include |
Contents (.hhc) | Create a table of contents for the Help file |
Index (.hhk) | Create an index for the Help file |
Search stop list (.stp) | Exclude specific words from searches |
Compiled (.chm) | Deploy the completed Help file |
The HTML Help Workshop provides tools to organize, edit, and compile these files. By default, Visual Studio .NET installs the HTML Help Workshop in the Program Files\HTML Help Workshop folder during setup.
To create a new HTML Help project, follow these steps:
From the HTML Help Workshop File menu, choose New. The New dialog box opens.
In the New dialog box, select Project and click OK. The New Project Wizard opens. The wizard lets you convert an existing WinHelp project or create a new HTML Help project.
Click Next to create a new project. The wizard displays the Destination page.
Type the location and name of the Help project file you want to create, and then click Next. The wizard displays the Existing Files page.
Select the check boxes for any contents, index, or topic files you ve already created, and click Next. If you select any of these existing files, the wizard prompts you for the location of each of the selected file types. Otherwise, the wizard creates a new, empty Help project, as shown in Figure 14-4.
Figure 14-4. A new, empty Help project
Using HTML Help Workshop is fairly simple. You use the Project, Contents, and Index tabs on the left pane to edit the contents of the project, contents, and index files. The buttons at the top of the pane create new files, open existing files, compile the project, display the compiled project, and display HTML Workshop Help.
To add topic files to the Help project, follow these steps:
Click the New button on the toolbar, select HTML File in the New dialog box, and then specify a title for the topic. The Workshop creates a new Help topic file, as shown in Figure 14-5.
Figure 14-5. Creating topic files
Save the HTML file, and then click Add/Remove Topic Files on the Project tab. The Topic Files dialog box opens.
Click Add, and then select the files to add to the project. Click Open.
Click OK to close the Topic Files dialog box. The Workshop adds the file to the project.
The HTML Help Workshop provides only basic text-editing capabilities. In general, you author your Help topic files in a full-featured HTML editor, such as Microsoft FrontPage, and then use the Workshop to create the project file and compile the Help.
Setting Project Options
Help project options are displayed on the Project tab of the HTML Help Workshop. These options are stored in the Help project file (.hhp) in plain text and can be modified using the HTML Help Workshop or a text editor such as Notepad.
To set project options in the HTML Help Workshop, on the Project tab, click Change Project Options. The Workshop displays the Options dialog box, as shown in Figure 14-6.
Figure 14-6. Setting options
The project options let you specify a title for the Help project, locale information about the project, how the contents and index files are created, whether to support searching, and other features. These items are placed in the OPTIONS section of the project file. For example, the following project options create index and contents files automatically when compiling a Help file named HelpSample.chm, which displays the title HTML Help Sample in the Help window:
[OPTIONS] Auto Index=Yes Auto TOC=9 Compatibility=1.1 or later Compiled file=HelpSample.chm Contents file= Contents.hhc Default topic=topic1.htm Display compile progress=No Full text search stop list file=Search.stp Index file=Index.hhk Language=0x409 English (United States) Title=HTML Help Sample
The project file also includes a FILES section that lists the Help topic files to compile. The order of the files in this section determines the order of items in the contents file when Auto TOC is selected in the OPTIONS section. For example, the following topic files appear in sequential order in contents:
[FILES] topic1.htm topic1a.htm topic1b.htm topic2.htm topic3.htm
Building Tables of Contents
When building the table of contents automatically, the HTML Help Workshop uses the heading level of the topic and its order in the FILES section of the project file to determine how the table of contents is organized.
The Workshop puts <h1> headings at the top level, <h2> headings under those, and so on until a new <h1> heading is encountered. If you have multiple heading levels within a single topic, the Workshop creates subordinate contents items for each of those headings even though they all represent the same Help topic. For this reason, it s best to use only one HTML heading element per Help topic when generating contents automatically.
For example, the following FILES section includes topic files with three heading levels, as indicated by their file names:
[FILES] topic1.htm topic1a.htm topic1b.htm topic2.htm topic2a.htm topic2b.htm topic2bi.htm topic2bii.htm topic3.htm
At run time, the generated contents files appear as shown in Figure 14-7.
Figure 14-7. Automatic table of contents
The Workshop stores the generated table of contents in an HTML file. You can generate an automatic table of contents, turn off Auto TOC in the project file, and then edit the generated contents file to customize the table of contents.
To edit a contents file, click the Contents tab in the HTML Help Workshop. The Workshop displays the contents, as shown in Figure 14-8.
Figure 14-8. Editing the contents file
One thing you might have noticed in the automatic contents shown in Figure 14-8 is that the icons for top-level topics aren t consistent. For instance, Topic 3 shows a page icon rather than a book icon.
To change the icon displayed for a topic, follow these steps:
On the Contents tab, select the contents topic, click Edit Selection, and then in the Table Of Contents Entry dialog box, click the Advanced tab, as shown in Figure 14-9.
Figure 14-9. Changing the contents entry icon
Select the image to use for the entry in the Image Index list box, and then click OK.
The contents file is stored as an HTML file that uses object elements to specify the contents items, as shown by the following HTML:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <HTML> <HEAD> <meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1"> <!-- Sitemap 1.0 --> </HEAD><BODY> <UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic1"> <param name="Local" value="topic1.htm"> </OBJECT> <UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 1.a"> <param name="Local" value="topic1a.htm"> </OBJECT> <UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 1.a.i"> <param name="Local" value="topic1ai.htm"> </OBJECT> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 1.a.ii"> <param name="Local" value="topic1aii.htm"> </OBJECT> </UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 1.b"> <param name="Local" value="topic1b.htm"> <param name="ImageNumber" value="1"> </OBJECT> </UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 2"> <param name="Local" value="topic2.htm"> </OBJECT> <UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value=""> <param name="Local" value="topic2.htm"> </OBJECT> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 2.a"> <param name="Local" value="topic2a.htm"> </OBJECT> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 2.b"> <param name="Local" value="topic2b.htm"> </OBJECT> </UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Topic 3"> <param name="Local" value="topic3.htm"> <param name="ImageNumber" value="1"> </OBJECT> </UL> </BODY></HTML>
The HTML list elements specify the hierarchy of the items in the table of contents. The object elements specify the title, icon, location, and other information about the link. For example, the following contents item links to a company s New Products page and opens the page in a new window when the user clicks it:
<OBJECT type="text/sitemap"> <param name="Name" value="New Products"> <param name="Local" value="http://www.mycompany.com/newproducts.htm"> <param name="WindowName" value="NewWindow"> <param name="Comment" value="Sample of text/sitemap params"> <param name="New" value="1"> <param name="ImageNumber" value="7"> </OBJECT>
Adding Index Entries
The HTML Help Workshop can automatically build an index file from object elements entered in the topic files. Within a topic file, an index entry is created as an ActiveX object with a specific classID, as shown in the following HTML:
<Object type="application/x-oleobject" class> <param name="Keyword" value="Index Item 1"> <param name="Keyword" value="Index Item 1, Subitem a"> <param name="Keyword" value="Index Item 1, Subitem b"> </OBJECT>
The preceding HTML creates three index entries for that link to the topic file, as shown in Figure 14-10.
Figure 14-10. Automatic index entries at run time
The HTML Help Workshop does not automatically store index entries from topic files in the index file; however, you can add index entries to the index file to help organize or to supplement the automatic entries. The index file (.hhk) and the topic index entries are added together to create the index displayed in the compiled Help file. For example, the following index file (.hhk) is combined with the automatic entries to create the results shown in Figure 14-11:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <HTML> <HEAD> <meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1"> <!-- Sitemap 1.0 --> </HEAD><BODY> <UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Index Item 1"> <param name="Name" value="Topic 1.b"> <param name="Local" value="topic1b.htm"> </OBJECT> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Index Item 2"> <param name="Name" value="Topic 2.a"> <param name="Local" value="topic2a.htm"> </OBJECT> </UL> </BODY></HTML>
Figure 14-11. Combined index entries
Adding Cross-References
There are three ways to cross-reference Help topics within HTML Help:
Use standard HTML hyperlinks to create a link from one Help topic to another. Hyperlinks allow one-to-one relationships.
Use the Related Topics command to create a link from one topic to a list of other specific topics files.
Use associative links (ALinks) to create links from one topic to a list of other topics based on keywords entered in those topic files.
Because you already know how to create hyperlinks (by now, you d better), the following sections discuss how to add related topics and create associative links.
Adding Related Topics
You can add related topics as a cross-reference or a hyperlink.
To add a related topics cross-reference to a Help topic, insert an HTML Help ActiveX control in the topic file. For example, the following object element displays a button that lists two related topics as pop-up menu choices:
<OBJECT id=hhctrl type="application/x-oleobject" class codebase="hhctrl.ocx#Version=4,74,9273,0" width=100 height=100> <PARAM name="Command" value="Related Topics, MENU"> <PARAM name="Button" value="Text:Related Topics"> <PARAM name="Item1" value="Topic 2;Topic2.htm"> <PARAM name="Item2" value="Topic 3;Topic3.htm"> </OBJECT>
At run time, the preceding HTML appears as shown in Figure 14-12.
Figure 14-12. Related topics
To display related topics as a hyperlink instead of as a button control, specify a Text parameter rather than a Button parameter in the object element. For example, the following HTML displays the preceding Related Topics as a hyperlink:
<OBJECT id= hhctrl type="application/x-oleobject" class codebase="hhctrl.ocx#Version=4,74,9273,0" width=100 height=100> <PARAM name="Command" value="Related Topics, MENU"> <PARAM name="Text" value="Text:Related Topics"> <PARAM name="Item1" value="Topic 2;Topic2.htm"> <PARAM name="Item2" value="Topic 3;Topic3.htm"> </OBJECT>
Creating Associative Links
Associative links reference keywords rather than specific file names. For this reason, they are useful for cross-referencing between HTML Help files you don t have to know how the topics within a compiled file are named, you just need to know which keywords were used. Associative links are useful within a single Help file as well file names can change during development, and it s easier to maintain a keyword list than it is to update file names within cross-references.
There are two parts to an associative cross-reference:
The keywords entered in the target topic files provide the destinations that cross-references link to.
The link entered in the referencing topic file provides the source from which the cross- reference links.
To create associative link keywords, insert an object element in the target topic. For example, the following object element creates the associative link keyword Link1 :
<Object type="application/x-oleobject" class> <param name="ALink Name" value="Link1"> </OBJECT>
Associative links are very similar to keywords used in indexing HTML Help. However, they do not appear in the index. The reason for this is to allow cross-referencing and indexing to be maintained separately.
To create a link to topics with a specific keyword, insert an HTML Help control ActiveX object in the topic file making the cross-reference. For example, the following object element displays a list of cross-references in a pop-up menu when the user clicks the control:
<OBJECT id=hhctrl type="application/x-oleobject" class codebase="hhctrl.ocx#Version=4,74,9273,0" width=100 height=100> <PARAM name="Command" value="ALink, menu"> <PARAM name="Button" value="Text:See Also"> <PARAM name="Flags" value=",,1"> <PARAM name="Item1" value=""> <PARAM name="Item2" value="Link1"> </OBJECT>
At run time, the preceding HTML displays a list of topic titles that contain the associative link keyword Link1 , as shown in Figure 14-13.
Figure 14-13. Associative links
To display associative links as a hyperlink rather than as a button control, omit the Button parameter from the object element, and call the object s Click event from the hyperlink. For example, the following HTML displays the links when the user clicks the See Also hyperlink:
<OBJECT id=hhctrl type="application/x-oleobject" class codebase="hhctrl.ocx#Version=4,74,9273,0" width=100 height=100> <PARAM name="Command" value="ALink, menu"> <PARAM name="Flags" value=",,1"> <PARAM name="Item1" value=""> <PARAM name="Item2" value="Link1"> </OBJECT> <a href="#" onclick="hhctrl.Click()">See also</a>
Enabling Searches
To enable full-text searches within a Help file, select Compile Full-Text Search Information from the Compiler tab of the Project Options dialog box.
When full-text searching is enabled, the HTML Help Workshop builds a concordance table of all the words in your topic files and includes that table in the compiled Help file. Because this table references all words in the topic files, it can become quite large. To help control the size of this table, you can omit words that are not useful for searching. For example, you might want to omit articles, conjunctions, personal pronouns, and numbers from full-text searching.
To omit words from full-text searching, follow these steps:
Create a text file listing the words to omit.
On the Project tab in HTML Help Workshop, click Change Project Options.
On the Files tab of the Options dialog box, type the file name of the list of words to omit in the Full Text Search Stop List File box.
When a user tries to search on a word that you include in the stop list, HTML Help displays a message box stating that the phrase can t be searched on.
Compiling and Previewing Help
To compile an HTML Help project, choose one of the following methods:
On the Project tab of the HTML Help Workshop, click Save All Files And Compile.
Use the HTML Help Compiler (hhc.exe) from the command line. For example, the following command line compiles the HelpSample.hhp Help project:
hhc.exe HelpSample.hhp
To preview a compiled HTML Help project, choose one of the following methods:
Click the View Compiled File toolbar button, and then select the file name of the compiled file.
Double-click the compiled Help file (.chm) in Windows.
IMPORTANT
You can t recompile a Help file while the compiled Help file is open for viewing. You must close the compiled Help file before recompiling.
![MCAD(s)MCSD Self-Paced Training Kit(c) Developing Web Applications With Microsoft Visual Basic. Net and Microsoft V[. .. ]0-315](/icons/blank_book.jpg "MCAD(s)MCSD Self-Paced Training Kit(c) Developing Web Applications With Microsoft Visual Basic. Net and Microsoft V[. .. ]0-315"){kind=icon}
EAN: N/A
Pages: 118