Hi Stephen,
I'll snip all the small edits (s/some/many/, s/aobut our/about your/)
from the email, but I did fix them in my local repository. Thanks for
the suggestions.
Stephen J. Turnbull wrote:
> +- **Smart** - Darcs understands dependencies between patches. You can't
delete
> +a file before you add it. You can't rename a function before you write it.
The
This isn't true. It's quite possible to write top-down, invoking an
as yet undefined function.
... [ and then rename it ]
Ok. "Darcs understands dependencies between patches. You can't rename
a file before you add it. You can't delete line before you write it."
> +rules Darcs uses are simple but powerful. Darcs understands when two patches
> +can be reordered and when they can't. Darcs uses dependencies to know when
there
> +is a conflict (e.g. Bob can't rename file foo.txt to bar.txt if Alice
already
> +renamed it to something else). This means that when Darcs finds a conflict,
it
> +is likely to be a genuine conflict that requires a human to resolve (Alice
and
> +Bob must settle on a name for the file).
Something says "this needs work" to me. Specifically, you mention
"conflict" "too many" times, and do not focus enough on how Darcs
normally makes things go smoothly.
Well... I was trying to talk about how it finds conflicts. How about this:
"Darcs understands when two patches can be reordered and when they can't
(e.g. Bob can't rename file foo.txt to bar.txt if Alice already rename
it to something else). Understanding patch dependencies means that Darcs
will generally only issue a warning when there is a genuine conflict
(Alice and Bob must agree on a name)."
It says roughly the same thing, but I think it gives the feeling that
conflicts are rare.
> +You don't need to know Patch Theory to use Darcs. As a user, everything you
> +need to know is in the [Patch Reordering](../Patch Reordering) page. That
said,
Do users really need to know about patch reordering? The only thing
that would be useful to new users is quite high level: knowing that
"darcs pull A; darcs pull B" has exactly the same semantics as "darcs
pull B; darcs pull A". But that's not patch reordering, that's "pull
reordering".
I call that patch reordering in the documentation. If you look at the
'Patch Reordering' page, it is indeed fairly high level. Everything in
it is something I honestly think is relevant and useful to user:
1. First I explain that you apply patches in any order but Darcs may
need to "adapt" it.
2. Then I give two examples. One is a Hunk-Hunk merge which is the most
common merge. The other is an example of why Darcs is easy to use
("Darcs thinks the way you do").
> +if you are keen to know more about the theory behind Darcs, we are more than
> +happy to tell you all about it.
> hunk ./Patch\32\Theory/Index.page 8
URLs to the patch theory appendix and/or (maybe better) the mailing
list? Or would that be too cluttered?
The index page will have a lot more information in the future. The
information in the appendix will make its way to the wiki eventually.
Adding a section on 'where to get help' (IRC and mailing list) is a good
idea. I just added it to my local copy. It'll be there in the next revision.
> +the way you do. You think in terms of "I want feature X" and so does Darcs.
Very well put. Some people may disagree (at least when constrained to
work in their formal processes), but those folks are unlikely to love
Darcs no matter what we do.
:-)
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
