vms-01b: HELP — faithful hierarchical-library reader (retire the printf shim + orphaned dead reader)

[baron-3dl]

What

Replaces the DCL HELP printf shim and the orphaned, never-dispatched reader with a single shared hierarchical HELP engine that walks a real topic tree parsed from library data — no hardcoded topic content.

Before (origin/main)

• Live cmd_help (dcl_cmd_misc.c) printed a verb one-liner + 3 hardcoded SHOW/SET/DIRECTORY blocks + a fake one-shot Topic? (no level stack, no Subtopic?, no blank-pops-level, no HELP A B C), and emitted an inauthentic %DCL-W-NOHELP on an unknown topic.
• A real recursive reader existed (tools/vms_help.c → HELP.EXE) but loaded from a compiled-in C string and was orphaned (nothing dispatched it). The honest Sorry, no documentation on X lived only in that dead code.

After

• src/vmsdcl/dcl_help.c (+ include/dcl/help.h) — parses the documented VMS numbered-level .HLP source format (1 TOPIC / 2 subtopic / 3 ...) into a key/subkey tree and renders:
  • HELP (top-level Information available: listing)
  • HELP topic (topic text + Additional information available: subtopic list)
  • HELP topic subtopic ... (deep lookup, abbreviated keys accepted)
  • the interactive Topic? / <path> Subtopic? loop (blank pops a level, EOF exits)
  • authentic Sorry, no documentation on <x> (not %DCL-W-NOHELP)
  • VMS status codes throughout (SS$_NORMAL / SS$_ITEMNOTFOUND).
• cmd_help now locates the library (SYS$HELP:HELPLIB.HLP via the logical-name tables, or $OVMX_HELPLIB as a locator override) and drives the shared engine. Honest failure — no fake fallback — if the library is absent (Rule 9 / INV-DCL).
• tools/vms_help.c (HELP.EXE) — KEPT, because the product-install e2e anti-LARP gate runs the installed image from the target device (tests/qemu/test_product_install_e2e.sh: RUNHELP MOUNT). Its 555-line orphaned reader and compiled-in help string are deleted; it is now a thin wrapper over the same shared engine, reading the real library.
• distro/Dockerfile.bootable — stages HELPLIB.HLP into the booted image's SYS$HELP (it was never copied; the old HELP.EXE only worked via its compiled-in fallback), so HELP reads real data on a running system.

Clean-room (Rule 8)

The numbered-level .HLP format, the listing headers, the prompt wording, and the not-found message are from public OpenVMS documentation (VSI OpenVMS DCL Dictionary — HELP; User's Manual — "Getting Help") and observed HELP output. The unpublished .HLB binary byte layout is not reproduced; the reader consumes the documented .HLP source form directly, labeled as an OVMX design choice.

Tests

• tests/dcl/test_help_engine.c (new hermetic ctest dcl-help-engine): top-level listing, topic text + subtopic listing, 3-level lookup, abbreviated keys, unknown topic → Sorry, no documentation on X + SS$_ITEMNOTFOUND (and NOT %DCL-W-NOHELP), and the interactive Topic?/Subtopic? loop.
• tests/dcl/test_help_content.sh: re-armed for the hierarchical behaviour (grounded in real library content).
• ctest -LE slow: 158/158 passed, exit 0.

Note / scope decision

The rd item said to delete the orphaned reader. Deleting HELP.EXE outright would break the install-e2e anti-LARP gate that activates the installed image, so instead the dead code (compiled-in string + orphaned duplicate reader) was removed and the file rewired to the shared engine — it is no longer orphaned and no longer carries hardcoded content.

Deferred (still under epic vms-01b)

Compiling .HLP → .HLB via LIBRARIAN and HLP$LIBRARY search-list location; per-command help auto-generated from CDU tables; HELP/MESSAGE from the message DB.

🤖 Generated with Claude Code