[darcs-users] darcs patch: Partially rewrite "darcs annotate" help. (and 3 more)

[Eric Kow]

On Mon, Sep 21, 2009 at 00:27:23 +1000, Trent W.Buck wrote:
> Sun Sep 20 20:23:14 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Partially rewrite "darcs annotate" help.
> 
> Sun Sep 20 21:58:24 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Partially rewrite "darcs apply" help.

I've applied these two, thanks!

> Sun Sep 20 23:14:02 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Rewrite $DARCS_EMAIL documentation.

I had a doubt about this one, so I did not apply it, nor the
dependency below.

> Mon Sep 21 00:06:08 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Partially rewrite "darcs record" help.

Partially rewrite "darcs annotate" help.
----------------------------------------
> Trent W. Buck <trentbuck at gmail.com>**20090920102314
>  Ignore-this: b6bc982424ac641c35085f0a0c6bb97f
> ] hunk ./src/Darcs/Commands/Annotate.lhs 69
>  
>  annotate_help :: String
>  annotate_help =
> - "Annotate displays which patches created or last modified a directory\n"++
> - "file or line. It can also display the contents of a particular patch\n"++
> - "in darcs format.\n"
> + "The `darcs annotate' command provides two unrelated operations.  When\n" ++
> + "called on a file, it will find the patch that last modified each line\n" ++
> + "in that file.  When called on a patch (e.g. using --patch), it will\n" ++
> + "print the internal representation of that patch.\n" ++
> + "\n" ++
> + "The --summary option will result in a summarized patch annotation,\n" ++
> + "similar to `darcs whatsnew'.  It has no effect on file annotations.\n" ++
> + "\n" ++
> + "By default, output is in a human-readable format.  The --xml-output\n" ++
> + "option can be used to generate output for machine postprocessing.\n"

This is a nice improvement.

> +%% FIXME: AFAICT -u does nothing.  Remove it from anno's options?
> +%% --twb, 2009-09-20
>  Giving the \verb!--unified! flag implies \verb!--human-readable!, and causes
>  the output to remain in a darcs-specific format that is similar to that produced
>  by \verb!diff --unified!.

--unified works for patches.  I recommend removing the comment (sooner rather
than later lest we forget and confuse ourselves)

darcs annotate -p 942 -u

  [Also test for apply posthook in issue942.
  Eric Kow <kowey at darcs.net>**20090930221536
   Ignore-this: b716d577e2f9423e03dc30d9954c6320
  ] hunk ./tests/issue942_push_apply_prehook.sh 3
   #!/usr/bin/env bash
   ## Test for issue942 - remote apply prehook not invoked on darcs push
  +## We also test for posthooks along the way even though that's not part
  +## of the issue.
   ##
   ## Copyright (C) 2009 Eric Kow <kowey at darcs.net>
   ##

... etc

Partially rewrite "darcs apply" help.
-------------------------------------
> + "If the `--reply noreply at example.net' option is used, and the bundle is\n" ++
> + "attached to an email, Darcs will send a report (indicating success or\n" ++
> + "failure) to the sender of the bundle (the To field).  The argument to\n" ++
> + "noreply is the address the report will appear to originate FROM.\n" ++
> + "\n" ++
> + "The --cc option will cause the report to be CC'd to another address,\n" ++
> + "for example `--cc reports at lists.example.net,admin at lists.example.net'.\n" ++
> + "Using --cc without --reply is undefined.\n" ++

commits at lists.example.net might be nice a useful example

> + "\n" ++
> + "If gpg(1) is installed, you can use `--verify pubring.gpg' to reject\n" ++
> + "bundles that aren't signed by a key in pubring.gpg.\n" ++
> + "\n" ++
> + "If --test is supplied and a test is defined (see `darcs setpref'), the\n" ++
> + "bundle will be rejected if the test fails after applying it.  In that\n" ++
> + "case, the rejection email from --reply will include the test output.\n"

The new text is snappier, thanks.

Incidentally, have you ever considered using unlines to write this?
  
> -When used in combination with the \verb!--verify! option, the
> -\verb!--reply! option allows for a nice pushable repository.  When these
> -two options are used together, any patches that don't pass the verify will
> -be forwarded to the \verb!FROM! address of the \verb!--reply! option.  This
> -allows you to set up a repository so that anyone who is authorized can push
> -to it and have it automatically applied, but if a stranger pushes to it,
> -the patch will be forwarded to you.  Please (for your own sake!)\ be certain
> -that the \verb!--reply FROM! address is different from the one used to send
> -patches to a pushable repository, since otherwise an unsigned patch will be
> -forwarded to the repository in an infinite loop.

I guess this would be for people trying to have some sort automatic
procmail with darcs apply setup.  Perhaps it would be a good idea for
this sort of thing to go on the wiki instead?

Incidentally, I always use darcs apply --interactive and would support it becoming
the default.

A very easy bug to fix
  http://bugs.darcs.net/issue1633
although much easier if we had flags rationalisation

Rewrite $DARCS_EMAIL documentation.
-----------------------------------
> -          writeFile (darcsdir++"/prefs/author") add
> +          writeFile (darcsdir ++ "/prefs/author") $

I guess (</>) would have been good here

> +                    unlines ["# " ++ line | line <- fileHelpAuthor] ++ add

Does this actually work?  I get the impression from get_easy_author that this
would not have the desired effect, that the author would be #foo

Perhaps something like this would be clearer

  hint = unlines (map ("# " ++) fileHelpAuthor)

writeFile $ hint ++ "\n" ++ add

Partially rewrite "darcs record" help.
--------------------------------------
> -commit_description =
> - "Does not actually do anything, but offers advice on saving changes"
> +commit_description = "Redirect the user to record, push or send."

Better.
  
> -\label{DARCS_EDITOR}
> -Finally, each changeset should have a full log (which may be empty).  This
> -log is for detailed notes which are too lengthy to fit in the name.  If you
> -answer that you do want to create a comment file, darcs will open an editor
> -so that you can enter the comment in.  The choice of editor proceeds as
> -follows.  If one of the \verb!$DARCS_EDITOR!, \verb!$VISUAL! or
> -\verb!$EDITOR! environment variables is defined, its value is used (with
> -precedence proceeding in the order listed).  If not, ``vi'', ``emacs'',
> -``emacs~-nw'' and ``nano'' are tried in that order.

Is this information lost?  Apologies if I'm just not reading carefully enough.

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20091002/a7d31723/attachment.pgp>