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.
|