cabal-install needs a manpage

[bos]

(Imported from Trac #858, reported by @nomeata on 2011-06-19)

The cabal binary shipped by cabal-install ought to be documented with a manage. Ideally, cabal could generate one by itself from the Command declarations, similar to how darcs does it, this way there is no duplication of documentation.

[bos]

(Imported comment by @kosmikus on 2011-06-19)

Also see #690.

[jbnicolai]

Yes!

[BardurArantsson]

"Yes!" what?

@23Skidoo are you (realistically) going to do this since you haven't in ~1 year? If not, at the very least, you need to un-assign yourself, and perhaps close this issue as "WONTFIX".

[23Skidoo]

I used to assign tickets to myself so as to not forget about them, but now I use a wiki page.

[jdnavarro]

Feel free to assign this to me. If anyone else is working on this at the Hackathon2015, please let me know.

[23Skidoo]

Looks like it's only possible to assign tickets to members of the Haskell organization.

[jdnavarro]

After discussing with @dcoutts, it seems imitating the way pandoc creates its own manpages is the most sensible option right now. The source documentation will be written in a markdown and a script using pandoc in the scripts/ directory will generate the manpages in a predetermined path which will be registered in the cabal file as extras source files. This will also allows to easily generate extra formats like HTML or PDF in the future, if necessary.

Notice that anyone trying to build cabal from the repository will have to make sure that every dependency for the script is met. However, this is not necessary for users downloading an already built package.

[kosmikus]

@23Skidoo Can we not make people a member of the organisation without giving them commit permission immediately?

[23Skidoo]

@kosmikus Maybe, but I can't figure out how to do that. Maybe one needs more permissions.

[phadej]

Github ACL is a bit complicated, especially as it gone thru few changes recently.

There are outside collaborators and organisation members, both can be in teams IIRC.

Without any idea how Haskell organisation is configured, but you could have

• a team per each project (or closely related projects) with push rights
• people without any team with default repository permission set to none could probably be assigned tasks

[jdnavarro]

Would it be worth adding a new global command line option, like --full-help, where the help messages for cabal and all its subcommands are displayed together? I'd have to do the same for the manpage in a script anyway, so it'd be the same effort.

[lspitzner]

@jdnavarro
just fyi: i previously used the (bash) script [1] to generate/review diffs for changes to the documentation. But it might indeed be useful to include that functionality directly in cabal-install.

[1] https://gist.github.com/lspitzner/6600cf70030f934e5fc8#file-1_print-all-help-sh