HTML Help Utilities

Introduction | Main Menu | 
File Contents page | Test HH API page | Code Wizard page | Check Links page
How To Compare two Help Files

This window is available from the Authoring menu (main window). Alternatively right-click a Chm of HxS file in Windows Explorer and select "Examine with FAR". Select "Examine with FAR (Compare)" to open a second help file which is compared with the first.

Introduction

This window allows you to

  1. Examine the files inside a HxS, HxI, Chm, Chw, ITS or Hh.dat ITS structured storage file.
  2. Compare 2 help files. Also compare files inside a CHM.
  3. Extract files from a help file. Delete files from a help file.
  4. Perform API tests on a help file.
  5. Link-check a Chm file.
  6. The Code Wizard page tab gives you access to MS HH 1.x Workshop's "HTML Help ActiveX control" code wizard dialog.
About ITS Help files

You can think a Chm or HxS help file as being a container for folders and files, much like a zip or archive file.  FAR allows you to Open a help file and list its files and folders. Inside you will find your help contents, as well as several extra files which store information such as Help window configuration, Keyword and Full-text search information. These binary files have paths all starting with either a "#" or "$" character. If you remove any of these special files, the Help file may no longer function. 

  Main Menu  

File menu

Open Open an HTML Help file.
Open and Compare Opens a second HTML Help file and compares with the first.
Reload File(s) Refreshes the memory image of the help files read from disk. If comparing 2 CHM files it will reload both. You must Reload whenever you change any comparison options (see Reload below).
Launch View the HxS or CHM help file in the Help Viewer.
Close Close the current help file.
Compress Compress the current ITS file.
Help Files Explorer Open ITS File Explorer.
Auto Open Last When checked this window will load the last help file automatically when it opens.
Exit Exit this window.
Edit menu
Delete Selected Delete select item(s).
Copy Copy selected item(s) to the Windows clipboard.
Paste Paste the contents of the Windows clipboard.
Select All Select all items.
Decompile
 
Extract Selected
Extract All
 
Help
Open this help
File Contents page  

Select File > Open to open a Chm or HxS file. The files inside the help file will be listed on the File Contents page. You will see all your help project files (HTML and image files) as well as a number of binary data files compiled into the help file by the MS Help compiler. These special binary files, displayed in light gray text, contain HTML Help specific information such as, Map and Alias info, Search info, Window definitions, etc. 

Right click popup menu:

Open in Help File Explorer
Select this item to view the selected file in the FAR Help File Explorer. Alternatively double-click the file item. 
See also: Help File Explorer Dialog
Open in HH window (HH 1.x Files only)
Opens the selected file in the default HH window of the CHM.
Open in IE window (HH 1.x Files only)
Opens the selected file in Internet Explorer.
Extract Selected
Allows you to extract files from the Chm or HxS. First highlight the files you want extracted by Ctrl+Clicking or Shift+Clicking the files. This command is also available from the Decompile menu.
Extract All
Allows you to extract all files from the Chm or HxS. Note: The special HTML Help binary files are not extracted. This command is also available from the Decompile menu.
Display File Differences
This command is available if you are in Help file compare mode (see below). It allows you to display differences between actual files in the Help file. To do this you must specify an external File Difference Viewer in the Preferences dialog. Either select a file that exists in both Help files, or select 2 separate files to compare.
Note: Most Programs cannot read files inside a CHM, so FAR extracts the two files to a temp folder so that the external viewer can access them correctly.
Delete Selected
Allows you to deleted files from the Chm or HxS. Remember if you make a mistake you can always recompile a new help file (if you have the original project files). This command has a number of uses:
1. Remove files accidentally added to the Chm.
2. Remove the special binary data files.

The second option is how you make ITS files. ITS files are container files where the contents can be viewed only in Internet Explorer, never in a HH window. To make an ITS file, delete the HH 1.x data files then rename the Chm file to a .ITS file extension.

Note: Deleting HTML Help binary data files will stop the Chm files opening correctly as a HH window.
Copy
Select one or more files then press Ctrl+C to copy the file list to the Windows clipboard. Once in the clipboard you can paste the list of files into any editor or Windows control with paste capability.
Select All
Selects all the files in the file list. 
How To Compare two Help Files

This is useful for checking the differences between two Help files. A filter drop down list allows you to view files that are unique to one Help file etc.

To open two Chm files:

  1. Open the first Chm using the File > Open dialog.
  2. Open the second Chm also by using the File > Open dialog, but make sure that the checkbox labeled  "Compare this Chm..." is checked (The checkbox is at the bottom of the File Open dialog).

    Note: In Version 4 software you can simply select "File > Open and Compare" to open the second help file.

Once the second Chm is opened, a new display panel becomes visible (see image below) and the file list displays files from both Chms. Files from the second Chm are marked with a light blue background. The text box right of the filter drop down displays how many differences were found (this is the total from both CHMs).

New for Version 4: Often when comparing HTML files we don't care about extra white space or line feeds etc. By checking the boxes provided and then pressing Reload Files button (same as File > Reload), you can make file comparisons more relaxed. EG. If 2 files only differ by a single CR character and "Ignore CR LF Chars" is checked, then these files will show as being identical with a "=" prefix.

  Test HH API page  
API Test

This is basically a copy of the API Test found in MS HTML Help Workshop 1.x. It tests the HH API commands HH_DISPLAY_TOPIC, HH_HELP_CONTEXT and HH_CLOSE_ALL. These commands are documented in the Workshop help and are used by programmers to open a specific topic in a specific window. This test page is disabled if you have a HxS (MS Help 2) file loaded.

API Command
Select the API command you want to test. Fields below will become disabled if they do not apply to the selected command.
Window Definition
When a Chm file is opened this dropdown is filled with the names of all Window definitions found in the Chm. Leave this field blank to open a topic in the default window.
Topic File
Specify the topic you want to display. Available only for the HH_DISPLAY_TOPIC command. When a Chm file is opened this dropdown is filled with all available files found in the the Chm. Select a file and hit Test.
Help Context ID
Specify the help context ID you want to test. Available only for the HH_HELP_CONTEXT command. During help development many authors create ID to Topic mappings using the [MAP] and [ALIAS] sections in the .HHP project file. Select a help context ID and hit test.
Test Button
Press the test button to execute the selected API command.

Note: The HTML Help API (hhctrl.ocx) is a DLL and as such becomes a part of the FAR application. Therefore if a problem occurs that crashes the DLL, FAR will also crash. 

Compress ITS File

This allows you to compress the dead space (if any) out of a Chm. Most Chms don't compress much. In fact some Chms may actually grow by a few KBytes. To compress the Chm file we simply use an Istorage API function copy to a tempary file, then rename the file to the original Chm file.  The resultant Chm has the same file content but none of the null padding.

So why compress? The real advantage is in reducing Chw files. A Chw file holds the combined Indexes of all merged (or Collection) Chms. They are created on the fly with out compression for speed. You can safely delete a Chw as HTML Help will recreated it next time you open the Chm. It makes sense to ship them, since a 10 MB file will reduce by around 80% down to 2 MB.  If you have no index in your merged CHMs then you not  see a CHW file.

Note: You can also compress MS Help 2 files but at this stage we know little of the effects that compression has on MS Help 2 files. The huge HxW combined Index files (c:\Documents and Settings\All Users\Application Data\Microsoft Help) can be compressed, but compressing will cause access time to decrease slightly.

Example: MSDN Install

Typically when you install the a HH 1.x based MSDN CDROM you get a massive 57 MB Chw file copied to your hard disk. You can reduce this file by 50MB using FAR compression. 

MSDNxxx.CHW (original) 57.7 MB
MSDNxxx.CHW (compressed) 5.6 MB

Similarly the new MS Help 2.x based MSDN CDROMs install uncompressed HxW files which also compress very well.

Warning: Compressing combined index files will cause a noticeably longer access time on slower PCs.

  Code Wizard page (HH 1.x only)

The Code Wizard page gives you access to HH 1.x Workshop's "HTML Help ActiveX control" code Wizard dialog. Use it to generate code to access features of the HHCtrl.OCX ActiveX control. Copy and paste the generated code into your HTML document. For help on using the HH Workshop dialog, and HTML Help ActiveX control, please see "HTML Help ActiveX control" in your HH Workshop online help.

The Code Wizard page will remember any code you insert into the editor control when you close the window.

Tip: If you place the editor cursor within an existing code block, or select an existing code block (that was previously generated), then when you open the wizard dialog, the selected settings will be used as a basis of creating a new block of code. This is a handy way to manipulate existing code blocks. E.G. Copy existing code into the editor, select it and open the Wizard. The Wizard will edit this code and generate a new code block. Copy and paste the new code over your old.

 

  Check Links page  (HH 1.x only)

This command checks all links found in a CHM file. Which type of files to check and how verbose the logging  is, is controlled by the settings on the Options dialog (This is displayed when you press The Start button - see help below). 

What is checked?

FAR will first validate any Context Map information found in the Chm. This checks that the URLs associated with each context ID actually exists. The HH compiler log would normally report this error but still builds the CHM anyway. Note: Mappings are declared via the [MAP] and [ALIAS] sections of your .hhp project file, and are completely optional. For more info see our web site -- http://www.HelpwareGroup.com/htmlhelp/how_to_context.htm

Next each file in the Chm file is opened and scanned. File types scanned are specified in the options dialog (displayed when Start is clicked).  A first pass is done to find character patterns of ".chm::". This finds us file paths like  "master.chm::/index.htm#bookmark" and so on and we validate each path found. A second pass is done on the file to search for the character patterns of "href=" and "src=". This finds all standard hyperlink paths of the form <a href="index.htm#bookmark"> and <img src="file.jpg"> these paths are validated also.

29-May-2013 -- We now check <img src="..."> type links. Previously we only checked <a href="..."> links.

This approach of using pattern matching can be a little slow, but produces very good results. Help systems you think are squeaky clean, can show up with many errors. For merged help systems you need to open and check each Chm separately. We recommend you check links towards the end of the project to save time. 

All links that can not be physically checked are flagged as warning. Warnings include links to (ftp:, mailto:) web files as well as dynamic links created using script.  If you have warnings enabled (Options page) then at least you can look through the result file and check these links by hand. 

Start Checking 
Start checking the current Chm for link errors.
Stop
Terminate checking for links.
View last report in HTML
At the end of checking, an HTML version of the log is created with hyper-links to the Chm files with errors. Use this button to view this HTML version of the log file. Each report goes to the same file in the windows Temp directory. Use the Save As button if you wish to keep a report.
Save As
Save the current HTML report file to another file name.
Link Checker Options Dialog  

This dialog appears when you click the Link checker Start button.

Link Checker Reporting Options

Show Warnings 
When this option is selected, all link warnings are logged by the link checker. Warnings are links that cannot be physically checked, such as mailto:, http:, ftp: and partial links embedded in script.
1-Dec-2005: http links can be verified now by checking the Check HTTP Web Links checkbox.
Check Bookmarks
When this option is selected, all links containing bookmarks (link#anchor) are checked. When this option is unchecked the link to the target file is still checked.
Check Inside Comments
When this option is selected, any links found inside an HTML comment will be checked. Comments look like this <!-- text -->. Remember authors often wrap <script> sections with comment tags so enable this if you want script scanned for links.
Show Debug (verbose)
When this option is selected, every bit of information is logged by the link checker. This includes all files opened for inspection, even those files where no link errors or warnings were found.
Check Web Links (Requires Internet Connection)
When this option is selected HTTP, HTTPS and FTP web links will be verified. An Internet connection is required.
If the web link checks take a long time to perform you can click the "Stop" button. This will stop Link Checker from waiting for a thread to timeout. This wont stop results from being display correctly.
Check Link Case
Added 29/05/2013.
Checks and reports if links have the same case as the target file.
eg <a img="ABC.gif"> will flag an error if the target file name has a different case than "ABC.gif" (eg "abc.gif")
This check is usually not required since Microsoft type links are not case sensitive.
Note: If your project has a file "abc.html" but added to the .HHP project file [FILES] list as "ABC.HTML" then the file will be added to the CHM as "ABC.HTML".

HTML Report

Source Directory
You will notice that when link checker reports an error, the HTML document version of the report provides a link to the CHM file in error, as well as a link to the actual source file. The only way we can provide a link to the source file is if you enter the path to the .HHP project file (used to create the CHM). This field is only remembered if File > Load Last CHM is checked. If this field is blank we assume the Src is below the folder containing the CHM file.

File Extensions to Check

This tells the Link Checker which file types in the current Chm file to check. Specify the files types by entering each file extension separated by a comma. Hit the reset button to get back to the shipped defaults.

Example: "HTM,HTML" would mean that only *.htm and *.html files found in the Chm file would be opened and checked for bad links.

    1-Dec-2005: .HHC and .HHK files are now also checked for links if included.

OK - Select OK to except any changes and continue on to perform the actual Link Checking.

Cancel - Select Cancel to discard any changes made and cancel the Link Check.

http://www.HelpwareGroup.com/