winhlp

A pure-Python parser for Windows Help (.hlp) and MediaView (.mvb) files — the help format used from Windows 3.0 through Windows 95 before everything went all chmmy. It parses a help file into a structured object model and can export it to JSON or a single browsable HTML page.

Based on helpdeco by Manfred Winterhoff, Ben Collver, and Paul Wise, therefore GPL licensed.

• 🏠 home
  • 📖 helpfile
• 😺 src
• 🐍 pypi

Install

pip install winhlp

Requires Python 3.13+. pillow-wmf renders WMF images in the terminal viewer and converts them to PNG in HTML exports.

Command line

winhlp file.hlp                        # open the interactive terminal viewer
winhlp file.hlp --json                 # dump the parsed structure as JSON
winhlp file.hlp --raw                  # JSON including raw byte blobs (base64)
winhlp file.hlp --html out.html        # render the whole file to one HTML page
winhlp file.hlp --html out.html --images extract   # write images to out_images/

The terminal viewer has searchable Topics, structured Contents and Index sidebars, keyboard and mouse links, cross-file back/forward history, WinHelp browse-sequence navigation, popup and secondary-window topics, formatted tables, and inline bitmap/hotspot rendering with descriptive fallbacks. Press / to search, o/c/k to switch sidebar views, Tab/Shift-Tab to select links, Enter to follow one, m to toggle a bookmark, g to browse bookmarks, n to edit a topic note, i/d/e for file/topic/error details, and q to quit. Bookmarks and notes are saved beside the help file in a small <filename>.user.json sidecar; original HLP and ANN files are never modified.

The HTML export is a single self-contained page: a table of contents followed by every topic as an anchored section, with internal jumps/popups turned into in-page links, character formatting from the |FONT descriptors as CSS, and images embedded as PNG data URIs (or extracted to a folder).

Library

from winhlp.lib.hlp import HelpFile

hlp = HelpFile(filepath="file.hlp")
for topic in hlp.topic.get_all_topics():
    print(topic.title, topic.context_names)
    print(topic.get_plain_text())

hlp.model_dump()          # full structured data (Pydantic)
hlp.parse_errors          # non-fatal per-file problems, if any

from winhlp.lib.html import export_html
open("out.html", "w").write(export_html(hlp))

What it handles

• WinHelp 3.0, 3.1, and Windows 95, plus MediaView .mvb books.
• Topic text and formatting, tables, hotspots/jumps, bitmaps (|bmN, SHG/MRB, named MediaView resources), phrases (old-style and Hall compression), |CONTEXT/keyword/title cross-references, and context-id recovery.
• Malformed or truncated files degrade gracefully (see parse_errors) rather than aborting.

Parsing has been validated across ~6,500 real-world help files.

Development

make dev       # set up the venv + pre-commit hooks
make test      # run the test suite
make coverage  # HTML coverage report in htmlcov/

scripts/compare_helpdeco.py <files or dirs> checks extracted text against helpdeco. It builds helpdeco from ref/ with gcc, decompiles each file to RTF, and reports word-level agreement per file, with the worst diffs.

License

GPLv2, because that's what the original is.

As much as I dislike restrictive license terms, it'd be a lie to say this wasn't derived from the source code of helpdeco.