[darcs-users] another confusion re: command names

[Aggelos Economopoulos]

On Saturday 08 May 2004 14:49, David Roundy wrote:
> On Thu, May 06, 2004 at 11:24:39AM -0400, zooko at zooko.com wrote:
> > I'm sure David is grateful that I'm so dense, because this will help him
> > find parts of the user experience which are troublesome to dense people
> > before he releases 1.0 and comes into contact with a great many more
> > dense people.
> >
> > Today's confusion was that it took several hours and much discussion
> > before I finally got it through my head that "unpull" could be the
> > command to remove a patch from my local repo.  Since in my mind "pull"
> > means "fetch patches from other repo and apply them to local repo", I
> > couldn't believe that "unpull" didn't somehow involve exchanging
> > information from some other repo.
>
> I've added a blurb to the docs on the naming of unpull (and the fact that
> it doesn't actually require the patch to have been pulled) to the docs.
> Let me know if it's not entirely clear (or if it's poorly worded--I wrote
> it pretty quickly).
>
> > By the way, I had previously been doing "unpull" by "unrecord; revert".
>
> This is what I hope that new users will do.  When you unrecord and then
> revert, you're much less likely to accidentally delete a change you made
> and not be able to get it back (especially since unrevert exists).
>
> The intention of this "interesting" naming convention is that people who
> don't understand exactly how unpull and unrecord differ (which is everyone
> at first) will not end up accidentally using unpull when they want
> unrecord, and losing their precious data.  Then when they have that "aha"
> moment when they see that unpull is like an unrecord that also reverts the
> working directory (and also understand what this means), they can start
> using unpull instead of "unrecord; revert".
>
> Of course, the documentation should make this "aha" moment come as soon as
> possible, which I don't think it was really doing.  The --help text doesn't
> have that goal (currently)--it is mostly designed to prevent people from
> using unpull if they don't understand it.

While on the subject on documentation, is this table accurate and, if so, do 
you think something along these lines would help reduce the confusion if it 
were added to the manual?

(fixed-width font recommended)

			affects
		repo		wdir
--------------------------------------
pull		yes		yes
apply		yes		yes[0]
rollback	yes		no
unrecord	yes		no
unpull		yes		yes
revert		no		yes
unrevert	no		yes

[0] unless --no-resolve-conflicts is given

Thanks,
Aggelos