man page

[silby]

 ~$ man gleam
man: No entry for gleam in the manual.

Would the project welcome a PR to start adding a man page for gleam(1) to Gleam? What guardrails/requirements would you have to want to maintain it? I observe that the existing CLI reference doc is generated by postprocessing gleam help output.

Some projects single-source man pages from help output like this, but that can be pretty limiting. I tend to think --help output should be concise and reference documentation should be thorough. The gleam binary should have a more detailed reference available.

Some projects single-source man pages from Markdown or similar, e.g. using Pandoc. I think the main motivation for this is the unfamiliar and line-noisy appearance of roff and man markup, and secondarily ease of rendition of the manual to HTML within an existing site build. Personally I think the mdoc language, which is a bit less common but supported by all relevant man implementations, is approachable to anyone who knows HTML, and is the thing to use to write a man page from scratch. You can also get good HTML renditions out of mandoc and style/template them to fit in to your website of choice. A drawback of using mdoc is that it's not supported as an input format by very many tools and so your single-sourcing possibilities may be limited or require shelling out to things you'd prefer not to shell out to.

I observe lpil is working on a Gleam website in Gleam, with Djot as the content format. Maybe the best fit for the project would be to write a gleam reference in Djot and write some code to render a jot.Document as man or mdoc macros.

[lpil]

Sounds like a good idea to me! I would say that mdoc seems like a good choice, but your point about the website is a very good one. It would be ideal to have a description of the API in Gleam data types which are then used to generate HTML documentation, a man page, and anything else.

A package which defines a data structure for mdoc documents and then a function to turn it into an mdoc string would be useful.

[silby]

Thanks for the encouragement! I realized after this reply that I introduced multiple lines of work with a single idea, which is never a great move, but I'm glad you're open to shipping a gleam(1) man page in any case. I started drafting one in mdoc, which is already getting me looking at the CLI source to understand things that aren't precisely documented yet, which is meeting my own immediate goals at least. I'll hopefully pop up again eventually with more on this.