#730 GTK3V2MAIN: nearly every dialog's Help button is broken (70 of 71 dialog names have no matching page)

[Allen D Byrne]

Found while investigating SF #729 (command-context F1 help links). There are 3 separate wHelp() call sites in the codebase, and #729 only covered one of them (app/wlib/gtk3lib/help.c's DoHelpMenu, the F1/menu-driven 'Command Context help' system, keyed by AddMenuButton()'s helpKey).

A second, completely independent path: app/wlib/gtk3lib/dialog.c:169 -- every parameter dialog's own 'Help' button fires GTK_RESPONSE_HELP, which calls wHelp(dialog->name), using the dialog's internal paramGroup_t name (e.g. 'block', 'turnout', 'pref') as the topic, looking for file:///<applibdir>/html/<name>.html.</name></applibdir>

Confirmed this is live and reachable, not dead code: e.g. app/wlib/gtk3lib/ui/block.ui has a real, visible '_Help' button (id_help) wired to action-widget response="GTK_RESPONSE_HELP" in its GtkDialog action-widgets.

Extracted all 71 paramGroup_t dialog names declared across app/bin/.c -- the literal first string field of each "paramGroup_t xxxPG = { NAME, ... }" declaration -- and checked each against the real built User Guide (a local Doxygen 1.16.1 build of the help-html target, app/doc/.dox). Result: 70 of 71 have no matching page at all -- only 'index' happens to match. Clicking Help on almost every dialog in the app (Block, Turnout, Preferences, Print, Structure, Elevation, Switchmotor, Signal, Train, Group, Rescale, Rotate, Sensor, Text, etc.) currently opens the generic 'Help Error - help information cannot be found' notice from browserhelp.c.

Importantly this does NOT look like a fresh regression from SF #219 (Halibut->Doxygen migration) the way #728/#729 were: the wHelp(dialog->name) line in dialog.c traces back well before this year's migration (present since at least Hg rev 5569, and unchanged except reformatting since), and the doc content (app/doc/*.dox) has only ever used 'cmd'-prefixed page names (cmdBlock, cmdSwitchmotor, etc.), never the bare dialog names dialog->name actually looks up. This looks like a long-standing, pre-existing gap between the dialog Help-button mechanism and the actual doc content, not something that broke recently -- worth confirming against the old Halibut-era docs if anyone has an archived copy, but not investigated further here.

Also checked the third wHelp() call site while auditing this: app/bin/menu.c's ShowMessageHelp() (the 'Recent Messages' list's per-item help lookup, triggered via a msgKey parsed out of a tab-delimited message string in app/bin/misc.c's ParseMessage()). Searched app/bin/*.c for any InfoMessage/ErrorMessage/NoticeMessage call passing a literal format string with the required two embedded tab characters -- found none. This path appears to be dead/unreachable in the current codebase (no code currently constructs a message in the format ParseMessage() expects), so not counted as a live broken-link surface, unlike the dialog Help-button path above.

Given the scale (70 dialogs, not a handful of links), this needs its own scoped investigation/fix rather than folding into #729's small content fix -- likely candidates: (a) write real per-dialog help content for all 70 (a lot of authoring work), (b) point dialog->name lookups at the nearest existing 'cmd'-family page instead (would need a per-dialog mapping decision, not mechanical), or (c) some hybrid. Not decided here. A CI regression check analogous to #729's help-links-check (extract every paramGroup_t name, verify a matching page exists) would be straightforward to add once the content approach is decided.

Correction 2026-08-25: this ticket's original description had one sentence's embedded code snippet silently dropped by a shell command-substitution bug (a backtick pair in the creation script's argument was interpreted by bash) -- this update replaces the full description with the corrected text.

[Allen D Byrne]

Correction to the first two commits on the bug-730-dialog-help-mechanism-gtk3 Hg branch (already pushed here): they fixed the wrong code path.

They wired a fix into app/wlib/gtk3lib/dialog.c's GTK_RESPONSE_HELP switch case, believing wHelp(dialog->name) was the live Help-button mechanism. That function is entirely dead code -- wWinDialogCreate() never connects a "response" signal to it, so it can never run. (Its containing function is additionally broken by an unrelated unclosed /** comment that swallows the whole function body -- found while investigating, left as a separate, harmless-because-unreachable observation.)

The real, already-compiled mechanism is app/bin/form/dialog.c's FormCreateDialog(), which builds every dialog's "id_help" button with a direct click handler computing "cmd" + Capitalize(dialogName) inline -- bypassing dialog->name entirely. This means the first fix had zero real-world effect even though local verification showed it passing (the check modeled the same wrong mechanism).

A third commit just pushed corrects this: reverts the dead-code changes, moves GetDialogHelpTopic() into app/bin/form/dialog.c (its actual compiled home -- the original location, app/bin/paramwrapper.c, turned out to be a second, independent dead-code file not in the CMake source list at all), and preserves FormCreateDialog's existing "cmd"+Capitalize default exactly. Consequence: about 40 of the 76 tracked dialogs needed zero code change -- they were never actually broken, only mis-diagnosed by checking the wrong lookup key. Verified this time with a genuinely clean (ccache-disabled) rebuild and confirmed via nm that the function symbol is actually linked in, not just a successful-looking build.

Net effect on the real gap: unchanged from the original 35-dialog tracked list (app/doc/known_missing_dialog_help.txt) plus one new alias found during re-verification (the "index" dialog / "Select Index" -> cmdSelectIndex).

[strobelight]

I built from your branch and checked a few which did show up. An oddity is that the browser opened a new tab for each help request, but I can't say whether or not that's always how it worked. Another plug for webkit help.

In any event, looks good to me.

[Allen D Byrne]

Thanks for testing! Investigated the new-tab behavior before merging.

It's not caused by this fix. The Help-button mechanism itself (app/wlib/gtk3lib/browserhelp.c
and opendocument.c) is untouched by this branch -- diffed against GTK3V2MAIN mainline and
confirmed. Each Help click calls wHelp() -> wOpenFileExternal() -> gtk_show_uri_on_window(),
which on Linux hands off to the desktop's default URI handler (xdg-open) with a fresh
file:// URL each time. There's no window/tab handle kept around to reuse, so the browser opens
each request as a new tab -- that's the existing, longstanding behavior of that call, dating
back to 2015/2018.

Also checked ButtonHelp() -- it's a single wHelp() call per click, no duplicate dispatch.

Most likely reason it wasn't noticed before: prior to this fix 70 of 71 dialogs' Help buttons
pointed to dead pages, so there was rarely a second successful help open in the same session to
compare against. Now that the links resolve, the pre-existing one-tab-per-request behavior is
just visible for the first time.

Proceeding with the merge into GTK3V2MAIN mainline.