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

[jdnavarro]

@lspitzner oh, thanks, that will help.

[lspitzner]

@jdnavarro (i have not checked if there are new subcommands not listed in the script)

[jdnavarro]

It turns out that adding a new global flag that only works when there is no command is non trivial, so I'm back to writing a simple script.

The problem now is that the markdown generated by pandoc is still messy; I have to tweak how pandoc detects list of items.

Or directly bite the bullet and generate valid markdown everywhere in the code. I guess there is no easy shortcut for this.

[23Skidoo]

@kosmikus OK, I figured out how to do that. You go to Settings > Colllaborators and add people as collaborators with Read permissions. Just added @jdnavarro and a bunch of other folks.

[jdnavarro]

@23Skidoo but I can't still label or assign myself to any issue, even for the ones I reported.

[23Skidoo]

@jdnavarro I guess that you need Write permissions to do that.

[jdnavarro]

@jdnavarro Then what can I do with Read permissions that I couldn't do before? I don't understand GitHub permissions :confused:

[23Skidoo]

@jdnavarro You can now get tickets assigned to you.

[mmakowski]

@jdnavarro oops, I picked it up at the Hackathon and announced on hackage IRC channel, but didn't think of mentioning it here. I went for the darcs option suggested by @bos instead of pandoc.

[jdnavarro]

@mmakowski, well, the pandoc option is turning to be not as straightforward as I thought, so I was considering other ways to go about. Are you changing the format of console messages to manpages in the source or you are formatting the messages at runtime?

[jdnavarro]

@mmakowski I just saw the PR. Looks good!