search

pcapriotti / optparse-applicative

Applicative option parser
BSD 3-Clause "New" or "Revised" License
915 stars 116 forks source link

Generate man page and/or markdown #176

Open nomeata opened 8 years ago

nomeata commented 8 years ago

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 commented 8 years ago

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 commented 7 years ago

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 commented 7 years ago

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

shmish111 commented 5 years ago

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

hasufell commented 3 years ago

@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 commented 3 years ago

Ta.

kukimik commented 4 months ago

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

HuwCampbell commented 4 months ago

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 commented 4 months ago

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

HuwCampbell commented 4 months ago

PRs welcome.