MS Win32 Programmer's Reference in CHM Format

[Mike Lobanovsky]

Those who are interested in MS Windows SDK-style programming (modern BASIC and non-BASIC alike) may find this manual very handy in their everyday work. It's a no-nonsense .CHM recompilation of the old-style .HLP file still available at MASM32, PowerBASIC and FreeBASIC sites.

The manual was part of MS SDK documentation back in the Win'98/NT era but since MS is doing everything to preserve backward compatibility of their system API, about 99% of its contents is still applicable today. In fact, it is a miniature offline replica of MSDN right on your desktop 24/7 regardless of the availability/quality of your Internet connection:



Contrary to earlier recompilation attempts including my own, the new CHM file features non-scrolling headers and true popup windows and preserves the look-and-feel of the original to its fullest. And, what's most important of all, it is fully context sensitive, i.e. responsive to ShellExecute('Win32.chm::/FunctionName.htm') calls of your preferred compiler help system (if available).

Credits go to Laurence Jackson, a PowerBASIC long-timer, and the file can be downloaded directly from his site.

The DL offers an ~11MB large unarchived .CHM file, so you will probably have to unblock it explicitly once dowloaded for your system's Defender to allow you to use it.


(Jochen, will you please inform the MASM32 community of this new download? I'm sure Laurence was too shy to advertise his work anywhere outside the PB circles. I have his written assurances that he's got nothing against anyone using his manual in any environments other than PowerBASIC.

Perhaps anybody else could notify the FreeBASIC community of the same? I'm not a member of their forum though I do lurk over there from time to time.

TIA)

[jj2007]

Jochen, will you please inform the MASM32 community of this new download?

Done!

[ScriptBasic]

Mike,

It seems to work under Linux with xCHM.

[Mike Lobanovsky]

That's great John!

It does seem to somewhat disrespect the stylesheets though. Does it show a popup window when the Quick Info button is clicked?


With Laurence's kind permission I have recompiled the CHM again to add some styles that are consistent with FBSL's regular documentation, and the file is now part of the distro:





The resultant file size (10,694,622 bytes) turned out to be some 711,5KB smaller than Laurence's compilation with all the functionality seemingly preserved. I used pure HTML Help Workshop's HHP project file (it can be DL'ed from his site as well) and his HTM files rather than his non-free Help & Manual XML project, and cooked up a quick and dirty FBSL script to automatically inject the new visual style classes, button GIFs and JS popup script references directly into the HTM files.

[Mike Lobanovsky]

Such a great reduction in the overall file size was due to unfortunate omissions of certain entries in my recompilation. My script messed up a few HTM files rendering them unreadable from within the CHM. Will have to redo the job before letting it go public...

[jj2007]

Such a great reduction in the overall file size

On a side note: Inside LJ's version you'll find a file called win32api_popup_html.js - a genuinely crappy mass of styles, example:

Code: [Select]

<p style=\"margin: 0px 0px 0px 0px;\">Win95<\/p>\n\r<\/td>\n\r<td valign=\"top\" width=\"61%\" style=\"width:61%;\">
11 MB, by far the biggest file (the next one is $FIftiMain at 3 MB). However, with 7-zip it compresses to 200k, a ratio of 55:1, so it's probably not worth the effort to try a reduction.

[ScriptBasic]

Does it show a popup window when the Quick Info button is clicked?

Nope. 

I remember chmsee doing a good job with .chm help files under Linux supporting pop-ups and such. It's no longer being supported and the last release was in 2013.

[Mike Lobanovsky]

Jochen,

... with 7-zip it compresses to 200k ...

I really don't know what you're talking about. 7-zip's ultra-LZMA compresses it to an approx. 10,9MB archive, which means by some 200KB smaller than MS HH Workshop's native ZIP compression. Given that ultra-LZMA is applied against the already compressed data rather than the initial textual HTMs, I'd estimate that ultra-LZMA instead of ZIP could've yielded some 20 to 25% deeper compression (as it usually does), i.e. a 7.5 to 8MB large output CHM. Unfortunately this would render such a CHM unreadable by standard system Help services...

Inside LJ's version you'll find a file called win32api_popup_html.js - a genuinely crappy mass of styles, example:

Code: [Select]

<p style=\"margin: 0px 0px 0px 0px;\">Win95<\/p>\n\r<\/td>\n\r<td valign=\"top\" width=\"61%\" style=\"width:61%;\">

This isn't crap, Jochen. That's in fact the ultimate achievement of this recompilation: genuine HTML popups in the originally converted HLP file. No other HH software I'm aware of, free or non-free, can do such things in a HLP-to-CHM conversion process automatically.

The only questionable parameter in this proprietary (!) JS script's per-popup list of project files is the width=\"61%\" tag that makes the popups help-screen-size-dependent. In fact, all the popup entries are of the exact same size, so the popup width should also be made fixed for the popup window not to obscure the rest of view with its own blank spaces.

[Mike Lobanovsky]

Nope. 

It probably won't be such a great loss under Wine anyway. The popups are meant to show exactly what system library hosts the particular API and which MS VC include file contains the appropriate declaration.

The file is great even without the popup functionality. A must-have for an SDK style Windows programmer.

[ScriptBasic]

It probably won't be such a great loss under Wine anyway.

xCHM is not running under Wine. It's a 64 bit Linux Gtk based effort.

[Mike Lobanovsky]

xCHM is not running under Wine. It's a 64 bit Linux Gtk based effort.

Probably I didn't make myself clear enough. I meant to say the real wealth of that information is useless under Linux unless you're coding something for Wine. Things that are meant to run under Wine should be coded under genuine Windows where those popups will be visible, and visual style sheets, respected.

Cross-compilation for Windows and Mac OS X under Linux is IMHO a stillborn idea; Linux is, uhm, too extreme an environment for any GUI programming, let alone programming for other, mature graphics OSes.

[jj2007]

I really don't know what you're talking about.

Simple: out of curiosity, I found a 11MB file that compresses to 200k, 55:1. Which means that the same text is being repeated 200k times. Bad design IMHO (what about style sheets?), but in any case this is criticising the big software vendor who designed chm, not you, Mike. You take everything personally - a bad reflex, my friend ;-)

[Mike Lobanovsky]

Simple: out of curiosity, I found a 11MB file that compresses to 200k, 55:1.

I'm curious if that was the Holy Bible, Jochen? What about Alcoran or Torah for a change?

Bad design IMHO (what about style sheets?), but in any case this is criticising the big software vendor who designed chm, not you

From my standpoint, every little thing that's based upon interpreted markup languages is bad by definition. Aside from being able to compress deeply and thus to transfer efficiently over cable and air, interpreted plain text is horrible to work with. Those innumerous tags are aesthetically and practically much, much worse than the C language's dreaded curly braces, and the sheer amount of them is the cause of ever-increasing enthropy that every such file potentially brings along to the system. Take any Linux GUI: it may look nice -- at a first glance and in some rare cases -- but it is entirely impractical and ungreatful to work with design-wise and it is the direct cause of most crashes many more or less advanced GUI programs, let alone the entire frameworks such as GTK & Co. themselves, experience on that platform.

Laurence's H&M project is triply vulnerable in this regard. First off, the sources are designed in XML. Then they are translated together with their XSL style sheets to HTML files. And finally these are in their turn utilized by JS scripts that include yet more markup for the HTM topics to display as intended. How stable such a system can be, do you think?

"The big software vendor" once took a questionable decision to try their hand at the newly emerging markup language market and (quite expectedly) failed. But the mere sense of responsibility before the nearly two-billion strong user base regarding the backward compatibility of their system is what really keeps the CHM concept still going today.

I should also mention that 10..12MB large CHM files like Win32.chm (~100MB of raw data) are probably a physical maximum to what the 12 y.o. stock HHC compiler is able to handle. It was a nightmare experiencing regular system memory crashes in the HTML Help Workshop environment (under any Windows OS I had) with every three new entries to the file's TOC back in 2014, and it is what I'm seeing again working on this recompilation now. Oh my...

You take everything personally - a bad reflex, my friend ;-)

I'm just trying to take everything I'm working with s.e.r.i.o.u.s.l.y. Is that really such a bad reflex, do you think?

[jj2007]

I'm curious if that was the Holy Bible, Jochen?

No, Mike, it was win32api_popup_html.js, see reply #5

[Mike Lobanovsky]

No, Mike, it was win32api_popup_html.js, see reply #5

Aha! (looks like I'm a bit slow on some things, ain't I? )

Then this:

... with 7-zip it compresses to 200k, a ratio of 55:1 ...

probably meant using 7-zip in its ZIP, not ultra-LZMA, compression mode. Well-tuned 7-zip compresses this file to under 80KB using ultra-LZMA (.7z archive extension), i.e. ensures a 140:1 compression ratio with practically equal compression/decompression time. Unfortunately as I noted this won't work for the standard HH system.