Using WinHelp 4.0 In Win32s

This FAQ file is intended to put in one place the information I have gathered on using WinHelp 4.0 under Windows 3.1 with Win32s. This file is accurate to the best of my knowledge, but I make no guarantees. I will try to keep it updated as I receive new information.

Terminology Used

Distributing Win32s

• Getting Win32s Files
• Installing Win32s
• Distribution Files for Win32s
• Easy Win32s Distribution

Setup and Behavior

• WinHelp 4.0 Calls From 16-bit Software
• Win32s and Context Sensitive Help
• WinHelp 4.0 Calls From 32-bit Software
• WinHelp 4.0 and 16-bit DLLs
• Getting WinHelp 4.0 by Double-clicking
• Known Bugs in WINHLP32.EXE running under Win32s

Compiler Compatibility

• Moving to WinHelp 4.0
• WinHelp 4.0 tools under Win32s
• Compiling Under Windows 95 for Win32s Use

Support

• How will WIN32HLP.EXE under Win32s be updated?
• How Will Bugs get fixed?

Send any questions, comments, corrections, or additions to .

If I don't know the answer, I will try to get one and then add it to this file.

Terminology Used

I have tried to distinguish between the WinHelp file versions and the engines.

• A WinHelp 3.1 file is a 16-bit file compiled with HC or HCP.
• A WinHelp 4.0 file is a 32-bit file compiled with HCW/HCRTF.
• WINHELP.EXE is the 16-bit WinHelp 3.1 engine.
• WINHLP32.EXE is the 32-bit WinHelp 4.0 engine.

Is everyone confused yet?

If you find where I misused terminology, please let me know.

Getting Win32s Files

All of the necessary files are on the current MSDN level 2 CDs.

Installing Win32s

Run SETUP from the <CD>:\WIN32SDK\MSTOOLS\WIN32S\DISKS\RETAIL\WIN32S\DISK1 directory. If you also want the latest versions of the OLE files, run SETUP from the <CD>:\WIN32SDK\MSTOOLS\WIN32S\DISKS\RETAIL\OLE32S\DISK1 directory (from Michael Malcolm Anderson)

Distribution Files for Win32s

The following is taken directly from \WIN32SDK\DOC\REDIST\REDIST.TXT on the MS Development Platform Premium Release titled "Windows 95 Final Rlease."

Win32s Version 1.30 Redistributable Code

The Win32s Redistributables are located in several directories of the Win32 SDK distribution CD-ROM. The Win32s files must be installed on Microsoft Windows 3.1 or Microsoft Windows for Workgroups in order to run Win32 applications. It is necessary to ship these components with, and be installed by, your application.

In addition to the rights granted in Section 1 of the Development License Agreement ("Agreement"), with respect to the Win32s Redistributable Code, you have the following non-exclusive, royalty free rights subject to the Distribution Requirements detailed in Section 1 of the Agreement:

• You must ship all of the following CORE Files from the \MSTOOLS\WIN32S\NODEBUG directory.
  comdlg32.dll compobj.dll crtdll.dll lz32.dll netapi32.dll
  ntmsg.dll olecli32.dll olesvr32.dll sck16thk.dll shell32.dll
  version.dll w32s.386 w32scomb.dll w32skrnl.dll w32sys.dll
  win32s.exe win32s16.dll winmm.dll winmm16.dll winspool.drv
  wsock32.dll ctype.nls l_intl.nls locale.nls sortkey.nls
  sorttbls.nls unicode.nls riched32.dll winhlp32.exe ftsrch.dll
  comctl32.dll l_trk.nls
• You must ship all of the following CORE Files from the \MSTOOLS\WIN32S\HELP directory.
  winhlp32.hlp windows.hlp winhlp32.cnt
• You must ship all of the appropriate files for your target locale from the \MSTOOLS\WIN32S\NLS directory. (E.G. in the US market - p_437.nls, p_850.nls, and p_1252.nls)
  p_037.nls EBCDIC
  p_10000.nls Macintosh Roman
  p_10001.nls Macintosh Japanese
  p_10006.nls Macintosh Greek I
  p_10007.nls Macintosh Cyrillic
  p_10029.nls Macintosh Latin 2
  p_10079.nls Macintosh Icelandic
  p_10081.nls Macintosh Turkish
  p_1026.nls EBCDIC
  p_1250.nls Windows 3.1 Eastern European (ANSI)
  p_1251.nls Windows 3.1 Cyrillic (ANSI)
  p_1252.nls Windows 3.1 US (ANSI)
  p_1253.nls Windows 3.1 Greek (ANSI)
  p_1254.nls Windows 3.1 Turkish (ANSI)
  p_437.nls MS-DOS United States (OEM)
  p_500.nls EBCDIC "500V1"
  p_737.nls Greek (formerly 437G) (OEM)
  p_850.nls MS-DOS Multilingual (Latin I) (OEM)
  p_852.nls MS-DOS Slavic (Latin II) (OEM)
  p_855.nls IBM Cyrillic (OEM)
  p_857.nls IBM Turkish (OEM)
  p_860.nls MS-DOS Portuguese (OEM)
  p_861.nls MS-DOS Icelandic (OEM)
  p_863.nls MS-DOS Canadian-French (OEM)
  p_865.nls MS-DOS Nordic (OEM)
  p_866.nls MS-DOS Russian (USSR) (OEM)
  p_869.nls IBM Modern Greek (OEM)
  p_875.nls EBCDIC
  p_932.nls Japan (ANSI/OEM)
  p_936.nls Chinese (PRC, Singapore) (ANSI/OEM)
  p_949.nls Korean (ANSI/OEM)
  p_950.nls Chinese (Taiwan, Hong Kong) (ANSI/OEM)
• If your application is an OLE application, you must ship all of the following CORE OLE files from the \MSTOOLS\WIN32S\NODEBUG directory.
  ole2.dll ole2.reg ole2conv.dll ole2disp.dll ole2nls.dll
  ole2prox.dll ole2thk.dll ole32.dll oleaut32.dll olecli.dll
  stdole.tlb stdole32.tlb storage.dll typelib.dll oledlg.dll
• You may modify and distribute the object code versions of the files in the directory identified as \MSTOOLS\WIN32S\SETUP and its subdirectories.
• You may distribute the following files to ensure that Win32s is properly installed:
  cards.dll freecell.exe freecell.hlp
• You may distribute the following files from the \MSTOOLS\WIN32S\NLS directory.
  w32s.dan w32s.deu w32s.esp w32s.fin w32s.fra
  w32s.ita w32s.nld w32s.nor w32s.sve w32sys.dan
  w32sys.deu w32sys.esp w32sys.fin w32sys.fra w32sys.ita
  w32sys.nld w32sys.nor w32sys.sve

Easy Win32s distribution

Copy the disk images in the <CD>:\WIN32SDK\MSTOOLS\WIN32S\DISKS\RETAIL\WIN32S\DISK1 and . . .\DISK2 directories and call SETUP.EXE on disk 1 from your setup routine to do the Win32s setup for you.

If your application is an OLE application copy the disk images in the <CD>:\WIN32SDK\MSTOOLS\WIN32S\DISKS\RETAIL\OLE32S\DISK1, . . .\DISK2, and . . .DISK3 directories and call SETUP.EXE on disk 1 from your setup routine to do the Win32s setup for you.

Can I open a WinHelp 4.0 file from 16-bit software under Win32s?

Only if you use the Shell command to start WINHLP32.EXE and pass the file name as a parameter.

Since you cannot have context sensitive help this way, it's probably better to call the WinHelp API which will automatically call WINHELP.EXE from 16-bit software. If you want WinHelp 4.0 functionality you will need to get any extensions (collapsible contents windows, print-all routines, etc.) as 16-bit DLLs or apps.

Author's note: You can get context sensitive help from a WinHelp 4.0 file under Win32s if you are calling it from 32-bit software.

Can I get context sensitive help in Win32s if I use WinHelp 4.0?

Yes, if you use one of the following combinations:

• 16-bit software calling WinHelp 3.1 file (16-bit DLLs allowed in the help file)
• 32-bit software calling WinHelp 3.1 file (no 16-bit DLLs in the help file)
• 32-bit software calling WinHelp 4.0 file (no 16-bit DLLs in the help file)

In general it's safer not to mix 16-bit and 32-bit components. Use WinHelp 3.1 files if your application is 16-bit and WinHelp 4.0 files with only 32-bit DLLs if your application is 32-bit. If you are using WinHelp 4.0 files in Win32s and want the user to be able to double-click on the file to open them, you should name them with an extension other than .HLP (I'm using .H32) and associate this extension with WINHLP32.EXE (see below).

Author's note: I have tried to trick the system by declaring the 32-bit API call (WinHelpA) in a 16-bit application (Yes, I remembered to copy the appropriate Windows 95 DLL to my Windows/System directory). This doesn't work either, so don't waste your time trying.

How do I get 32-bit software to call WINHLP32.EXE under Win32s?

Don't do anything. Once Win32s is installed, 16-bit software calls to the WinHelp API will call WINHELP.EXE while 32-bit software calls to the WinHelp API will call WINHLP32.EXE.

Can I call WINHLP32.EXE if my help file uses 16-bit DLLs under Win32s?

No. You will get an error message telling you that the help file uses a 16-bit DLL and that WINHELP.EXE (the WinHelp 3.1 engine) will be used to open the file. Although 32-bit software with 16-bit DLLs will work correctly under Windows 95, it will not work correctly under Win32s.

How can I make sure that WINHLP32.EXE is called when I double-click on my help file.

There are at least two ways to do this:

1. Name your help file with a ".H32" extension (or any other extension that is not already spoken for). Once you have Win32s on your system, add "h32=winhlp32.exe ^.h32" in the [Extensions] section of the WIN.INI file.
   The setup routine programmer must associate WINHLP32.EXE with the .H32 extension during setup (in Win32s, Windows 95, or both, depending on the system). The application developers need to make sure that the name of the application help file is changed. In Visual C++ with Microsoft Foundation Classes, this can be done by adding "m_pszHelpFilePath = helpPathFileName;" to the InitInstance member function of the App class created for the app. This changes the help file name from the default AppName + .HLP to helpPathFileName. When creating helpPathFileName you must make sure that all backslashes are double backslashes.
   If you use this method, your help file does not have a .HLP extension, and therefore may not be recognized by someone trying to double-click the file name to get help. However, 16-bit and 32-bit help files are handled separately and intelligently by the system. In Windows 95, you can set the file association so that the new file extension shows the help "book" as its icon, just like a standard .HLP file.
   Note: You can use a .HLP extension in Windows 95 and a .H32 extension in Win32s if you want. This requires a little more programming (emphasis on little), since both the app and the installation routine need to know which environment they are in. It also causes the least possible disruption, since everything is as expected in Windows 95, and in Win32s the only difference from normal for users appears if they go hunting to open the help file by double-clicking.
2. Once you have Win32s on your system, change the ".HLP" entry in the [Extensions] section of your WIN.INI file from "hlp=winhelp.exe ^.hlp" to "hlp=winhlp32.exe ^.hlp." This changes the WinHelp engine used if you "execute" a help file directly (e.g., by double-clicking in file manager) or if it is called from a 32-bit application.
   Double-clicking a .HLP file does the following:

• WinHelp 4.0 files using only 32-bit DLLs are opened by WINHLP32.EXE.
• WinHelp 3.1 and WinHelp 4.0 files with 16-bit DLLs are shunted to WINHELP.EXE after an error message the the user must dismiss.
• WinHelp 3.1 files without 16-bit DLLs are opened by WINHLP32.EXE.
• WinHelp 3.1 and WinHelp 4.0 files opened by WINHLP32.EXE that have an associated .CNT file will open to the Help Topics dialog. Those without a .CNT file will open to the contents topic as defined in the HPJ file.
  Unfortunately, when you call the WinHelp API from a 16-bit app, it always calls WINHELP.EXE. If the help file has an associated .CNT file, the Help Topics dialog box will appear when you double-click to open it, but will not be available when you call it from within the app. In other words this can cause problems with other software on the system, so I don't think it's a very good idea. Although this method is shown here because it has been previously documented, I don't recommend it.

What are the known bugs in the current version of WinHelp 4.0 running under Win32s?

• With the help authoring switched on with winhlp32, if you use PopupContext with an invalid context number, the error message displayed is "Cannot find the windows.hlp file. Do you want to find it?"
• With winhlp32, deleting an annotation in a popup causes an unhandled exception. This occurs on Windows NT 3.51 and Windows 95 as well.
• The winhlp32 Find tab does not paint correctly. The tab dialog box background is white, the button captions have a white background, and some lines are missing. All critical information is still on the tab, and the tab functions correctly.
• Winhlp32 does not have context sensitive help for itself.
• Winhlp32 cannot play .AVI files.
• Each time you open a help file, found words are not highlighted in the first topic you select using the Find tab. If you reopen the Find tab and select another topic (or even the same topic), the found words will be correctly highlighted.
• When a help file with a .CNT file is brought up from a write-protected floppy, there is a system error the first time that the help file is invoked. This does not happen if winhlp32 is invoked from the command line (winhlp32 a:file.hlp) or if the .GID is already created.
• When you open up a different help file, the window title changes to the title of the new help file. When you go back to the original help file, the window title does not change back to the original title.
• When bringing up a help file in File Manager with a .CNT file but no keywords, the Find tab is brought up.
• Winhlp32 requires some DLLs to be in the Windows/System directory. If the DLL is in the same directory as the help file, winhlp32 is confused. CTL3D32.DLL (and possibly others) will cause an error if it is in the help file directory, rather than (or in addition to) the Windows/System directory. The error message is "This application uses CTL3D32.DLL, which has not been correctly installed. CTL3D32.DLL must be installed in the Windows system directory." The solution is to move the DLL to the Windows/System directory (observed 1/21/96).

When should I move to WinHelp 4.0?

• If your help file must run on Windows 3.1x, Windows 3.1x with Win32s, and Windows 95, you must use the Windows 3.1 files, and are stuck with all of the restrictions of WinHelp 3.1.
• If the application calling the help file is 16-bit you should use WinHelp 3.1 files.
• If you are using 16-bit DLLs you should use WinHelp 3.1 files.
• If you know that Win32s will be on all systems using your help file, and your software is 32-bit, you can use WinHelp 4.0 files.
• If you are willing to distribute (2) floppy disks worth of Win32s files with your 32-bit software you can use WinHelp 4.0 files.
• If your software can only run on 32-bit systems, you should use WinHelp 4.0. Any 32-bit Visual basic program qualifies here, since VB4-32 cannot run on Win32s.

Can I use the new WinHelp 4.0 tools under Win32s?

Version 4.00 of hcw.exe and hcrtf.exe should run OK on Win32s, but because it has not had a test pass, it is not officially supported. Version 4.01 of hcrtf.exe (available this fall) will not run on Win32s if you allow the grinder window to come up. Version 4.02 of hcw.exe (early next year) will not run at all on Win32s. (from Faith Sohl, Microsoft)

Note from author: I have not been able to get any version of hcw.exe or hcrtf.exe to work on my system under Win32s. Other people have reported success in using the 4.00 version of these files. However, if you have Windows 95, you can do all editing and compiling under Windows 95 and only test under Win32s (see below).

Can I compile with versions of hcw.exe and hcrtf.exe later than 4.00 and still have a help file that runs on Win32s?

There is no code in hcw/hcrtf for recognizing that it is running on Win32s. It always creates a version 4.0 help file, which requires WINHLP32.EXE to display. WINHLP32.EXE is available on NT 3.51, Windows 95, and Win32s 1.3. It makes no difference whether the help file was compiled on any of these platforms. (from Faith Sohl, Microsoft)

Author's note: The WINHLP32.EXE shipped with Windows 95 is different from the WINHELP.EXE shipped with Win32s. make sure you keep track of which platform your WINHELP.EXE belongs to.

How will WIN32HLP.EXE under Win32s be updated?

Microsoft has no current plans to ever revise the Win32s version of WinHelp. (from Faith Sohl, Microsoft)

How Will Bugs get fixed?

The only bugs in the Win32s version of WINHLP32.EXE that Microsoft will consider fixing are ones that are reproducible on NT or Windows 95. If you find bugs not listed that meet the criteria, send them on to Microsoft. (from Faith Sohl, Microsoft)