How to add samples in a CHM file like in MSDN

This a undocumented feature of the HTML Help ActiveX so use these informations at your own risk.

 Step

Action

1

Create a subdirectory called Samples in your documentation source directory.

2

Create a subdirectory for your example in the Samples directory. Let's call it Example1 for the explanation. Then put all the files required for this example in this directory.

3

Edit your project file with your favorite text editor. Notepad is enough. Let's call it Project1.hhp.

4

Add the following lines to the OPTIONS section

Sample list file=Project1.hhs
Sample staging path=Samples
 

5

Add a line for each file of your example to the FILES section of the project file. For example

Samples\Example1\main.cpp
Samples\Example1\Images\Blur.bmp
Samples\Example1\Images\Clear.bmp
 

6

Then add the following line add the end of the FILES section

Samples\Example1\Example1.sfl

This file doesn't exist yet but it will be generated for you by hhc.

7

Save your project file

8

Open a new blank text file and put the following lines in it

[Example1]
ID=Example1
DistributionMediaDestination=MyProject\Example1
DefaultClientCopyDestination=\MyProject\Example1
SourceLocation=Samples\Example1\

The path you put for DistributionMediaDestination will be created by hhc during compilation time. All your example files will be copied in it and I don't know why !!!!
The path for DefaultClientCopyDestination is the path proposed to the client for saving the files on its computer.

9

Save this new file as Project1.hhs in same directory as Project1.hhp

10

Create an html file for the example explanation and add the following code in it :

<P><OBJECT ID=sample1 TYPE="application/x-oleobject" CLASSID="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11">
        <PARAM NAME="Command" VALUE="Sample">
        <PARAM NAME="Item1" VALUE="Samples">
        <PARAM NAME="Item2" VALUE="Example1">
</OBJECT><A HREF="javascript:sample1.Click()">Click to open or copy the files for the Example1 sample.</A></P>

You can put almost every value you want in Item1 but Item2 must indicate the name of the example you used in the hhs file.

11

Add the name of this file to the end of the hhp file like this for example :

html\Sample.html
 

12

Save every file and then open HTML Help Workshop. Open you project then compile it. The compilation should fail saying that if failed compiling example1.sfl. This is normal as we didn't created it. But before ending the compilation, hhc created this file for us not in the sample directory but in another new directory called sfl in the Samples directory.
Simply copy the Example1.sfl file from this directory to Example1 directory
It is possible that if you change the line at step 6 to Samples\sfl\Example1.sfl the compilation will work but the CHM system might be unable to uncompress your files by the time you ask for it... Even if there is no message at compilation time !!!!

13

Relaunch the compilation. This time you shouldn't have any error

14

Enjoy !!!!!

If you have any question mail me at obones@meloo.com
I will answer your question about the error messages you might get but I won't be liable for any loss of data that might occur using this information.
Once again, this feature has not been documented by Microsoft so this method worked for me today, maybe it won't work for you tomorrow... 8-)

All information Copyright Olivier SANNIER 2001. Contact me for details.