Complete Port of Original Help Docs to Fully interactive HTML

[NazmusLabs]

The original documentations for winfile, as extracted from the Windows 98 operating system, has now been ported to an open, and fully functional web based help system, complete with hyper-link support and table of contents.

It's another effort in "freeing" the documentation, making it easy to read on any device. And now that this is done, contributors can now easily add information to reflect the current state of the application.

Furthermore, I'm hoping to have the webpage that is stored on the repository serve as a live, up-to-date, documentation for the application, that can be launched right from the help menu. And, and the same time, with subsequent releases of Winfile, a frozen version of these documents can be distributed with the binaries, allowing that particular release enjoy a fully offline copy of the help files, as they were at the time of the release. This can be especially useful in older computers without internet access.

I have not done extensive testing in all the different browsers, and, but it appears all desktop browsers are able to view the files perfectly fine. I have yet to test mobile browser compatibilities.

But that's where the community comes in. By having the help file out there and easily accessible, it can be improved quickly whereas, before, the documentation was trapped in proprietary file formats that were difficult to read.

Best

[ZanderBrown]

Wow that's a lot of work, have you looked at GH Pages and considered using Jekyll?

[peterooch]

@ZanderBrown Jekyll formatted pages would not work if it would be downloaded and used offline

[NazmusLabs]

@ZanderBrown yes, that's the idea. But only an admin can set that up.

@peterooch yes it does work. I had extensive experience with it. Got Pages allows you to use your own HTML and isn't limited to its own thing.

[ZanderBrown]

@peterooch Jekyll generates html, just a c compiler generates machine code

[peterooch]

I meant if you added raw "unjekylled" files to the zip then there would issues with the pages.
if in the end product with all the jekyll processing would be done, it should work ...
We all misunderstood each other 😀

[NazmusLabs]

And like I said, that is optional to get you easily started. You can just go old school and upload your own index.html and just use that. That way, you have control of the website.

[ZanderBrown]

You do with Jekyll as well just without repeating yourself for every header/footer as I'm sure your aware

[malxau]

I maybe be missing something here, but it seems to me like there are two things going on in parallel:

1. Pulling the documentation out of the Win98 CHM and adding it to the repo so it can be maintained (what this PR does.)
2. Suggesting that documentation being invoked by Winfile be flat, HTML files.

I'm not sure I follow the reasoning for the second point. A CHM is just a pile of HTML files compressed into a single archive, with some extra metadata to create additional tree navigation support (optional), and invoked in a runtime that supports things like searching either via an index or text. The source material is still just HTML and can be maintained by anyone familiar with HTML.

What are the drawbacks to using CHM as a packaging/distribution mechanism for these HTML sources?

[NazmusLabs]

@malxau great question; allow me to answer that and we may proceed from there!

1. CHM is a closed, proprietary, format, which, by nature, amplifies some of the problems as described below.

2. CHM formats are not easily opened in anything other than HTML Help app that ships with Windows, as it is a non-standard format. Although it uses HTML for the actual documents (which thankfully allows us to port it out very easily), the extra Metadata that are included are not, to my knowledge, written in an open standard, such as XML, as it's typically expected today. This makes CHM files harder to extract with the likes of 7-zip and read the Metadata with notepad++.

3. As a result, the help file is not typically readable on mobile devices or other operating, meaning that one can't easily carry a portable, offline, copy of the docs to read on another OS.

4. The compiled format of the help doc is hard to update. This repository doesn't include anything to easily update individual documents and Metadata and recompile a new CHM. If we were going to set up a full system for updating and compiling the docs, why not do it using something that is completely open, which is fitting for an OSS project such as this.

5. All the operating systems we want to target, even on the retro branch, have first party web browsers, when windows 3.1. However the same cannot be said for chm files, I don't think.

6. HTML Help application has been unofficially deprecated in Windows and, thus, is unoptimal in modern environments for many reasons, including the lack of high DPI support and outdated user interface guidelines. It is also more at risk of being dropped on future editions of Windows.

What About the CHM Benefits?

That being said, there are drawbacks to using only HTML since, as you pointed out, the HTML help viewer has built in search and indexing functions that would need to be manually implemented in HTML, potentially making it too complex for older operating systems in the retro branch.

Possible Alternatives to CHM

I'd like to know if anyone is aware of another, open source, implementation of a help viewer application that can view HTML files and add indexing and searching capabilities that can be distributed with the application as the default help viewer.

Your Thoughts

Thoughts on any of the points I mentioned?

[malxau]

Eh, you're asking for my thoughts but I don't think you'll like them...

1. It's true that CHM is a somewhat proprietary format and would need a Windows (or compatible) environment to execute, but the same could be said for winfile.exe itself.
2. The formats to generate a CHM are HTML and an .ini file. To see what it looks like, I have a project doing this at https://github.com/malxau/wincvt/tree/master/help ; see in particular the wincvt.* files at the bottom. It may not be exactly how things are done in 2018, but it's not super bad.
3. The CHM itself can't be read directly outside of Windows, but the source HTML sure can. Taking the above project, the docs are readable by anyone at http://www.malsmith.net/wincvt/docs/Intro.htm . This may not be ideal for offline access, but I'm not really aware of any other good format for distributing a tree of HTML pages in a single file for offline access other than CHM. I mean, it could be in a .zip archive, but that's not exactly mobile friendly either.
4. Updating a CHM requires https://www.microsoft.com/en-us/download/details.aspx?id=21138 . Not ideal (ie., not in VS), but not hard to get.
5. This one is the one I'm struggling with the most. It's true that CHM support is only built in to Win98/Win2k and above, and available for NT4/95 and above, so 3.1/NT 3.51 don't have any support. But note that NT3.51/4 and 3.1/95 don't ship with usable web browsers either, so getting any functional HTML help there requires the user to install something else. This really sounds like an argument for generating winhelp files, since it's the only thing these platforms handle out of the box, but obviously that's far more proprietary/badly tooled than CHM. Note that Putty had tools for generating HLP + CHM to support their large version matrix since some platforms didn't have winhelp and others didn't have HTML help; those may be of use here too.
6. On deprecation, I don't know what to think. AFAIK MS built a new documentation system around the time of Visual Studio .NET and refined it over the years, but didn't make it available for anyone else. HTML help is thus old and badly maintained but is also the "newest" help system available for Windows developers. I'm curious what will happen if it's ever dropped.

I'm also curious if there's a true open source HTML help based system that can run on 3.1/NT 3.51, preferably out of a single file. This seems a little optimistic to me, but if one exists, great...

[NazmusLabs]

@malxau I'm not sure why you said I won't like your thoughts? If I just cared about my own opinion, I wouldn't have asked for thoughts. My views are based on what, I observe around the world and what I learn from others. Hearing other points of views allows me to reconsider my own and evolve it.

Anyway, I agree with all of your point except the first one because the first point is factually incorrect. CHM is proprietary whereas winfile is free software. If CHM were free software, we could have updated it like we are doing with winfile and distributed for other operating systems. Sure, winfile currently runs on Windows only but because it's free software, it at least has the potential to be eventually ported, as the code is free. That's why CHM and winfile are nothing alike.

Anyway, your other points also describes the reason why I went with HTML. Building CHM is too much of a barrier for people to quickly update the documentation. It'd be better to have a system where anyone can quickly update a help page on the fly on any computer or OS and create a pull request.

Oh, and about web browsers: Internet explorer 5 is available for Windows 3.1 and NT 3.1. They are first party browsers. This is why I noted that first party browser support is available for these OSes.

P.S. There's got to be an open source help viewer somewhere built in the last decade. I guess I'll need to do some archeological investigations.

[NazmusLabs]

P.P.S. Thinking about it, if there's going to be another ancient Windows feature going open source, let it be HTML Help. It would be such a beautiful gift for all wij32Windows developers who have used this system in their apps over the years. Since Microsoft isn't doing anything with it, it's better to just let the community to improve and support it. Just letting it die will be such a shame.

Winfile and HTML Help viewer are examples of best good retro Windows software that can really benefit from being open source and offer real value to people today.

[ZanderBrown]

wine

winhelp hh

Both are a little rough around the edges but work

[thecatkitty]

@NazmusLabs, but wouldn't it need to have Trident open-sourced too? Because HH relies on IE rendering engine, it is not going to be fully open.

[ZanderBrown]

Neither have search implemented and hh is missing index but they work, from memory hh uses gecko

[NazmusLabs]

@thecatkitty no because HTML Help doesn't actually render the help pages and doesn't include the Tradient engine as its component. It simply calls Internet Explorer to render the HTML. So, you will notice that in Windows 10, it uses Internet Explorer 11 (easiest by spotting the fat scrollbar unique to IE10/11). Furthermore, in Windows 7, you will notice that of you update from IE8 to IE11, HTML Help Viewer's HTML page's Window 7 style scroll bar will get replaced by IE11 fat metro style scrollbar.

Same with the likes of in XP: upgrading from 6 to 8 have you new find in page features in the help viewer even though the help viewer was never updated.

So, no, trident isn't a part of it. It will call IE to do the hard work. Plus, if people want to port that to Linux, they can just have it use blink instead. 😉

@ZanderBrown thanks for the info!

[thecatkitty]

@NazmusLabs, I know, I know. :)

I'm just saying that it would make it an open source project "trapped" in a closed-source technology.

[malxau]

@NazmusLabs I really disagree with the characterization of winfile.chm and winfile.exe as different with respect to how closed they are. Both of them can have source code that is available, readable, and compiled by anyone. Once compiled, they both target a particular runtime environment. Neither are really designed to have their post-compiled form pulled apart, but in neither case is that required, because the source is there for all to see/modify/compile.

An argument could be made that winfile.exe is compilable with an open source compiler and winfile.chm is not, and while I could see that argument being made in many places, this project's primary development system is with a closed source compiler...

[NazmusLabs]

@malxau I was referring to free software as in the license. Winfile is a "free software" as defined by Richard Stallman. CHM is not a free software, and while it may be as easy to decompile and work with this, the Windows End User License Agreement prohibits reverse engineering or distributing its code which you can correct me if I am wrong. That's why, I believe, Winfile and CHM are nothing alike. The difference is more a philosophical/legal one rather than a technical one.

This is why I strongly believe that HTML Help viewer along with the CHM format should be made open source. That would change everything. :)

[malxau]

I think you're confusing source code and compiled code. RMS opinion, which isn't really binding here, is what's in the GPL.

winfile.exe is what the GPL would call "object code", and if it were licensed under the GPL, the GPL would mandate distribution of its "corresponding source." The object code itself isn't free unless the corresponding source is supplied. A CHM is the compiled form of a pile of sources. It isn't open source by itself, but it is open source if the "corresponding source" is available. The GPL specifically excludes from its scope "general-purpose tools or generally available free programs which are used unmodified" in generating object code, to address the earlier question about closed source compilers.

None of this is directly applicable to a non-GPL project, but it's very hard to reason about free software without having a clear distinction between the source code form and the compiled form of that software. Free software is about ensuring the source is available; it doesn't try to ensure that binaries are pure source code or are capable of generating corresponding source code.

[NazmusLabs]

@malxau all this is irrilevent to what I was saying. I am speaking of "Free Software", which is separate from GPL. GPL is one type of "Free Software" license. For a software to be free, its license must give its users some clearly defined rights as defined by RMS and the Free Software Foundation. As software under the MIT license meets all criteria, it is "Free Software" by definition. The Free Software Foundation clearly lists the licenses that fall under "Free Software" license, and the foundation includes, in writing, that any software under the MIT License is "Free Software". That is sufficient enough. We don't need to worry about what GPL says or doesn't say.

My point was, if a software is free software, you are legally allowed to modify and/or reverse engineer its binary, be it in compiled form or through its source code. If a software is not free, its it may not be legal to do so.

So, I don't know if it's legal to reverse engineer the HTML Help Viewer application. I'd think not, as the Windows EULA clearly states that reverse engineering any Windows component is prohibited unless its own license supersedes it. Winfile's MIT license supersedes Windows's EULA and can be reverse engineered. HTML Help Viewer doesn't have its own EULA, and thus is bound by Windows EULA. That is the fundamental difference. I don't need to worry about what this license says or that license says. The only relevant licenses are MIT and Windows EULA. And MIT is Free Software License and Windows EULA is not.

[malxau]

If this project distributed a winfile.chm file, that would be something users are allowed to reverse engineer. Any other software, including the HTML Help Viewer, is distributed under its own license, which may prevent reverse engineering. Similarly, distributing HTML files under an MIT license that supports reverse engineering does not imply that the web browser used to view them is licensed for reverse engineering. Along the same lines, an MIT licensed winfile.exe may be legally allowed to be reverse engineered, but that doesn't extend to kernel32.dll which is used to execute winfile.exe.

In terms of licensing, the real issue with this PR is whether or not Microsoft have given their blessing to re-purposing commercially licensed help content under the MIT license.

Obviously tons of CHMs have been distributed under MIT licenses over the years without issue. If there's a really good reason to avoid using something that's part of Windows to help solve this problem, and instead implement a custom thing, so be it; but implementing a good custom thing would probably benefit greatly from a thorough understanding of what it's trying to re-implement.

[thecatkitty]

@NazmusLabs , I've checked the possibility of opening the generated HTML help on Windows 3.x (original Windows for Workgroups 3.11 PL, to be precise). It surely works as it should in IE5 but there are two things we must remember:

• file names are limited to the 8.3
• in case of possible future internationalization: IE5 on WfW knows about ISO and Windows encodings; no UTF-8 there

I've prepared a working package and attach it here: wfhelp.zip

And here's the screenshot (apparently, Windows 3.x is unable to capture 1280x1024, so just the window):

[NazmusLabs]

Ah! I had totally forgotten about the filename limitation. Thanks for the update. I would love to incorporate your changes. While I can manually extract your zip contents and make the changes, I prefer you get the credit. So, feel free to clone this PR branch, if you like, upload your changes, and create a pull request, and I'll merge it up this PR; that way you will get the credit. If you prefer, I can do this myself. It's up to you.

[NazmusLabs]

Closing this PR, as it has been superseded by #152.