[darcs-devel] [patch2043] improve help texts and how they are generated

[Ganesh Sittampalam]

Ganesh Sittampalam <ganesh at earth.li> added the comment:

>   * fix formatting of manpage

OK

>   * remove escaping of '-' and '\' when generating the manpage

OK

>   * autoformat help for whatsnew

OK

>   * fix manpage formatting of bullet lists in help Docs

OK

>   * remove unused function usageInfo from D.UI.Usage

OK

>   * remove export of formatOptions from Darcs.UI.Usage

OK

>   * move debugging options to the end of the advanced options

OK (moving around Bools is always a bit dangerous but I don't think you
missed anything).

>   * shorten the help for alias commands

OK

>   * fix docs and description for the status command

OK

>   * add extended help for rebase super command

Thank you :-)

>   * remove historyEditHelp from rebase apply/pull

OK

>   * simplify a logical expression

OK

>   * include help for super commands in the man page

OK

>   * remove some extraneous spaces

OK

>   * slightly extend help text for darcs show and darcs convert

OK

>   * slightly re-word some option descriptions
>   
>   Use of "give" as in "give human-readable output" sounds like bad english to
>   me. I kept it only for options that modify how the user /enters/ information
>   e.g. when recording a patch.

I think "give" was ok, but your re-wordings are fine too. I'm not sure
if it would make it clearer to only use a single verb for output, like
"produce". Some of the options add new output and some change the format
of existing output, maybe we should explicitly distinguish the two.

>   * fix help for naked super command

OK (though I couldn't quite make out from the code what is actually
changing)

>   * return a Doc from subusage

OK

>   * slightly improve the (top level) usage text

OK

>   * autoformat help for help
>   * cleanup import lists in D.UI.Commands.Help
>   * minor code cleanups in D.UI.Commands.Help.helpCmd
>   * autoformat help for optimize and its subcommands
>   * autoformat help for initialize
>   * cleanup import lists in Darcs.UI.Commands.Init

All OK.

__________________________________
Darcs bug tracker <bugs at darcs.net>
<http://bugs.darcs.net/patch2043>
__________________________________