5 ms·

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

77 points by dmitripopov 7y ago

captn3m0 7y ago
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/ https://www.nongnu.org/chmspec/latest/
- dmitripopov 7y ago
  It's a folder with xml files, content is pretty self-explanatory, but I should write a description.
  - acqq 7y ago
    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?
    - dspillett 7y ago
      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.
      - acqq 7y ago
        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?
    - p_l 7y ago
      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.
    - dmitripopov 7y ago
      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.
  - Endy 7y ago
    How does that differentiate it from ePub? Because "a compressed folder with XML files" is how I describe that format.
    - dmitripopov 7y ago
      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.
- zozbot234 7y ago
  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.
- pabs3 7y ago
  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/ 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.
  - zaphirplane 7y ago
    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
    - pabs3 7y ago
      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.
Bonooru 7y ago
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.
- dmitripopov 7y ago
  Ha, sorry :) Should have quoted "Microsoft HTML Help"
eps 7y ago
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.
- zeta0134 7y ago
  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.
  - eps 7y ago
    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.
    - sgc 7y ago
      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.
roel_v 7y ago
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)?
- dmitripopov 7y ago
  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.
Aeolun 7y ago
This is cool. But I feel like the default styles could use some improvement (if possible).
- dmitripopov 7y ago
  Email me your suggestions, please, I am always open. popov.dmitri@gmail.com
29athrowaway 7y ago
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?
- dmitripopov 7y ago
  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).
  - 29athrowaway 7y ago
    My use case for Zeal or Dash is searching API documentation.
    - dmitripopov 7y ago
      Oh, I understand. My primary objective is on end user manuals, not developer docs.

77 points by dmitripopov 7y ago

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/ https://www.nongnu.org/chmspec/latest/

dmitripopov 7y ago
It's a folder with xml files, content is pretty self-explanatory, but I should write a description.
- acqq 7y ago
  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?
  - dspillett 7y ago
    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.
    - acqq 7y ago
      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?
  - p_l 7y ago
    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.
  - dmitripopov 7y ago
    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.
- Endy 7y ago
  How does that differentiate it from ePub? Because "a compressed folder with XML files" is how I describe that format.
  - dmitripopov 7y ago
    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.
zozbot234 7y ago
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.
pabs3 7y ago
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/ 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.
- zaphirplane 7y ago
  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
  - pabs3 7y ago
    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.

Bonooru 7y ago

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.

dmitripopov 7y ago
Ha, sorry :) Should have quoted "Microsoft HTML Help"

eps 7y ago

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.

zeta0134 7y ago
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.
- eps 7y ago
  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.
  - sgc 7y ago
    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.

roel_v 7y ago

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)?

dmitripopov 7y ago
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.

Aeolun 7y ago

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

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

29athrowaway 7y ago

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?

dmitripopov 7y ago
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).
- 29athrowaway 7y ago
  My use case for Zeal or Dash is searching API documentation.
  - dmitripopov 7y ago
    Oh, I understand. My primary objective is on end user manuals, not developer docs.