cabal-install needs a manpage #848

Closed
bos opened this Issue May 24, 2012 · 23 comments

Comments

Projects
None yet
9 participants
Contributor

bos commented May 24, 2012

(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.

Contributor

bos commented May 24, 2012

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

Also see #690.

Yes!

@23Skidoo 23Skidoo self-assigned this Jun 8, 2014

Collaborator

BardurArantsson commented Jun 25, 2015

"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 23Skidoo removed their assignment Jun 26, 2015

Member

23Skidoo commented Jun 26, 2015

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

Collaborator

jdnavarro commented Oct 11, 2015

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

Member

23Skidoo commented Oct 11, 2015

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

Collaborator

jdnavarro commented Oct 11, 2015

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.

Contributor

kosmikus commented Oct 11, 2015

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

Member

23Skidoo commented Oct 11, 2015

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

Collaborator

phadej commented Oct 11, 2015

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

screen shot 2015-10-11 at 16 11 00

Collaborator

jdnavarro commented Oct 13, 2015

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.

Collaborator

lspitzner commented Oct 13, 2015

@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

Collaborator

jdnavarro commented Oct 13, 2015

@lspitzner oh, thanks, that will help.

Collaborator

lspitzner commented Oct 13, 2015

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

Collaborator

jdnavarro commented Oct 13, 2015

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.

Member

23Skidoo commented Oct 13, 2015

@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.

Collaborator

jdnavarro commented Oct 13, 2015

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

Member

23Skidoo commented Oct 13, 2015

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

Collaborator

jdnavarro commented Oct 13, 2015

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

Member

23Skidoo commented Oct 13, 2015

@jdnavarro You can now get tickets assigned to you.

Collaborator

mmakowski commented Oct 17, 2015

@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.

Collaborator

jdnavarro commented Oct 18, 2015

@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?

Collaborator

jdnavarro commented Oct 18, 2015

@mmakowski I just saw the PR. Looks good!

@23Skidoo 23Skidoo closed this in #2877 Oct 22, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment