This is a large an pretty invasive bundle touching many code lines in many
files. However, most of the changes are simple and none of them change
functionality other than the help output and perhaps the formatting of some
error or warning messages.

A few remarks may be in order:

 * The naming and calling convention of the formatting functions (wrapText,
   formatWords, formatText) could be improved i.e. made more uniform and
   intuitive.
 * The line length is currently hard-coded as 80; it would be better to
   query that from the terminal, if we have one, and use the 80 only as a
   fallback if stdout is not a terminal. In practice this will require using
   a "global variable" i.e. unsafePerformIO.
 * Formatting currently supports only plain paragraph filling. Indented
   "literal" text (e.g. blocks of shell commands) and bullet lists must be
   excluded from being autoformatted, which complicates the construction of
   some of the help texts.
 * Not all of the help texts are autoformatted yet. I tried to include
   enough commands to encourage contributors to follow the new scheme,
   rather than the legacy way of formatting the text manually.

Fixing these imperfections is left for future work ;-)

The patches

  * remove initial blurb from the manpage

and

  * extend the description in the manpage

should be regarded as a unit: the second replaces the blurb with (IMHO) more
useful conceptual information.

Similarly,

  * fix formatting of manpage

follows up on

  * generate the manpage as a Doc, rather than [String]

Finally, all the

  * autoformat help for ...
  
patches explicitly depend on

  * improve support for autoformatting help texts

but of course it is hard to keep this up.


39 patches for repository http://darcs.net/screened:

patch 7ed208bc404fb1fe1291a1ff8bd3e2d56e63b223
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sat Jul  4 13:40:39 CEST 2020
  * remove initial blurb from the manpage
  
  Man pages serve as technical references, not to discuss the merits a program
  might have or not have.

patch a248ecd630ea4020d5675fdf8637ade7a8a61944
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jun 21 11:38:10 CEST 2020
  * generate the manpage as a Doc, rather than [String]

patch 611790328f6e582f22338476fd6f2be0029649d1
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sat Jul  4 15:16:31 CEST 2020
  * remove an obsolete comment in D.UI.Commands.Help
  
  The ".br" directive is not listed as an extension by man 7 groff_diff.

patch 2919bcd56acf880d2dfb40f5c7b2ec6cf6da6e9c
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sat Jul  4 15:11:17 CEST 2020
  * extend the description in the manpage

patch 81b3b94785d95426c37bed4dd59ab56948dcdad5
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 12:17:02 CEST 2020
  * retype commandHelp from String to Doc
  
  This is a first step toward a cleaner approach to formatting the help
  output. We do have our own pretty printing library, so we should use it.

patch 15a011b89bc7d832939d44074fec993554ad3794
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sat Jul  4 17:39:29 CEST 2020
  * fix docs for D.UI.Commands.Help.manpage

patch 966393464bd3fc01f762c6803869ee743fc2a280
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 13:00:48 CEST 2020
  * streamline module haddocks for Darcs.Util.Printer
  
  Most of the deleted text was completely outdated information.

patch f709640792f946db946243ee57257f154b7ef1ce
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 14:29:59 CEST 2020
  * remove module Darcs.Util.Text
  
  sentence, pathlist, formatText: moved to Darcs.Util.Printer
  breakCommand: moved to a local function in Darcs.Util.Ssh
  chompTrailingNewline: moved to Darcs.UI.RunCommand
  showCommandLine: simplified and moved to Darcs.Util.Ssh, inlined in
    Darcs.UI.External (it is only used for debug messages)
  
  The idea here is to move away from manipulating Strings for textual output
  toward more consistently using Darcs.Util.Printer.Doc.

patch 06fbed658c45933c1acc86d8fcf4d4bbd1deb579
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 00:13:18 CEST 2020
  * improve support for autoformatting help texts
  
  This introduced an operator $+$ (replaces vplus) and function formatWords.

patch a76d66d41cd31b2628a7da4a43e71e6c3a2fdfdd
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 20:57:51 CEST 2020
  * autoformat help for clone, push, pull, and send

patch 4279c6ae92274d03ab9cfc26f73c58db55a63631
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 23:55:19 CEST 2020
  * autoformat help for record

patch 98b44a22f280f67f2c734125abb1f671aa2964aa
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 23:06:36 CEST 2020
  * autoformat help for history editing commands
  
  These are: amend, obliterate, unrecord, as well as rebase suspend, rebase
  apply, and rebase pull. This patch also factors out a common help text for
  history editing commands, including the previously under-documented
  --not-in-remote option.

patch c5c724b825936523f13c5b303dd6ad68ec246ad5
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 21:15:13 CEST 2020
  * autoformat help for log

patch 03a80691c058692645b4da2f6f664ce3e6704c8f
Author: Ben Franksen <ben.franksen@online.de>
Date:   Sun Jul  5 21:07:29 CEST 2020
  * autoformat help for apply

patch af0eabb900005db9fd6dff699abda5fff4b7f024
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 00:44:45 CEST 2020
  * fix formatting of manpage
  
  The autoformatted help texts have no trailing newline, so we should use vsep
  to concatenate the command sections.

patch 5a29f1ee8ed3ed0bf84343a25bbea5e86fcea862
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 09:21:32 CEST 2020
  * remove escaping of '-' and '\' when generating the manpage
  
  I could not find any documentation that says these characters must be
  escaped when generating a man document. So I just tried without and
  the result looks fine.

patch 47804b549d85b3301c3f5d1d1b2ef94517465df7
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 09:33:06 CEST 2020
  * autoformat help for whatsnew

patch 8cc9cbcc860d94d8198121ca622ae28edb8c72d8
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 01:06:20 CEST 2020
  * fix manpage formatting of bullet lists in help Docs
  
  To preserve layout i.e. disable any paragraph formatting by nroff, text must
  be indented.

patch 6d265067aacf766be0eb0cfc962478e9475c54c0
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 13:59:47 CEST 2020
  * remove unused function usageInfo from D.UI.Usage
  
  This also removes the obsolete module header docs.

patch 8f4710b382cac83441a86a18014e9c73efb5d1c3
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 14:02:30 CEST 2020
  * remove export of formatOptions from Darcs.UI.Usage

patch 350ea5586aeb0bc3898f4343fd72845265171a55
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:05:03 CEST 2020
  * move debugging options to the end of the advanced options

patch 1bcdeb157c647e85ffd81b9a4b03d1db7a77521f
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:34:02 CEST 2020
  * shorten the help for alias commands
  
  The default help text for an alias now refers the user to the other command.
  Directly including the help for the other command may can be misleading.

patch 5d004b301b9983c6f784a87d14d0c608e2404a41
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:43:00 CEST 2020
  * fix docs and description for the status command

patch b121e72a6c8c6375335e44f31ed2e8d0e548a31e
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:43:35 CEST 2020
  * add extended help for rebase super command
  
  This is intended to give an overview of how darcs rebase works.

patch 171801b031ff02f769e50d17133d5cd1b4ed1cb4
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:45:36 CEST 2020
  * remove historyEditHelp from rebase apply/pull
  
  While these commands do edit the history, they do not support common flags
  like --not-in-remote, so including the full historyEditHelp may be
  misleading.

patch e9d31d05391cb88eb3914a11bef3382945f99310
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:49:32 CEST 2020
  * simplify a logical expression

patch 9abba9f01db89d6d25e838e1ac650a13c19fb902
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:50:23 CEST 2020
  * include help for super commands in the man page

patch fcc88e564e3acc9a3bbeb3f4369fd9a745a7b88e
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:51:28 CEST 2020
  * remove some extraneous spaces

patch 2876456a350c21618c912dbc023a0fccd43e28b8
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:52:00 CEST 2020
  * slightly extend help text for darcs show and darcs convert

patch ac677777b536ca6a696d234a943a4213fd17d4bf
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 15:58:05 CEST 2020
  * 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.

patch 3eda19e50d8ee5c13226c59bbbbb985fdac720c6
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 16:56:05 CEST 2020
  * fix help for naked super command

patch 391250d443524897b9afdd9a247b7252759dd43a
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 16:58:49 CEST 2020
  * return a Doc from subusage
  
  This includes a few refactors in Darcs.UI.RunCommand to format error
  messages using Darcs.Util.Printer.

patch 07309d00351c7f3fe12e52df38664b9d94c3e2e9
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 14:13:34 CEST 2020
  * slightly improve the (top level) usage text

patch b84c4633e5e43ba9038e8d8081de8687de8adb5a
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 17:13:14 CEST 2020
  * autoformat help for help

patch 7f5953ba1581cd79d9b9d1e937e9af753e421758
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 20:55:40 CEST 2020
  * cleanup import lists in D.UI.Commands.Help

patch 8e3dbd29951a4e7bcf9b417f289a1586f049efe9
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 20:57:07 CEST 2020
  * minor code cleanups in D.UI.Commands.Help.helpCmd

patch 9c6b14dea9702b84e198109690f9bafb422912ca
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 21:53:39 CEST 2020
  * autoformat help for optimize and its subcommands

patch a00d328371245eec960515a9d40c61c3901007fa
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 22:34:31 CEST 2020
  * autoformat help for initialize

patch acb871eac9f990f04af16fa6ca78e1b29915b86d
Author: Ben Franksen <ben.franksen@online.de>
Date:   Mon Jul  6 22:35:03 CEST 2020
  * cleanup import lists in Darcs.UI.Commands.Init

Attachments

• patch-preview.txt
• remove-initial-blurb-from-the-manpage.dpatch
• unnamed

I intend this bundle to go into darcs-2.16. I have not screened it yet 
because it is large and may conflict with WIP that you haven't sent 
yet. If you have anything that you think should go into 2.16 but isn't 
finished, you might want to still send it as a draft before I screen 
this one, so I can help sorting out possible conflicts.

I don't have anything pending for 2.16, so go ahead and screen if it's
otherwise ready.

Partial review:

On 07/07/2020 11:26, Ben Franksen wrote:

> The patches
> 
>   * remove initial blurb from the manpage
> 
> and
> 
>   * extend the description in the manpage
> 
> should be regarded as a unit: the second replaces the blurb with (IMHO) more
> useful conceptual information.

Agreed.

>   * generate the manpage as a Doc, rather than [String]

Fine.


>   * remove an obsolete comment in D.UI.Commands.Help
>   
>   The ".br" directive is not listed as an extension by man 7 groff_diff.

Fine.

>   * extend the description in the manpage

Fine.

>   * retype commandHelp from String to Doc

Fine.

>   * fix docs for D.UI.Commands.Help.manpage

Fine.

>   * streamline module haddocks for Darcs.Util.Printer
>   
>   Most of the deleted text was completely outdated information.

OK. I don't think I ever read it :-)

>   * remove module Darcs.Util.Text

OK

>   * improve support for autoformatting help texts

OK

>   * autoformat help for clone, push, pull, and send
>   * autoformat help for record
>   * autoformat help for history editing commands
>   * autoformat help for log
>   * autoformat help for apply

OK - I haven't read through all the changes in detail.

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

>>   * fix help for naked super command
> 
> OK (though I couldn't quite make out from the code what is actually
> changing)

The difference is subtle. 'darcs help optimize' no longer says

Usage: darcs optimize [OPTION]...

but

Usage: darcs optimize SUBCOMMAND [OPTION]...

Also, the help text for the standard command options (--help, --disable,
--list-options) is no longer displayed. This is debatable. On the one
hand these options are accepted for a naked supercommand so not listing
them is a factual ommission. On the other hand, these standard options
are boring and distract the reader from the more interesting conceptual
explanations that follow. I can easily put them back if you think they
should be listed.

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

I think that's a good idea, but I'd say we postpone this until after 2.16.