Rick Strahl's Weblog  

Wind, waves, code and everything in between...
.NET • C# • Markdown • WPF • All Things Web
Contact   •   Articles   •   Products   •   Support   •   Advertise
Sponsored by:
Markdown Monster - The Markdown Editor for Windows

Make your CHM Help Files show HTML5 and CSS3 content


:P
On this page:

The HTML Help 1.0 specification aka CHM files, is pretty old. In fact, it's practically ancient as it was introduced in 1997 when Internet Explorer 4 was introduced. Html Help 1.0 is basically a completely HTML based Help system that uses a Help Viewer that internally uses Internet Explorer to render the HTML Help content. Because of its use of the Internet Explorer shell for rendering there were many security issues in the past, which resulted in locking down of the Web Browser control in Windows and also the Help Engine which caused some unfortunate side effects.

Even so, CHM continues to be a popular help format because it is very easy to produce content for it, using plain HTML and because it works with many Windows application platforms out of the box. While there have been various attempts to replace CHM help files CHM files still seem to be a popular choice for many applications to display their help systems. The biggest alternative these days is no system based help at all, but links to online documentation.

For Windows apps though it's still very common to see CHM help files and there are still a ton of CHM help out there and lots of tools (including our own West Wind Html Help Builder) that produce output for CHM files as well as Web output.

Image is Everything and you ain't got it!

One problem with the CHM engine is that it's stuck with an ancient Internet Explorer version for rendering. For example if you have help content that uses HTML5 or CSS3 content you might have an HTML Help topic like the following shown here in a full Web Browser instance of Internet Explorer:

ChromePreview[4]

The page clearly uses some CSS3 features like rounded corners and box shadows that are rendered using plain CSS 3 features. Note that I used Internet Explorer on purpose here to demonstrate that IE9 on Windows 7 can properly render this content using some of the new features of CSS, but the same is true for all other recent versions of the major browsers (FireFox 3.1+, Safari 4.5+, WebKit 9+ etc.).

Unfortunately if you take this nice and simple CSS3 content and run it through the HTML Help compiler to produce a CHM file the resulting output on the same machine looks a bit less flashy:

ChmViewer

All the CSS3 styling is gone and although the page display and functionality still works, but all the extra styling features are gone. This even though I am running this on a Windows 7 machine that has IE9 that should be able to render these CSS features. Bummer.

Web Browser Control - perpetually stuck in IE 7 Mode

The problem is the Web Browser/Shell Components in Windows. This component is and has been part of Windows for as long as Internet Explorer has been around, but the Web Browser control hasn't kept up with the latest versions of IE. In a nutshell the control is stuck in IE7 rendering mode for engine compatibility reasons by default. However, there is at least one way to fix this explicitly using Registry keys on a per application basis.

The key point from that blog article is that you can override the IE rendering engine for a particular executable by setting one (or more) registry flags that tell the Windows Shell which version of the Internet Explorer rendering engine to load. An application that wishes to use a more recent version of Internet Explorer can then register itself during installation for the specific IE version desired and from then on the application will use that version of the Web Browser component. If the application is older than the specified version it falls back to the default version (IE 7 rendering).

Forcing CHM files to display with IE9 (or later) Rendering

Knowing that we can force the IE usage for a given process it's also possible to affect the CHM rendering by setting same keys on the executable that's hosting the CHM file. What that executable file is depends on the type of application as there are a number of ways that can launch the help engine.

  • hh.exe
    The standalone Windows CHM Help Viewer that launches when you launch a CHM from Windows Explorer. You can manually add hh.exe to the registry keys.
  • YourApplication.exe
    If you're using .NET or any tool that internally uses the hhControl ActiveX control to launch help content your application is your host. You should add your application's exe to the registry during application startup.
  • foxhhelp9.exe
    If you're building a FoxPro application that uses the built-in help features, foxhhelp9.exe is used to actually host the help controls. Make sure to add this executable to the registry.

What to set

You can configure the Internet Explorer version used for an application in the registry by specifying the executable file name and a value that specifies the IE version desired.

There are two different sets of keys for 32 bit and 64 bit applications.

32 bit only or 64 bit:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\MAIN\FeatureControl\FEATURE_BROWSER_EMULATION

Value Key: hh.exe

32 bit on 64 bit machine:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Internet Explorer\MAIN\FeatureControl\FEATURE_BROWSER_EMULATION

Value Key: hh.exe

Note that it's best to always set both values ideally when you install your application so it works regardless of which platform you run on.

The value specified is a DWORD value and the interesting values are decimal 9000 for IE9 rendering mode depending on !DOCTYPE settings or 9999 for IE 9 standards mode always. You can use the same logic for 8000 and 8888 for IE8 and the final value of 7000 for IE7 (one has to wonder what they're going todo for version 10 to perpetuate that pattern).

I think 9000 is the value you'd most likely want to use. 9000 means that IE9 will be used for rendering but unless the right doctypes are used (XHTML and HTML5 specifically) IE will still fall back into quirks mode as needed. This should allow existing pages to continue to use the fallback engine while new pages that have the proper HTML doctype set can take advantage of the newest features.

Here's an example of how I set the registry keys in my Tarma Installmate registry configuration:

InstallerRegKeys

Note that I set all three values both under the Software and Wow6432Node keys so that this works regardless of where these EXEs are launched from. Even though all apps are 32 bit apps, the 64 bit (the default one shown selected) key is often used.

So, now once I've set the registry key for hh.exe I can now launch my CHM help file from Explorer and see the following CSS3 IE9 rendered display:

ChmViewerCss3

Summary

It sucks that we have to go through all these hoops to get what should be natural behavior for an application to support the latest features available on a system. But it shouldn't be a surprise - the Windows Help team (if there even is such a thing) has not been known for forward looking technologies. It's a pretty big hassle that we have to resort to setting registry keys in order to get the Web Browser control and the internal CHM engine to render itself properly but at least it's possible to make it work after all.

Using this technique it's possible to ship an application with a help file and allow your CHM help to display with richer CSS markup and correct rendering using the stricter and more consistent XHTML or HTML5 doctypes. If you provide both Web help and in-application help (and why not if you're building from a single source) you now can side step the issue of your customers asking: Why does my help file look so much shittier than the online help… No more!


The Voices of Reason


 

Phil
February 16, 2012

# re: Make your CHM Help Files show HTML5 and CSS3 content

Hey Rick,

Interesting article. I used to work for Blue Sky Software / eHelp Corporation (their flagship product was RoboHelp, which is a Winhelp / HTMLHelp authoring environment).

It is kinda cool & reassuring that this format hasn't gone the way of the dodo yet (and still has some life in it). Reading your article brought be back in time.

Keep up the excellent work!

Phil

Eric Lawrence
February 23, 2012

# re: Make your CHM Help Files show HTML5 and CSS3 content

It's not an accident that the Web Browser control is locked to a particular rendering version; that helps ensure that installing a new browser doesn't mangle all of your existing help files. If you go mucking with the registry for an application you don't own (e.g. the help viewers) you're taking the risk of breaking the rendering of all *other* help files on the system.

Rick Strahl
February 23, 2012

# re: Make your CHM Help Files show HTML5 and CSS3 content

@Eric - yes, but if you use 9000 it'll still fall back to quirks mode if you don't use the newer HTML doctypes. I'd say there's a pretty small chance of that breaking existing HTML content.

Tony Bunce
March 05, 2012

# re: Make your CHM Help Files show HTML5 and CSS3 content

What about using the X-UA-Compatible Metatag? that way you don't have to edit the users registry.

<meta http-equiv="X-UA-Compatible" content="IE=9" >


http://stackoverflow.com/questions/4612255/regarding-ie9-webbrowser-control

Rick Strahl
March 05, 2012

# re: Make your CHM Help Files show HTML5 and CSS3 content

Tried it - didn't work for me. Problem is that the control is global and once it initializes in a certain mode it won't switch between them. The meta tag works only in combination with the registry flags as far as I can tell.

Jimm Chen
June 17, 2013

# re: Make your CHM Help Files show HTML5 and CSS3 content

Very helpful. I solved my problem at http://stackoverflow.com/q/17042914/151453 with your help.

Johannes
May 01, 2017

# re: Make your CHM Help Files show HTML5 and CSS3 content

Interestingly, Tony's suggestion worked just fine for me without any registry hacks.


Jonathan Wood
September 27, 2017

# re: Make your CHM Help Files show HTML5 and CSS3 content

The only reason people are still using CHM files is because Microsoft hasn't provided anything new that is supported by Windows. Even the MFC Wizards no longer have a checkbox to generate support for help. It seems Microsoft has decided that online help no longer matters. Yes, I realize I can use Web pages. But it's fairly complex to have fully context-sensitive help using Web pages. And context-sensitive help seems to be another thing Microsoft has decided is not really important, even for some of their own products.


Tristano
February 09, 2020

# re: Make your CHM Help Files show HTML5 and CSS3 content

Thanks Rick, an excellent article as always!

The solution of enabling IE9 emulation mode for the application to which the CHM file belongs is quite cool. The only downside is that if the end user opens the CHM Help file directly (instead of from the main app via H1) then it would launch in IE7 mode — which might end up looking quite ugly if the HTML contents and CSS were designed targetting IE9 mode.

Setting the registry to enable IE9 compatibility directly for HH.exe seems an interesting idea, but I too share Eric's concerns about this potentially breaking the intended styles of many CHM docs. You mentioned that this shouldn't be an issue since the HTML Help Viewer should safely fall-back to IE7 if the HTML contents don't target IE9 explicitly. Did you have a change to actually test tweaking the registry entry and see if and how it affected various CHM files?


West Wind  © Rick Strahl, West Wind Technologies, 2005 - 2024