Automating AnoHAT HXS → JavaHelp Conversion for Documentation Teams

Quick Tutorial: Transform AnoHAT HXS Files into JavaHelp TopicsConverting legacy help formats into modern, maintainable help systems is a common task for documentation teams. This tutorial walks through converting AnoHAT HXS files (compiled HTML Help eXtended sources often used in older Windows help systems) into JavaHelp topics. You’ll learn how to extract content, prepare assets, map structure, and generate JavaHelp-compatible HTML and XML so the resulting help set integrates cleanly with Java applications.

---

What you’ll need

• A Windows machine (or VM) with tools to extract HXS/HHC content, or access to the original source HTML.
• Decompiler/extraction tools (examples: 7-Zip, Microsoft HTML Help Workshop, HxS decompiler tools).
• A text editor or IDE (VS Code, IntelliJ, or similar).
• JavaHelp SDK (if you plan to build and test a JavaHelp set locally).
• Basic knowledge of HTML, CSS, and XML.

---

Background: HXS vs JavaHelp

• HXS: A compiled help file format from Microsoft (used by HTML Help and components like Help 2 / HxS); content often includes HTML pages, images, a contents/index file (.hhc, .hhk), and compiled metadata.
• JavaHelp: An Oracle/Sun help system for Java applications; uses a contents map (map.xml), TOC (toc.xml), search indices, and topic HTML/XHTML pages. JavaHelp expects a specific directory structure and XML configuration (helpset file).

---

Step 1 — Extract HXS contents

1. If you have the original source files (HTML, images, CSS), start with those. If only the compiled HXS is available:
   • Try simple extraction with 7‑Zip (right-click → Open archive). Some HXS files can be opened like archives.
   • If that fails, use specialized HXS extraction tools or an HxS decompiler. Search for “HxS decompiler” or “extract HXS contents” to find community tools.
2. Result: a folder containing topic HTML pages, images, style sheets, and navigation files (for example, .hhc for table of contents, .hhk for index).

---

Step 2 — Audit and cleanup extracted HTML

1. Open several topic files to check HTML quality:
   • Look for non‑standard HTML (framesets, ActiveX, script-heavy navigation).
   • Check encoding and character set declarations (convert to UTF‑8 if necessary).
2. Normalize doctype and structure:
   • Convert legacy markup into well-formed HTML5 or XHTML (JavaHelp works with HTML; XHTML often yields fewer quirks).
   • Remove or adapt deprecated tags (font, center) and inline event handlers that may break in JavaHelp.
3. Consolidate CSS:
   • Collect all stylesheets and move them into a single styles folder. Adjust relative paths.

---

Step 3 — Plan the JavaHelp structure

JavaHelp requires a particular file layout and several XML files:

• helpset (.hs)
• map file (map.xml) — maps topic IDs to files
• table of contents (toc.xml)
• index (index.xml) — optional, but useful
• search index files — generated by JavaHelp tools
• /docs — folder with topic HTML/XHTML and assets

Decide how the existing HXS TOC (often .hhc) will map into JavaHelp’s TOC. Keep topic IDs consistent and meaningful (for example, using original HXS anchor names).

---

Step 4 — Convert TOC and Index

1. Extract structure from .hhc (TOC):
   • The .hhc file is an HTML-like file with nested