Show HN: I created a portable lightweight replacement for Microsoft HTML Help | Hacker News Reader

Show HN: I created a portable lightweight replacement for Microsoft HTML Help

dmitripopov.com

77 pointsdmitripopov40 comments

I hated chm because the spec wasn't open. With only 1 reference implementation, it was user-hostile. Unless the spec for helpinator is open, I don't see myself using this.

reverse engineered chm spec and the complexity boggles my mind: https://www.nongnu.org/chmspec/latest/

It's a folder with xml files, content is pretty self-explanatory, but I should write a description.

Why xml and not simply zipped htmls?

Everybody knows how to author html, if xml is some specific new set of rules, what is the advantage of that approach?

If it is xml, what makes it different from the epub format? Is epub format the subset? What were the advantages of it not being the subset?

Why XML? In the context of the CHM format I suspect because the answer to everything around that time was XML. If XML wasn't solving your problem you needed more of it.

I've thought what's shown here (and what I've asked about) is a new format that should replace CHM, and not the old "real" CHM?

When CHM arrived on the scene, ZIP was far from being treated like container format, and definitely not ubiquitous.

As for XML - it's ch easier to make a stable parser that is complete and fast for XML than it is for SGML-based HTML, and indeed the was a big push towards XML everywhere... Partially because of that reason.

Because technical writing is about structured authoring (e.g. using specialized content items like step-by-step guides, FAQs or Quizzes) and I follow this metaphor, avoiding excessive formatting options and concentrating on things that matter.

How does that differentiate it from ePub? Because "a compressed folder with XML files" is how I describe that format.

Epub suffers from the same flaws - only one language per file, freeform styling that makes company-wide style consistency problematic (and when we talk about a ERP system with thousands of users and a miriad supplementary tools created for it - it's a really big problem).

And it was not designed for context-sensitive help of desktop apps, while LiteHelp is.

CHM was a replacement for an even weirder format (HLP, and its reader WINHELP) carried over from Windows 3.0. It was a gopher-like hierarchy of hypertext pages, but with RTF-based formatting as opposed to HTML, and a weird, proprietary container format. Given that context, CHM meant some progress.

Thanks for mentioning chmspec, I think it was a mistake for me to focus on writing it instead of writing an open source library that other tools could use to read the CHM format; several folks (xCHM etc) had to re-implement code instead of just depending on a library.

These days I think I would have used Kaitai Struct to create a declarative specification and generated library code and a human-readable specification from that.

https://kaitai.io/

The reverse engineering of the CHM format was pretty rewarding though, it felt good to bring CHM access to the Linux community. I never got as far as scratching my original itch of having a CHM compiler that runs on Linux, instead I got distracted by open source and just ditched the proprietary world entirely.

If anyone feels the need to get involved in open source but isn't sure how or where, reverse engineering proprietary formats, drivers and firmware is needed now more than ever and is very rewarding both intellectually and for enabling the community.

I wish Microsoft had used an existing standard container format like ZIP instead of inventing yet another container format. They have created lots of different container formats over the years; OLE, ITSF, istorage from back then and probably more in recent times.

Kaitai Looks interesting and rich. Thou I don’t get the license gpl3 for the compiler and MIT for the runtime, you can use the runtime without the compiler ? Why split them up licensing wise

I haven't used it but I think the idea is that if they want the tool to be used in proprietary software; the runtime needs to be license-compatible with anything, but the compiler can be any license, so may as well be one that ensures the compiler will always be open.

There should be some punctuation in the title. The tool is named "Help". A quick skim doesn't make it seem like the author is in need of urgent assistance.

Ha, sorry :) Should have quoted "Microsoft HTML Help"

This is awesome, I've been wanting something like this for a decade. But if there's no html inside, does that mean I can't style the content with css (or otherwise)?

It's not a problem to add styles, especially since LiteHelp is based on structured content, but hey, is that feature so needed? All my client do with HTML templates of Helpinator is to add their own logo and that's it. Content is what matters.

Have you tried Zeal or Dash?

I think you can convert CHM to ePub using Calibre, then convert from ePub to whatever you want using pandoc, then import that into Zeal?

I am well aware of Zeal, and it's cool for docs that people read from cover to cover. My primary objective was to not to create a new format, but rather provide means for authoring and displaying structured technical content, pretty much like DITA or DocBook, but way more simple and targeted at software (e.g. providing a context-sensitive help feature).

My use case for Zeal or Dash is searching API documentation.

Oh, I understand. My primary objective is on end user manuals, not developer docs.

This is cool. But I feel like the default styles could use some improvement (if possible).

Email me your suggestions, please, I am always open. popov.dmitri@gmail.com

Without exaggerating much, I don't know a single person, technical or not, who ever read a single help file for any Windows software. There's even less sense in these files now as opposed to keeping all documentation online.

So I have to say I don't see a point in this product... though I suspect there is actually a market for it.

Perhaps I'm simply too old, but my first decade of computing was spent using software installed from CD-ROM drives, which you would typically purchase in a brick and mortar store, drive to your house, and install once. We had dial-up at the time, but it was painfully slow and as a kid I wasn't allowed to use it all that often.

HTML help files were the only way I had to really discover the hidden features in any of the software I had. I dove deep into those manuals and read every section, sometimes more than once, just to familiarize myself with what was possible. If I couldn't figure something out, the option to "just Google it" wasn't on the table; the help feature built into the program was the best shot at finding the solution. It was also relatively standard: just about every bit of software, even lots of games, used the same format and had the same basic UI to navigate and search the text.

Maybe times are different now, and internet-based help really is the way to go, but for a long while they were the next best thing to a paper manual: easy to ignore, but incredibly handy when required.

For what it's worth, I grew up on MS-DOS, so I am of comparable age if not older than you.

I still stand by my observation - very few people read help _files_. Printed manuals - yes, those were read and they were undoubtedly useful, but not the electronic versions. They are usually bloated with so much filler and so cumbersome to use that people just don't bother.

I have definitely spent plenty of time reading help files as well. Some are very useful, and I would say they are often more useful than a man page just due to the more verbose format.

I used to use them (usually to no avail) for the office products a couple decades ago. I try to use F1 now occasionally but even for excel it’s faster to just do a web search.

I've sadly noticed that for last few (since 2007?) versions F1 leads you to a web page that usually is quite useless. Back on Office 2003 and earlier, I could blitz through anything low to medium complexity in Office by hitting F1 :-(

A lot of early "e-books" were distributed as .chm

You know, back when there were modems, and before the Eternal September spread to the rest of the world (1993 ... 2000)

I find chm readers much more friendly for reading books on the desktop than proper ePub readers. It is nice to have a nicely laid out table of contents right next to the text. In addition, chm readers are also much faster than ePub ones.

Those pirate CHMs of books were usually surprisingly well indexed, with proper table of contents.

When I was contracting I'd carry a disc or two of CHMs - basically the bookshelf back home, to avoid carting actual books.

Xbox One SDK and DirectX documentation is still distributed in CHM form and it's very useful still to have one file to refer people to and that you don't need to be online for.

I disagree, as well. CHM files were great - they were local, so you could find help even when you didn't have an internet connection. I found them quicker to pull up than a web page, and they didn't have the ads, laggy front-end frameworks or telemetry. They tended to force vendors to be more thoughtful with their documentation than the link-to-a-blog-site that often passes for "technical documentation" today.

Not saying they're perfect or solve everything, but I'm thankful to the author for making this tool.

I recently read all the help files for Keyboard Layout Creator from Microsoft. The tool is a bit old now (no update since 2007), the help pages have some interesting information difficult to find online.

Its such a superior model. Im angry that it disappeared. I was shocked to see that Microsoft got away with replacing actual help files with links that open a search query in Bing (completely abused by SEO and spammers). This is such a regression.

Generally the developer doc was much better when we got MSDN on a CDROM as opposed to todays crap where links eventually become 404 because the MS web team decided to shuffle things around.

It used to be fantastic when you could click on the help button on a form or hit the F1 key, and a local help file would come right up. This capability used to be very emphasized in the Microsoft documentation - a million years ago, before 2000.

Sadly, it's all gotten lost in the shuffle over time, and 1.) Nobody writes comprehensive documentation anymore and 2.) Nobody knows the capabilities that are built in for desktop software to take advantage of.

One that sticks in my mind was the help file for mIRC, as a kid trying to script my irc client, it was pretty damn useful.

(Of course moved on to ircii, bitchx, etc.)

>keeping all documentation online

And destroy it with outsourced writers. MSDN 2001 is the last piece of readable documentation about windows that is still available in some form.

I know at least a dozen :) Just kidding. I know a lot more. Enterprise systems tend to have so complicated business processes that a detailed help file is a must.

Reply on news.ycombinator.com