vms-01b: HELP .HLB compilation + HLP$LIBRARY search list

[baron-3dl]

Summary

Next deferred slice of the HELP facility epic (vms-01b), following #449's hierarchical .HLP engine: .HLB help-library compilation and HLP$LIBRARY search-list location. The epic stays open — per-command CDU help, HELP/MESSAGE, and the terminal subtopic-prompt-for-specified-topic remain.

What landed

.HLB compilation — LIBRARY/HELP/CREATE lib.HLB src.HLP compiles a numbered-level .HLP source into a key-indexed .HLB. A VMS HELP library is keyed by its level-1 topics, so the compile splits the source by level-1 keys and writes one module per key into the OVMX "LBRO" container (dcl/hlb.h), reusing the vms-ca9 LIBRARIAN library infrastructure. LIBRARY/HELP list/extract keep working on the compiled form.

.HLB reader — dcl_help.c help_open_hlb() reads the modules in index order and reconstructs the exact numbered-level tree, so a compiled .HLB is indistinguishable from its .HLP source once loaded. help_open_any() auto-detects LBRO magic vs raw source.

HLP$LIBRARY search list — HELP resolves its library through the documented HLP$LIBRARY, HLP$LIBRARY_1..n search list (help_open_libraries()), each translation defaulting to .HLB, falling back to SYS$HELP:HELPLIB.HLB then .HLP. Libraries merge in search order, so a topic in an earlier library wins.

.HLB representation choice

The .HLB is the existing OVMX "LBRO" container (shared with LIBRARY/LIBRARIAN via the new dcl/hlb.h), library type HELP, one module per level-1 key. This reuses vms-ca9's infra rather than defining a second format.

Clean-room (Rule 8)

The LIBRARY command surface, the HELP library-compile semantics (each level-1 key is a module), and the HLP$LIBRARY search list are documented behavior — VSI OpenVMS DCL Dictionary (LIBRARY, HELP) and the VSI OpenVMS Command Definition, Librarian, and Message Utilities Manual (Librarian). The unpublished .HLB byte layout is NOT reproduced; the LBRO container is a labeled OVMX design choice, never presented as VMS-authentic.

No facades (INV-DCL)

Real compile writing a real indexed file, real search-list resolution, real content lookup — no hardcoded help. VMS status codes throughout.

Tests

• tests/dcl/test_help_engine.c — hermetic .HLB-reader + search-list-merge coverage (builds an LBRO container by hand, asserts navigation; two-library merge asserts first-library precedence). 29/29 ok.
• tests/dcl/test_help_hlb.sh (new) — drives the full DCL chain: compile two .HLB libraries, wire HLP$LIBRARY + HLP$LIBRARY_1, assert HELP reads a topic present only in the first via HLP$LIBRARY, one only in the second via HLP$LIBRARY_1 (search continues), and first-library precedence for a shared key.
• dcl-integration 136 passed / 0 failed; dcl-help-engine pass; dcl-harness-selftest pass. No vms-01b: HELP — faithful hierarchical-library reader (retire the printf shim + orphaned dead reader) #449 regression (existing HELP-content and LIBRARY tests green).

Native-link

No new translation unit or cross-image symbol (only a new header included by existing TUs + functions inside dcl_help.c/dcl_library.c/dcl_cmd_misc.c). Native-link enumerations unchanged — run_dcl_native.sh NOBJ stays 25 — and the three touched TUs compile clean under freestanding musl (-ffreestanding -fno-builtin).

Follow-up (not in scope)

The shipped SYS$HELP:HELPLIB.HLP is left as .HLP source (the reader consumes it, and the .HLB fallback is tried first); precompiling a HELPLIB.HLB into the bootable image is a mechanical follow-up.

🤖 Generated with Claude Code