search

haskell / cabal

Official upstream development repository for Cabal and cabal-install
https://haskell.org/cabal
Other
1.63k stars 696 forks source link

Add manpage that linux distributions can ship #10544

Open UnlimitedCookies opened 1 week ago

UnlimitedCookies commented 1 week ago

Generally I expect a binary like /usr/bin/cabal to be accompanied by a helpful manpage. This should include available flags/subcommands and perhaps a few examples.

ffaf1 commented 1 week ago

We have (undocumented) cabal man.

ulysses4ever commented 1 week ago

It'd be nice to have, I agree. The downside is we already have a big issue with our reference manual and cabal --help duplicating each other and wildly diverging at times, with some info available in one but not in the other.

cabal man had little maintenance over the recent years, I think, so I'd expect it to be even more badly outdated. I wish someone worked on making our help pages uniform and produced from a single source of truth. Even providing examples of setups that achieve that would be helpful.

I noticed you can't say cabal man build or such, which would be desirable too.

UnlimitedCookies commented 1 week ago

It'd be nice to have, I agree. The downside is we already have a big issue with our reference manual and cabal --help duplicating each other and wildly diverging at times, with some info available in one but not in the other.

Perhaps they could be consolidated into one or few sources of information that then get populated into the various sources. The git manpages are a good example for how to do it right, but it seems like they spent quite a lot of effort on that.