11 patches for repository http://darcs.net:

Continuing the effort to divorce the documentation and help text
from the rest of the source code.  Is this the way to go in principle?

Mostly sending this because I tend to work on it in bits and bobs
and then find myself very out of date, and have to spend a lot of
time rebasing.  So maybe I should give you what I have now in case
I flake out and wander off again.

Sat Sep 15 10:23:20 BST 2012  Eric Kow <kowey@darcs.net>
  * Infrastructure to convert markdown files in doc to long help text.
  
  The aim is to make the documentation easier to maintain by putting it
  all in one place, using one format.  This change brings us closer to
  the idea of documentation being in its own tree apart from the source
  code while still avoiding some duplication between the manual and the
  online help text.

Sat Sep 29 09:13:25 BST 2012  Eric Kow <kowey@darcs.net>
  * Use Printer.Doc in prompts.
  
  This allows us to get closer to converge user messages to Doc.

Sat Sep 29 09:13:32 BST 2012  Eric Kow <kowey@darcs.net>
  * Move darcs send help block to doc dir.

Sat Sep 29 09:13:35 BST 2012  Eric Kow <kowey@darcs.net>
  * Move darcs whatsnew messages to doc and Darcs.UI.Message.WhatsNew.

Sat Sep 29 10:53:32 BST 2012  Eric Kow <kowey@darcs.net>
  * Reindent and slightly tidy Darcs.UI.Commands.Send.

Sat Sep 29 13:48:40 BST 2012  Eric Kow <kowey@darcs.net>
  * Move darcs revert messages to doc and Darcs.UI.Message.Revert.

Sat Sep 29 13:48:48 BST 2012  Eric Kow <kowey@darcs.net>
  * Style/Tidy Darcs.UI.Commands.Revert.

Sat Sep 29 14:26:44 BST 2012  Eric Kow <kowey@darcs.net>
  * Move (amend-)record messages to doc and Darcs.UI.Message.

Sat Sep 29 16:40:27 BST 2012  Eric Kow <kowey@darcs.net>
  * Move darcs add messages to doc and Darcs.UI.Message.

Sat Sep 29 16:53:14 BST 2012  Eric Kow <kowey@darcs.net>
  * Move obliterate/unpull/unrecord messages to doc and Darcs.UI.Message.

Sat Sep 29 17:58:12 BST 2012  Eric Kow <kowey@darcs.net>
  * Move push messages to doc and Darcs.UI.Message.

Attachments

• infrastructure-to-convert-markdown-files-in-doc-to-long-help-text_.dpatch
• patch-preview.txt
• unnamed

Sounds like a valuable project. Thanks for working on it, Eric!

Should this be screened or not? :-)

I don't have particularly strong opinions about where the help text should 
be. What are the pros and cons?

I am in favour of this change. Maintaining help texts inside the source
code is horrible mainly due to Haskell's poor support for multiline
strings. Disclaimer: I haven't looked closely at the changes. I think it
is sad we did not screen this immediately. Eric, could you be bothered
to re-base them again (sorry!) in case the others agree?

Hi Ben,

I'm afraid I'm still having trouble getting time back to work on this for
now.
But I have the hope of possibly making time for Darcs next year.

I'd be happy for anybody else to have a look, or make this be the thing I
start with.

Cheers,

Eric

On Fri Nov 14 2014 at 12:53:52 AM Ben Franksen <bugs@darcs.net> wrote:

>
> Ben Franksen <benjamin.franksen@helmholtz-berlin.de> added the comment:
>
> I am in favour of this change. Maintaining help texts inside the source
> code is horrible mainly due to Haskell's poor support for multiline
> strings. Disclaimer: I haven't looked closely at the changes. I think it
> is sad we did not screen this immediately. Eric, could you be bothered
> to re-base them again (sorry!) in case the others agree?
>
> __________________________________
> Darcs bug tracker <bugs@darcs.net>
> <http://bugs.darcs.net/patch953>
> __________________________________
> _______________________________________________
> darcs-devel mailing list
> darcs-devel@darcs.net
> http://lists.osuosl.org/mailman/listinfo/darcs-devel
>

Attachments

• unnamed

I am in the process of rebasing these changes to the HEAD.

Eric, the file src/Darcs/UI/Message/Unrecord.hs is missing, I guess you
forgot to add it. Could you send the missing file, please?

I am not sure I like the idea of a Darcs.UI.Message hierarchy as it is
now. It makes things a little more complicated, and currently we only
use it for the Send command.

I propose to revert that change until we really want to do something
about darcs' messages as a whole, with a design that would also enable
to translate the message strings to other languages.

On a related note, in the past couple of years we decided to tackle the
hardcoded-help-vs-external-docs problem by issue a "darcs help markdown"
command that outputs a reference of all the commands, ready to be
inserted in a manual and/or the wiki.



See also for context:

* http://bugs.darcs.net/patch912
* http://bugs.darcs.net/patch929

I agree that we should either do this fully or not at all.

I'm attaching the following patch, will wait a couple of days before
screening it in case someone else disagrees:

patch 6553eff32c9f988810a53471f1f71f333f9a9cb9
Author: Guillaume Hoffmann <guillaumh@gmail.com>
Date:   Fri Feb  9 14:12:18 -03 2018
  * move back strings from Darcs.UI.Message.Send to Darcs.UI.Commands.Send

Attachments

• move-back-strings-from-darcs_ui_message_send-to-darcs_ui_commands_send.dpatch

No disagreement from me.

Let us screen this then.

Self-accept