Make every cabal-install subcommand help message valid markdown

[jdnavarro]

This was originally needed in #848, but I'm opening a new ticket to make the original task more granular. Feel free to assign this to me.

[jdnavarro]

I'm trying to come up with the minimal markdown syntax that still renders a manpage and HTML nicely without adding too much syntax ornamentation to the plain console help messages. In the end, it all boils down to rendering list items properly. This is what I came up after some fiddling:

https://gist.github.com/jdnavarro/23a338d7ee6ab20e7840

GitHub markdown doesn't support definition lists, but Pandoc does, so this looks nice when rendered to HTML or man format. However, I'm still not satisfied reading the raw markdown; this is a (small) step backwards compared to the original console messages, so I'm considering 2 possibilities:

1. Without touching the original console messages, write a dirty script that reformats the list items to markdown for every cabal subcommand. This should be in principle not that difficult with a shell script and some seding but I'm not entirely sure there won't be pitfalls, the key is to be able to identify unambiguously what is a list in the original messages reformatting the commandDescription fields of the different CommandUI data types in Distributition.Client.Setup with a Haskell script.
2. Whenever a help message needs to be printed, redirect the output to the corresponding man page, like for example git help commit does. The disadvantage of this is that the fundamental way to print messages would need to be changed and there may be different ways to do this depending on the platform.

I'm trying option 1. next, but if you have any opinion on this, this would be a good moment to step in.
/cc @dcoutts.

Other remarks:

• Plain markdown unordered lists look worse than definition lists.
• I'm looking at git, npm and gem as examples of programs with subcommands that print nice help messages while also having proper manpages. git looks like the most polished experience but imitating it all the way down would be overkill. It nevertheless uses some perl scripts, similar to solution 1., to embed short help messages within manpages.
• asciidoc, which git uses, is IMHO better than markdown for this particular case. The raw messages look much nicer than the markdown ones. However I don't think it's worth introducing pushing an alternative format, which is not as markdown, just for this case.
• Markdown definition lists are not in the Common Markdown standard, although many common markdown flavors implement them. It originally comes from kmarkdown.

[jdnavarro]

Option 1. is not straightforward because, for example, for the globalCommand the mainWorker in Main needs to populate the list of subcommands necessary for proper formatting. Formatting flags suffer from the same problem. Even if mainWorker is exported, it would need to be duplicated, and refactored, to support both plain text formatting and markdown formatting.

There is a 3. option: support markdown natively everywhere and strip down any superfluous markdown syntax when printing the help messages from the command line. That should be more robust and easier to pull off than trying to add markdown manually from plain text.

[jdnavarro]

For properly formatting the flag descriptions as markdown Cabal.Distribution.GetOpt.usageInfo would need to be tweaked. It can be done but it's getting quite hairy.

This issue is definitely becoming much more work than I anticipated, so I'm taking care first of what we left half-baked with @luigibozzo and @kosmikus at the Hackathon before getting back again to this issue.

[jdnavarro]

No longer needed after #2877