super man page with AI-assisted tooling to generate/maintain

[philrz]

What's Changing

This adds a man page for super that can be included in our release artifacts and installed as part of brew install super. The approach uses Claude AI to generate the page from the output of super -h and select book/ docs.

Why

It's been pointed out that some developers might look for a man page rather than jumping right to https://superdb.org or relying on the brief super -h output. While man pages are not as heavily relied upon as in the past, their presence or absence may be seen as an indicator of a tool's maturity.

Details

The README gives more detail on the usage and approach. In brief, I was nervous at the thought of having yet another set of docs to keep in sync, hence the attempt to use AI. The semi-automated approach here can become an additional step right before tagging the release to make sure the man page is still current: When run, material changes to the upstream sources will be obvious as diffs in the super.1.md. With minimal human effort, these changes be incorporated into the committed man page source.

Credit

Thanks to Gilles Clement for floating the idea, creating the first draft of the prompt, and showing how an LLM could generate a decent man page for us.