HTML Help Manager
This CTS will be improved in future but is very useful in its present form for those who need to maintain huge documentations for many different products, components and so on.

Why/Who need it (history)? 

If you ever created documentations with the Microsoft's HTML Help compiler you probably already liked it, but also you probably already felt there is something missing in it or probably around it. The MS HTML Help Workshop has a nice GUI and allows you to create Contents and Index for your HTML pages, but this is a manual work - a lot of work (especially for the keyword index). The situation becomes more complicated if you have common components used in some of your products - you need to add their documentation to the product's documentation too. And then a new contents tree must be created and a lot of work to be performed manually. Depending on the size of the documentation this could take a few days. As you can see we have this problem thus we created something to help us. 

How it works?

If you have all of your help pages in a single directory tree, including the documentation of all the products and components in corresponding subdirectories this helps to create cross-links between different products and components. When you need to build a documentation for a certain product you will probably want to be able to "scrap" part of this directory tree and generate Contents and Index for the files the scrap will contain. Thus one logical decision comes in - why not put the content-tree position knowledge in the HTML files? E.g. each file knows its position in the virtual help tree covering all your products and components (think of it as for something similar to MSDN). Then generating the help contents tree over the information contained in the HTML files will be much easier and will reflect any changes (new files added for example). To create a "scrap" of the tree (for a single product) you will need just to include in this contents tree generation process the files related directly or indirectly to the product. And they will appear in the correct positions in the help contents. This is exactly what this script does. It also collects the keywords specified for the HTML file in its META name="Keywords" tag and creates Index file as well.

Tags reference:

<META NAME="Keywords" CONTENT="....comma delimited keywords list">

Script adds each keyword found here in the index file and adds a link to the page that contains it. If the page contains more than one tag of this type all the tags will be processed one by one.

<META NAME="SiteMap" CONTENT="tree_path">

Specifies the file position in the help contents tree. The tag may appear more than once - this will put the file in several places in the contents tree - sometimes this is a required feature (for example feature common for several objects).

The tree_path syntax: 

/Tree node name/SubTree node name/../

The parts are the display names of the topics as they appear in the help contents tree. The file will be linked in the topic specified.

If you want to link the file to the folder in the contents tree (not as a document under it) place a "." after the last "/" - like this:

/Product start/Reference/.

Thus the Reference will appear as folder - clicking it user will open the sub-branch and also the document containing this path will open automatically. This is good for overview pages for example.

<CUSTOMFILED ID="CopyRight"> or  <CUSTOM ID="CopyRight">...</CUSTOM>

Will be replaced with the value of the CopyRightText global compiler variable in the project (if not defined it equals to empty string). This is useful to mark the pages with correct years and probably correct company name if it changes or if a particular product has been developed with partners.

<CUSTOMFILED ID="PageTitle"> or  <CUSTOM ID="PageTitle">...</CUSTOM>

Will be replaced with the page title - e.g. the text in the <TITLE>...</TITLE> tag. Why need this? You may need to place the heads of your HTML pages in include file (they could be different for the different products but however usually the pages belonging to one part of the help file share common header). Typically the page caption must appear in this header that is included and there is no other way to set different caption in each page. Thus these tags will usually appear in such include files to allow the page title to be copied into the page.

What is generated?

The files are processed and replacements are done. Usually you will choose SSItoHTML processing option for them (except for the images and some other non-HTML resources). After finishing the files processing the script will generate the following files in the project's output directory:

HHProject.hhp - A simple project file for MS HTML Help compiler and Workshop. It contains only minimal settings - edit it to adjust buttons, windows etc. To change the name of the generated file set the ProjectFileName global compiler variable (in the project settings) to the desired file name.

Table of Contents.hhc -  The HTML Help's contents tree. To change the output file name set the ContentsFileName global compiler variable to the desired name.

Index.hhk - Keyword index file. To change the output file name set the IndexFileName global compiler variable to the desired name.

After all you can open the .hhp file in the HTML Help workshop, adjust additional settings and compile.

Remarks

This script assumes you keep all the documentation in a single directory tree. To create documentation for each product you will need to create ASPC project for each product and include in it only the files related to the product. Thus you have ability to package the product's documentation by just including the related files in the project and setting the CTS for them (suggestion: specify this script as default CTS for the project in the project settings dialog and apply it to all the files that use SSItoHTML processing). What you will need to do manually in the Help workshop will be setting start page, some visual details and other miscellaneous options.

What will be added with the final version of the ASP Compiler 1.1? This script will also generate index and contents pages for exposing on the WEB server - e.g. if you want to expose the documentation online.

The script could be useful for other site management tasks similar to the documentation creation process. Even a normal static WEB site could benefit of it - could be packed in HTML help file for example.