Skip to content

macOS: bundle a build-time-generated Help Book#13260

Open
bo2themax wants to merge 2 commits into
ghostty-org:mainfrom
bo2themax:push-1a5d62ae
Open

macOS: bundle a build-time-generated Help Book#13260
bo2themax wants to merge 2 commits into
ghostty-org:mainfrom
bo2themax:push-1a5d62ae

Conversation

@bo2themax

@bo2themax bo2themax commented Jul 9, 2026

Copy link
Copy Markdown
Member

With this, you can now search config options, keybind actions, and cli help.

Inspired by +explain-config and idea of HelpBook from @jparise!

The diff might be overwhelming, but it doesn't affect terminals. The main part of this pr is basically HTML generation and bundling them into a .help bundle. This was first introduced in OS X and is archived, but it still works with Tips.app on macOS 27.

tips-badge-dark tips-badge-light image

AI Closure

Claude implemented most of it. I just learned how help books work and did my best to let Claude document.

TBH I didn't read every line of changes in those html/css/js files, but I tested a lot of random pages; it looks good.

I did review every Zig change after a few rounds of review from different Claude sessions; I couldn't see anything bad.

@bo2themax bo2themax requested a review from a team as a code owner July 9, 2026 17:19
@ghostty-bot ghostty-bot Bot added the os/macos label Jul 9, 2026
@bo2themax bo2themax requested review from jparise and removed request for jparise July 9, 2026 17:19

@jparise jparise left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the CApi.zig side could use some work. It looks more intrusive that the feature probably warrants. Or maybe some of this code shouldn't be in CAap.zig itself.

The other pattern that could be interesting is generating the macOS help strings at build time (and producing a .plist or similar resource) and consuming it in the macOS app.

Comment thread macos/Sources/App/macOS/AppDelegate+HelpSearch.swift Outdated
@bo2themax

bo2themax commented Jul 10, 2026

Copy link
Copy Markdown
Member Author

I think the CApi.zig side could use some work. It looks more intrusive that the feature probably warrants. Or maybe some of this code shouldn't be in CAap.zig itself.

The other pattern that could be interesting is generating the macOS help strings at build time (and producing a .plist or similar resource) and consuming it in the macOS app.

Plist generation is a good idea. I thought the changes in CApi.zig are already generating those entry in compile time.

@bo2themax bo2themax marked this pull request as draft July 10, 2026 13:54
@jparise

jparise commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

I think the CApi.zig side could use some work. It looks more intrusive that the feature probably warrants. Or maybe some of this code shouldn't be in CAap.zig itself.
The other pattern that could be interesting is generating the macOS help strings at build time (and producing a .plist or similar resource) and consuming it in the macOS app.

Plist generation is a good idea. I thought the changes in CApi.zig are already generating those entry in compile time.

Or perhaps generate a Help Book directly. I haven't used that format before, though, so I'm not sure how it trades off against the control of doing something more custom and integrated.

@bo2themax bo2themax changed the title macOS: search config&keybind in help menu macOS: bundle a build-time-generated Help Book Jul 11, 2026
@bo2themax bo2themax marked this pull request as ready for review July 11, 2026 21:59
@bo2themax bo2themax requested a review from jparise July 11, 2026 21:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants