Generate man page and/or markdown

[nomeata]

Hi,

given the highly structured and detailed data a well-polished option parser, one would really like to be able to use it to also create other bits of reference documentation that one would expect, in particular a manpage and maybe also markdown snippets to put into the README.

Such a feature would likely pull in pandoc, and hence be better put into a package of its own. This way, the dependency could be just of a special “man-page generating” executable and not bloat the real thing.

I’m not sure if the current API is well suited for this task.

Thanks,
Joachim

[HuwCampbell]

Hi,
I would imagine this it very possible. Internally we use treeMapParser to make our usage texts, which is very extendable.
You're right though, I can't put pandoc deps in this library however as it would kill our wide dep range.

[ababkin]

Hi,
I would also vote for having an auto-generated man page, even if it is rudimentary. It seems that a lot of the puzzle-pieces are already completed for the -h option, the remaining thing is to traverse the tree of sub-parsers and generate a somewhat coherent man page.
If nothing like that is available, I can take a stab at it, but would appreciate some guidance of folks who have intimate familiarity with the codebase
Thanks
Alex

[ip1981]

There is the help2man utility ;)
Though, optparse-applicative output is not perfectly friendly to it.

[shmish111]

Would pandoc really be necessary? ansi-wl-pprint is already a dependency, wouldn't this be enough to create nice man pages?

[hasufell]

@jneira pointed out: https://github.com/haskell/cabal/blob/00a2351789a460700a2567eb5ecc42cca0af913f/cabal-install/src/Distribution/Client/Manpage.hs

Also note that cabal man is a thing.

[HuwCampbell]

Ta.

[kukimik]

FWIW, this feature is now available in opt-env-conf, see the announcing blog post for an example.

[HuwCampbell]

Ta. That code has a more restrictive license than optparse, so it can't used directly. Good to know that it's relatively straight forwards though.

I think that man pages in general could be a separate package to optparse proper, but I'm open to inclusion here as well.

[HuwCampbell]

Really though, your man page is full documentation, not just options. So it's a bit of a kludge just automatically generating it.

[HuwCampbell]

PRs welcome.